day-toolkit-appkit 0.6.1

// Copyright © The Daybrite Project
// SPDX-License-Identifier: MPL-2.0

//! day-toolkit-appkit: the macos-appkit backend (DESIGN.md §9). objc2, pure Rust, no shim.
//!
//! `Handle = Retained<NSView>`. Containers are flipped `NSView`s (top-left origin, so Day's
//! frames apply directly and survive diffing). One custom target class (`DayTarget`) forwards
//! target/action + text-delegate callbacks into the Day event sink, node-id keyed (§8.3).

#![allow(unused_unsafe)]
#![cfg(target_os = "macos")]

mod controls;

mod applications;
mod nav_progress;

use std::any::Any;
use std::cell::{Cell, RefCell};
use std::collections::HashMap;
use std::rc::Rc;

use linkme::distributed_slice;
use objc2::Message as _;
use objc2::rc::Retained;
use objc2::runtime::{NSObjectProtocol, ProtocolObject};
use objc2::{
    AllocAnyThread, DefinedClass, MainThreadMarker, MainThreadOnly, define_class, msg_send, sel,
};
use objc2_app_kit::NSAccessibility as _;
use objc2_app_kit::NSAppearanceCustomization as _;
use objc2_app_kit::NSDraggingInfo as _;
use objc2_app_kit::NSSplitViewDelegate;
use objc2_app_kit::NSTextContent as _;
use objc2_app_kit::NSUserInterfaceItemIdentification as _;
use objc2_app_kit::{
    NSAffineTransformNSAppKitAdditions, NSClickGestureRecognizer, NSGestureRecognizer,
    NSGestureRecognizerState, NSPanGestureRecognizer, NSPasteboard,
};
use objc2_app_kit::{
    NSAnimationContext, NSApplication, NSApplicationActivationPolicy, NSBackingStoreType,
    NSBitmapImageFileType, NSBox, NSBoxType, NSButton, NSColor, NSControl, NSControlStateValueOff,
    NSControlStateValueOn, NSControlTextEditingDelegate, NSCursor, NSCursorFrameResizeDirections,
    NSCursorFrameResizePosition, NSEvent, NSEventModifierFlags, NSEventType, NSFont,
    NSGraphicsContext, NSLineBreakMode, NSMenu, NSMenuItem, NSProgressIndicator,
    NSProgressIndicatorStyle, NSResponder, NSScrollView, NSSecureTextField, NSSlider, NSSwitch,
    NSTabViewDelegate, NSText, NSTextField, NSTextFieldDelegate, NSTextMovement,
    NSTextMovementUserInfoKey, NSTrackingArea, NSTrackingAreaOptions, NSView, NSWindow,
    NSWindowDelegate, NSWindowStyleMask,
};
use objc2_app_kit::{
    NSApplicationDidBecomeActiveNotification, NSApplicationWillResignActiveNotification,
    NSApplicationWillTerminateNotification,
};
use objc2_app_kit::{
    NSOutlineViewDataSource, NSOutlineViewDelegate, NSTextDelegate, NSTextView, NSTextViewDelegate,
};
use objc2_app_kit::{NSTableColumn, NSTableView, NSTableViewDataSource, NSTableViewDelegate};
use objc2_core_foundation::CGAffineTransform;
use objc2_foundation::{
    NSAffineTransform, NSAffineTransformStruct, NSArray, NSData, NSDictionary, NSNotification,
    NSNumber, NSObject, NSPoint, NSRect, NSSize, NSString,
};
use objc2_quartz_core::{
    CAMediaTimingFunction, CATransaction, kCAMediaTimingFunctionEaseIn,
    kCAMediaTimingFunctionEaseInEaseOut, kCAMediaTimingFunctionEaseOut,
    kCAMediaTimingFunctionLinear,
};

use day_spec::ffi_guard;
use day_spec::present;
use day_spec::props::*;
use day_spec::sidetable::SideTable;
use day_spec::{
    A11yProps, AnimSpec, Builtin, Cap, Cursor, Curve, DrawOp, Event, EventSink, Font, InputPurpose,
    InputTraits, ListSource, MoveVerdict, NodeId, PieceKind, Platform, Point, Proposal, RawHandle,
    Rect, Registry, Renderer, Size, Support, Toolkit, Transform, TreeSource, WINDOW_NODE,
    WindowOptions, kinds, props_of,
};

pub type Handle = Retained<NSView>;

/// Icon resolution for a piece renderer's own `NSToolbar` items (see `toolbar::image_for`).
pub use toolbar::image_for as toolbar_image;

// Built-in leaf pieces split into modules (moved in from their satellite crates 2026-07).
mod dock;
mod documents;
mod frame;
mod picker;
mod status_item;
mod textarea;
mod toolbar;
mod transfer;
mod window_chrome;
use objc2_app_kit::NSDraggingSource;

pub mod ext;
pub use ext::*;

// ---------------------------------------------------------------------------
// Event plumbing: node-id keyed sink, thread-local (single UI thread)
// ---------------------------------------------------------------------------

/// The day-core event sink (node-id keyed).
type Sink = Rc<dyn Fn(NodeId, Event)>;

day_core::tls_group! {
    static SINK: RefCell<Option<Sink>> = const { RefCell::new(None) };
    /// Keeps each control's `DayTarget` alive (target/action holds it weakly).
    static TARGETS: RefCell<HashMap<usize, Retained<DayTarget>>> = RefCell::new(HashMap::new());
    /// The style each button currently carries, keyed by its view pointer.
    ///
    /// Needed because a tinted title is an attributed string (see `set_button_title`), and
    /// `ButtonPatch::Title` would otherwise replace it with a plain one and lose the color.
    static BUTTON_STYLES: RefCell<HashMap<usize, day_spec::props::ButtonStyleSpec>> =
        RefCell::new(HashMap::new());
    /// Original template images, retained across tint changes and swept on view release.
    static BUTTON_IMAGES: SideTable<Retained<objc2_app_kit::NSImage>> = SideTable::new();
    /// Each button's selected state (`ButtonProps::selected`), keyed by its view pointer: what
    /// the `action:` handler restores after a click toggles a push-on/push-off button, and the
    /// buttons whose `state` `read_native` reports as `checked`.
    static BUTTON_SELECTED: RefCell<HashMap<usize, bool>> = RefCell::new(HashMap::new());

    /// Canvas ptr → its display list. A [`SideTable`], so the release sweep reclaims it
    /// (replay inserted but nothing ever removed).
    static OPS: SideTable<Vec<DrawOp>> = SideTable::new();
    /// Views the app gave an accessibility label (`set_a11y`): a button's title change must then
    /// leave the label alone (`apply_button_content`). Swept on release like the other tables.
    static APP_LABELED: SideTable<()> = SideTable::new();
    /// How each image view renders its glyph (docs/vectors.md "Tint", "Template"): whether it
    /// was realized as a template, and whether a tint is on it now. Template rendering is a
    /// property of the NSImage, so a source swap has to re-apply it, and a tint patch of `None`
    /// keeps a template in the neutral tint rather than returning to the authored art. Swept
    /// on release.
    static IMAGE_MODES: SideTable<ImageMode> = SideTable::new();
    /// Each transformed view's `Transform` (`set_transform`). AppKit owns a layer-backed view's
    /// layer geometry and re-syncs it from the view, so a transform written into the layer
    /// never showed. It is expressed in the view's own geometry instead (`apply_geometry`).
    static TRANSFORMS: SideTable<Transform> = SideTable::new();
    /// Each view's frame as Day laid it out, before any translation, so a translation change can
    /// move the view without waiting for the next layout.
    static BASE_FRAMES: SideTable<[f64; 4]> = SideTable::new();
    static COVER_SHEETS: SideTable<CoverSheet> = SideTable::new();
    /// View ptr → node for `GestureKind::Pan` (docs/shapes.md): macOS pans arrive as trackpad
    /// scroll events, so `DayCanvas::scrollWheel:` reports them here instead of a recognizer.
    static PAN_NODES: SideTable<NodeId> = SideTable::new();
    static PAN_MONITOR: RefCell<Option<PanMonitor>> = const { RefCell::new(None) };
    /// View ptr → node for `GestureKind::Hover` (docs/canvas.md "Interaction"). Hover is not a
    /// recognizer on macOS either: it is an `NSTrackingArea` plus the three mouse methods, so
    /// like [`PAN_NODES`] this holds the canvases that asked and `DayCanvas` reports for them.
    static HOVER_NODES: SideTable<NodeId> = SideTable::new();
    /// Canvas view ptr → its node, so the view's own `keyDown:` knows who to report to. Every
    /// canvas is registered at realize (unlike [`PAN_NODES`], which only holds the ones that
    /// asked for a pan) because focus, not a gesture, is what decides who hears a key.
    static KEY_NODES: SideTable<NodeId> = SideTable::new();
    /// Focusable container view ptr → its node (docs/focus.md): `Decorate::focusable` opts a
    /// `DayFlipped` into the canvas contract (accepts first responder, takes focus on a
    /// press, reports both directions, hears the arrows). Empty for every container that
    /// never asked, whose behavior is exactly as before.
    static FOCUSABLE_NODES: SideTable<NodeId> = SideTable::new();

    /// Keeps each view's gesture targets alive + records which gestures are attached (idempotent).
    static GESTURES: RefCell<HashMap<usize, Vec<Retained<DayGesture>>>> =
        RefCell::new(HashMap::new());

    static NAV_STATE: RefCell<HashMap<usize, NavState>> = RefCell::new(HashMap::new());
    /// Handles whose frames are native-owned (nav pages): set_frame skips them.
    static NAV_PAGES: RefCell<std::collections::HashSet<usize>> =
        RefCell::new(std::collections::HashSet::new());
    /// Each nav page's pane, recorded at realize because `insert` sees only handles
    /// (docs/size-classes.md). Identity rather than position: a re-present re-homes the pages
    /// without changing their order, so "index 0 is the sidebar" stops being true the moment a
    /// host can morph. A [`SideTable`]: `remove` clears it on the normal path, and the release
    /// sweep catches a page released without one (a stale entry could mis-pane a recycled ptr).
    static PAGE_PANE: SideTable<day_spec::props::Pane> = SideTable::new();

    static INSPECTOR_STATE: RefCell<HashMap<usize, InspectorState>> = RefCell::new(HashMap::new());
    /// INSPECTOR_PANE ptr → is-panel, recorded at realize because `insert` sees only handles.
    /// A [`SideTable`]: the release sweep drops it with the view.
    static INSPECTOR_PANES: SideTable<bool> = SideTable::new();

    /// Split host (the wrap around an `NSSplitView`, docs/split.md) ptr → its state.
    static SPLIT_STATE: RefCell<HashMap<usize, SplitState>> = RefCell::new(HashMap::new());
    /// SPLIT_PANE ptr → is-second, recorded at realize because `insert` sees only handles.
    static SPLIT_PANES: SideTable<bool> = SideTable::new();

    /// Outline ptr → its data source, for [`DayNavOutlineView::menu_for_event`]'s row lookup.
    /// A [`SideTable`], reclaimed by the outline-keyed auxiliary sweep in `release`: the entry
    /// used to outlive its host, so a recycled outline address served the dead menu's rows.
    static NAV_OUTLINE_MENUS: SideTable<Retained<DayNavMenuData>> = SideTable::new();

    static LIST_STATE: RefCell<HashMap<usize, ListEntry>> = RefCell::new(HashMap::new());
    /// Tree host scroll-view ptr → (outline, data source) (docs/tree.md).
    static TREE_STATE: RefCell<HashMap<usize, TreeEntry>> = RefCell::new(HashMap::new());

    /// `BitmapId` → the decoded image (docs/images.md). Keyed by the id day-core minted, not by
    /// a view pointer: a bitmap outlives any one view and may be drawn by several at once.
    /// Entries leave only through `release_image`, which day-core calls when the app drops its
    /// last `Bitmap` handle.
    static BITMAPS: RefCell<HashMap<u64, AppKitBitmap>> = RefCell::new(HashMap::new());
    /// View ptr → its summon-time context-menu provider (docs/menus.md). Swept on release
    /// via `day_spec::sidetable`.
    static CTX_MENU_FNS: SideTable<day_spec::ContextMenuFn> = SideTable::new();

    /// NAV_MENU scroll-view ptr → (outline, data source) for patches and measure.
    static NAV_MENUS: RefCell<HashMap<usize, NavMenuEntry>> = RefCell::new(HashMap::new());

    /// The app's edit-bridge state (`set_edit_state`), which validateMenuItem consults.
    static EDIT_STATE: std::cell::Cell<day_spec::EditState> =
        const { std::cell::Cell::new(day_spec::EditState { can_cut: false, can_copy: false, can_paste: false, can_select_all: false }) };
    static UNDO_FRONT: std::cell::RefCell<Option<Retained<DayUndoManager>>> =
        const { std::cell::RefCell::new(None) };

    /// Live modal sheets keyed by request id (for programmatic dismissal).
    static PRESENT_ALERTS: RefCell<HashMap<u64, Retained<objc2_app_kit::NSAlert>>> =
        RefCell::new(HashMap::new());
    /// Live file-picker sheets (NSOpenPanel is stored via its NSSavePanel supertype).
    static PRESENT_PANELS: RefCell<HashMap<u64, Retained<objc2_app_kit::NSSavePanel>>> =
        RefCell::new(HashMap::new());

    // NSMenuItem does not retain its target, so one shared target is kept alive for the app's
    // lifetime.
    static MENU_TARGET: std::cell::RefCell<Option<Retained<DayMenuTarget>>> =
        const { std::cell::RefCell::new(None) };
    /// The primary window's content view, for call sites without backend access that must
    /// address the main window specifically (cover re-homing, DAY_DUMP). With secondary
    /// windows open, `app.windows().firstObject()` is arbitrary (docs/windows.md).
    static PRIMARY_CONTENT: std::cell::RefCell<Option<Retained<NSView>>> =
        const { std::cell::RefCell::new(None) };

}

/// Emit an event into day-core's queue (public: external Day Piece renderers use this too).
pub fn emit(id: NodeId, ev: Event) {
    let sink = SINK.with(|s| s.borrow().clone());
    if let Some(sink) = sink {
        sink(id, ev);
    }
}

fn ptr_of(v: &NSView) -> usize {
    (v as *const NSView).cast::<()>() as usize
}

/// An image view's rendering (`IMAGE_MODES`).
#[derive(Clone, Copy)]
struct ImageMode {
    template: bool,
    tinted: bool,
}

impl ImageMode {
    /// Template rendering: the glyph's alpha as a mask, filled with the tint or the neutral
    /// template color.
    fn renders_template(self) -> bool {
        self.template || self.tinted
    }
}

/// A decoded bitmap (docs/images.md), held until day-core drops its last handle.
///
/// The `NSBitmapImageRep` is kept beside the image rather than fetched on demand for two
/// reasons: it is the only thing here that can re-encode to other formats, and it is the only
/// accurate source of pixel dimensions, since `NSImage.size` is in points and reports a @2x
/// asset at half its real width.
struct AppKitBitmap {
    image: Retained<objc2_app_kit::NSImage>,
    rep: Option<Retained<objc2_app_kit::NSBitmapImageRep>>,
    info: day_spec::BitmapInfo,
}

/// Draw a decoded image into a fresh bitmap `scale`× its pixel size, for [`day_spec::EncodeSpec`]'s
/// `fit`.
///
/// 8 bits across 4 samples with alpha is the one layout every writer here accepts, and the only
/// one that carries transparency through a PNG round-trip intact.
fn scaled_rep(
    image: &objc2_app_kit::NSImage,
    pixels: Size,
    scale: f64,
) -> Option<Retained<objc2_app_kit::NSBitmapImageRep>> {
    use objc2::AllocAnyThread as _;
    let w = (pixels.width * scale).round().max(1.0);
    let h = (pixels.height * scale).round().max(1.0);
    let rep = unsafe {
        objc2_app_kit::NSBitmapImageRep::initWithBitmapDataPlanes_pixelsWide_pixelsHigh_bitsPerSample_samplesPerPixel_hasAlpha_isPlanar_colorSpaceName_bytesPerRow_bitsPerPixel(
            objc2_app_kit::NSBitmapImageRep::alloc(),
            std::ptr::null_mut(),
            w as isize,
            h as isize,
            8,
            4,
            true,
            false,
            objc2_app_kit::NSDeviceRGBColorSpace,
            0,
            0,
        )
    }?;
    let ctx = objc2_app_kit::NSGraphicsContext::graphicsContextWithBitmapImageRep(&rep)?;
    NSGraphicsContext::saveGraphicsState_class();
    objc2_app_kit::NSGraphicsContext::setCurrentContext(Some(&ctx));
    unsafe {
        image.drawInRect_fromRect_operation_fraction(
            NSRect::new(NSPoint::new(0.0, 0.0), NSSize::new(w, h)),
            NSRect::ZERO,
            objc2_app_kit::NSCompositingOperation::SourceOver,
            1.0,
        );
    }
    NSGraphicsContext::restoreGraphicsState_class();
    Some(rep)
}

/// Re-encode a decoded bitmap (docs/images.md).
///
/// A free function rather than the duty's body so each refusal reads as an early return instead
/// of another copy of the same emit.
fn encode_bitmap(
    id: day_spec::BitmapId,
    spec: &day_spec::EncodeSpec,
) -> Result<Vec<u8>, day_spec::ImageError> {
    use day_spec::ImageFormat as F;
    use objc2_app_kit::NSBitmapImageFileType as T;
    let file_type = match spec.format {
        F::Png => T::PNG,
        F::Jpeg => T::JPEG,
        F::Tiff => T::TIFF,
        F::Bmp => T::BMP,
        F::Gif => T::GIF,
        // Readable here but not writable: `NSBitmapImageRep` ships no WebP or HEIF writer. That
        // asymmetry is why `encode_formats` exists instead of letting `Cap::ImageEncode` imply
        // that everything decodable is also encodable.
        _ => return Err(day_spec::ImageError::Encode),
    };
    let held = BITMAPS.with(|m| {
        m.borrow()
            .get(&id.0)
            .map(|b| (b.rep.clone(), b.image.clone(), b.info))
    });
    let (rep, image, info) = held.ok_or(day_spec::ImageError::Gone)?;
    let rep = rep.ok_or(day_spec::ImageError::Encode)?;

    // `fit` scales the longest side down first. A box larger than the original is ignored:
    // upscaling on an export path inflates the bytes without adding any detail.
    let rep = match spec.fit {
        Some(fit) if info.pixels.width > 0.0 && info.pixels.height > 0.0 => {
            let scale = (fit.width / info.pixels.width)
                .min(fit.height / info.pixels.height)
                .min(1.0);
            if scale < 1.0 {
                scaled_rep(&image, info.pixels, scale).ok_or(day_spec::ImageError::Encode)?
            } else {
                rep
            }
        }
        _ => rep,
    };

    let props: Retained<NSDictionary<NSString, objc2::runtime::AnyObject>> = match spec.quality {
        // AppKit's own compression-factor property; a lossless writer ignores it.
        Some(q) => {
            let key: &NSString = unsafe { objc2_app_kit::NSImageCompressionFactor };
            let number = NSNumber::new_f64(q.clamp(0.0, 1.0));
            let value: &objc2::runtime::AnyObject = &number;
            NSDictionary::from_slices::<NSString>(&[key], &[value])
        }
        None => NSDictionary::new(),
    };
    let data = unsafe { rep.representationUsingType_properties(file_type, &props) }
        .ok_or(day_spec::ImageError::Encode)?;
    Ok(data.to_vec())
}

/// Replay a display list into the current graphics context. The one painter both the on-screen
/// `DayCanvas` (its `drawRect:`) and the canvas exports run, so the two cannot drift apart
/// (docs/canvas.md "Exporting").
fn paint_ops(ops: &[DrawOp]) {
    for op in ops {
        draw_op(op);
    }
}

/// Paint `ops` into `cg` with a top-left origin and y down, as the flipped `DayCanvas` sees
/// them. `height` is the context's own height in its base units (pixels for a bitmap, points for
/// a PDF page) and `scale` its units per canvas point.
///
/// The CTM flip turns the geometry the right way up; wrapping the context as a FLIPPED
/// `NSGraphicsContext` is what tells AppKit's text and image drawing to keep glyphs and pictures
/// upright inside that flip, exactly as they are in a flipped view's `drawRect:`.
fn paint_flipped(cg: &objc2_core_graphics::CGContext, height: f64, scale: f64, ops: &[DrawOp]) {
    use objc2_core_graphics::CGContext;
    CGContext::save_g_state(Some(cg));
    CGContext::translate_ctm(Some(cg), 0.0, height);
    CGContext::scale_ctm(Some(cg), scale, -scale);
    let ns = NSGraphicsContext::graphicsContextWithCGContext_flipped(cg, true);
    NSGraphicsContext::saveGraphicsState_class();
    NSGraphicsContext::setCurrentContext(Some(&ns));
    paint_ops(ops);
    NSGraphicsContext::restoreGraphicsState_class();
    CGContext::restore_g_state(Some(cg));
}

/// Render a canvas display list offscreen (docs/canvas.md "Exporting"): `export_pixels` of
/// transparent sRGB, premultiplied RGBA, painted at `scale` pixels per point.
///
/// A `CGBitmapContext` rather than `NSGraphicsContext(bitmapImageRep:)`: it carries a real sRGB
/// color space, so the `NSBitmapImageRep` built from its image is tagged sRGB like every canvas
/// color, shows on the display through the same color matching the live canvas gets, and writes
/// that profile into a PNG.
fn render_bitmap_image(
    ops: &[DrawOp],
    size: Size,
    scale: f64,
) -> Result<AppKitBitmap, day_spec::ExportError> {
    use objc2::AllocAnyThread as _;
    use objc2_core_graphics::{
        CGBitmapContextCreate, CGBitmapContextCreateImage, CGColorSpace, CGImageAlphaInfo,
    };
    let failed = |what: &str| day_spec::ExportError::Failed(what.to_string());
    let (pw, ph) = day_spec::export_pixels(size, scale);
    // SAFETY: `kCGColorSpaceSRGB` is an immutable CoreGraphics constant, valid for the process.
    let space = CGColorSpace::with_name(Some(unsafe { objc2_core_graphics::kCGColorSpaceSRGB }))
        .ok_or_else(|| failed("CoreGraphics has no sRGB color space"))?;
    // SAFETY: a null data pointer asks CoreGraphics to allocate (and own) the buffer, and a zero
    // row stride lets it choose one; 8 bits × RGBA premultiplied is a supported layout.
    let cg = unsafe {
        CGBitmapContextCreate(
            std::ptr::null_mut(),
            pw as usize,
            ph as usize,
            8,
            0,
            Some(&space),
            CGImageAlphaInfo::PremultipliedLast.0,
        )
    }
    .ok_or_else(|| {
        day_spec::ExportError::Failed(format!("CGBitmapContextCreate refused {pw}x{ph}"))
    })?;
    // A new bitmap context starts zeroed, which is the transparent background.
    paint_flipped(&cg, ph as f64, scale, ops);
    let cg_image = CGBitmapContextCreateImage(Some(&cg))
        .ok_or_else(|| failed("CGBitmapContextCreateImage returned nothing"))?;
    let rep = unsafe {
        objc2_app_kit::NSBitmapImageRep::initWithCGImage(
            objc2_app_kit::NSBitmapImageRep::alloc(),
            &cg_image,
        )
    };
    // Sized in POINTS, pixels over scale, so the image draws at the drawing's size and stays
    // sharp at `scale`× — the same shape as a staged @2x asset.
    let points = NSSize::new(pw as f64 / scale, ph as f64 / scale);
    unsafe { rep.setSize(points) };
    let image =
        unsafe { objc2_app_kit::NSImage::initWithSize(objc2_app_kit::NSImage::alloc(), points) };
    unsafe { image.addRepresentation(&rep) };
    Ok(AppKitBitmap {
        image,
        rep: Some(rep),
        info: day_spec::BitmapInfo {
            pixels: Size::new(pw as f64, ph as f64),
            scale,
            format: None,
            has_alpha: true,
        },
    })
}

/// Write `pages` as one PDF document (docs/canvas.md "Exporting"): a `CGPDFContext` on a
/// `CGDataConsumer` over memory, one page per drawing with its own media box, the title and
/// author in the document info. Shapes and text stay vector: the same painter draws into the PDF
/// context, and AppKit's string drawing there emits real glyphs from embedded font subsets.
fn render_pdf_bytes(
    pages: &[day_spec::PdfPage],
    info: &day_spec::PdfInfo,
) -> Result<Vec<u8>, day_spec::ExportError> {
    use objc2_core_foundation::{
        CFDictionary, CFMutableData, CFRetained, CFString, CGPoint, CGRect, CGSize,
    };
    use objc2_core_graphics::{CGContext, CGDataConsumer, CGPDFContextClose, CGPDFContextCreate};
    let failed = |what: &str| day_spec::ExportError::Failed(what.to_string());
    let media =
        |size: Size| CGRect::new(CGPoint::new(0.0, 0.0), CGSize::new(size.width, size.height));
    let first = pages.first().ok_or(day_spec::ExportError::Invalid)?;
    let data = CFMutableData::new(None, 0)
        .ok_or_else(|| failed("CFDataCreateMutable returned nothing"))?;
    let consumer = CGDataConsumer::with_cf_data(Some(&data))
        .ok_or_else(|| failed("CGDataConsumerCreateWithCFData returned nothing"))?;

    let mut keys: Vec<&CFString> = Vec::new();
    let mut values: Vec<CFRetained<CFString>> = Vec::new();
    // SAFETY: the auxiliary-info keys are immutable CoreGraphics constants.
    let (title_key, author_key) = unsafe {
        (
            objc2_core_graphics::kCGPDFContextTitle,
            objc2_core_graphics::kCGPDFContextAuthor,
        )
    };
    for (key, value) in [(title_key, &info.title), (author_key, &info.author)] {
        if let Some(value) = value {
            keys.push(key);
            values.push(CFString::from_str(value));
        }
    }
    let values: Vec<&CFString> = values.iter().map(|v| &**v).collect();
    let aux = CFDictionary::<CFString, CFString>::from_slices(&keys, &values);

    let first_box = media(first.size);
    // SAFETY: `first_box` outlives the call, and the dictionary maps the documented
    // auxiliary-info string keys to strings, which is the type those keys take.
    let pdf = unsafe { CGPDFContextCreate(Some(&consumer), &first_box, Some(aux.as_opaque())) }
        .ok_or_else(|| failed("CGPDFContextCreate refused the document"))?;
    for page in pages {
        let page_box = media(page.size);
        // SAFETY: `page_box` outlives the call; in a PDF context it becomes the page's MediaBox.
        unsafe { CGContext::begin_page(Some(&pdf), &page_box) };
        paint_flipped(&pdf, page.size.height, 1.0, &page.ops);
        CGContext::end_page(Some(&pdf));
    }
    // Closing flushes the trailer into the consumer; the bytes are complete only after it.
    CGPDFContextClose(Some(&pdf));
    drop(pdf);
    drop(consumer);
    Ok(data.to_vec())
}

thread_local! {
    /// Each realized list item's current props, by its view: a patch updates one part and the
    /// item is re-dressed from the whole (docs/list.md "List items").
    static LIST_ITEMS: std::cell::RefCell<std::collections::HashMap<usize, day_spec::props::ListItemProps>> =
        std::cell::RefCell::new(std::collections::HashMap::new());
}

/// A list row's standard content (docs/list.md "List items"), as an image-and-text table cell
/// draws it: a 16pt template image, the title in the system font with a smaller secondary
/// subtitle under it, a secondary trailing value, and the accent checkmark, in a horizontal
/// stack at least 28pt tall. Parts that are absent are hidden, and the stack closes up around
/// them.
///
/// The row's width is spoken for explicitly, as an image-and-text cell's is: the stack fills
/// its frame edge to edge, the words take every spare point and give way first, and the
/// trailing parts keep their own size. Left to the stack's default gravity areas, the spare
/// width had two equally weak claims, the words' column and the gap before the trailing parts,
/// so Auto Layout settled it from whatever the row's last layout had been: a checkmark landed
/// beside the title in one row and at the trailing edge in the next, and stayed put.
fn make_list_item(p: &day_spec::props::ListItemProps, mtm: MainThreadMarker) -> Retained<NSView> {
    use objc2_app_kit::{
        NSImageView, NSLayoutAttribute, NSStackView, NSUserInterfaceLayoutOrientation,
    };
    let label = |text: &str, size: f64, secondary: bool| {
        let tf = unsafe { NSTextField::labelWithString(&NSString::from_str(text), mtm) };
        unsafe {
            tf.setFont(Some(&objc2_app_kit::NSFont::systemFontOfSize(size)));
            if secondary {
                tf.setTextColor(Some(&objc2_app_kit::NSColor::secondaryLabelColor()));
            }
            tf.setLineBreakMode(objc2_app_kit::NSLineBreakMode::ByTruncatingTail);
        }
        tf
    };
    let size = unsafe { objc2_app_kit::NSFont::systemFontSize() };
    let small = unsafe { objc2_app_kit::NSFont::smallSystemFontSize() };
    const ACROSS: objc2_app_kit::NSLayoutConstraintOrientation =
        objc2_app_kit::NSLayoutConstraintOrientation::Horizontal;
    // Hugging: the words stretch (1), the trailing parts hold their size (750), and the stack
    // keeps its edges on its first and last parts (750), so exactly one part takes the slack.
    const STRETCH: f32 = 1.0;
    const HOLD: f32 = 750.0;
    let stack = NSStackView::new(mtm);
    stack.setOrientation(NSUserInterfaceLayoutOrientation::Horizontal);
    stack.setDistribution(objc2_app_kit::NSStackViewDistribution::Fill);
    stack.setAlignment(NSLayoutAttribute::CenterY);
    stack.setHuggingPriority_forOrientation(HOLD, ACROSS);
    stack.setSpacing(6.0);
    // A table row's breathing room above and below; the list gives the sides.
    stack.setEdgeInsets(objc2_foundation::NSEdgeInsets {
        top: 4.0,
        left: 0.0,
        bottom: 4.0,
        right: 0.0,
    });
    let icon = unsafe { NSImageView::new(mtm) };
    unsafe {
        icon.setImageScaling(objc2_app_kit::NSImageScaling::ScaleProportionallyUpOrDown);
        icon.widthAnchor()
            .constraintEqualToConstant(16.0)
            .setActive(true);
        icon.heightAnchor()
            .constraintEqualToConstant(16.0)
            .setActive(true);
    }
    stack.addArrangedSubview(&icon);
    // The title and subtitle span the words' column (Width alignment), so the column's width is
    // theirs and nothing is left over inside it.
    let texts = NSStackView::new(mtm);
    texts.setOrientation(NSUserInterfaceLayoutOrientation::Vertical);
    texts.setAlignment(NSLayoutAttribute::Width);
    texts.setSpacing(1.0);
    // Its height is its lines', centered in the row, not the row's height with the lines
    // floating somewhere inside it.
    texts.setHuggingPriority_forOrientation(
        HOLD,
        objc2_app_kit::NSLayoutConstraintOrientation::Vertical,
    );
    let title = label("", size, false);
    let subtitle = label("", small, true);
    // The words take the width and give way first, truncating, before the trailing parts.
    for line in [&title, &subtitle] {
        line.setContentHuggingPriority_forOrientation(STRETCH, ACROSS);
        line.setContentCompressionResistancePriority_forOrientation(250.0, ACROSS);
    }
    texts.addArrangedSubview(&title);
    texts.addArrangedSubview(&subtitle);
    stack.addArrangedSubview(&texts);
    let detail = label("", size, true);
    detail.setContentHuggingPriority_forOrientation(HOLD, ACROSS);
    detail.setContentCompressionResistancePriority_forOrientation(HOLD, ACROSS);
    stack.addArrangedSubview(&detail);
    let check = unsafe { NSImageView::new(mtm) };
    unsafe {
        check.setImage(
            objc2_app_kit::NSImage::imageWithSystemSymbolName_accessibilityDescription(
                &NSString::from_str("checkmark"),
                None,
            )
            .as_deref(),
        );
        check.setContentTintColor(Some(&objc2_app_kit::NSColor::controlAccentColor()));
    }
    check.setContentHuggingPriority_forOrientation(HOLD, ACROSS);
    check.setContentCompressionResistancePriority_forOrientation(HOLD, ACROSS);
    stack.addArrangedSubview(&check);
    let view = Retained::from(<NSStackView as AsRef<NSView>>::as_ref(&stack));
    LIST_ITEMS.with(|m| m.borrow_mut().insert(ptr_of(&view), p.clone()));
    dress_list_item(&view, p, mtm);
    view
}

/// Show `p` on a list item's stack (see [`make_list_item`]), as one accessibility element.
fn dress_list_item(view: &NSView, p: &day_spec::props::ListItemProps, mtm: MainThreadMarker) {
    use objc2_app_kit::{NSImageView, NSStackView};
    let Some(stack) = view.downcast_ref::<NSStackView>() else {
        return;
    };
    let parts = stack.arrangedSubviews();
    if parts.len() < 4 {
        return;
    }
    let icon = parts.objectAtIndex(0);
    if let Some(iv) = icon.downcast_ref::<NSImageView>() {
        let image = p
            .icon
            .as_ref()
            .and_then(|i| toolbar::image_for(i, &p.title, mtm));
        unsafe {
            iv.setImage(image.as_deref());
            iv.setContentTintColor(p.icon_tint.map(nscolor).as_deref());
        }
    }
    icon.setHidden(p.icon.is_none());
    if let Some(texts) = parts.objectAtIndex(1).downcast_ref::<NSStackView>() {
        let lines = texts.arrangedSubviews();
        if lines.len() == 2 {
            if let Some(tf) = lines.objectAtIndex(0).downcast_ref::<NSTextField>() {
                tf.setStringValue(&NSString::from_str(&p.title));
            }
            let sub = lines.objectAtIndex(1);
            if let Some(tf) = sub.downcast_ref::<NSTextField>() {
                tf.setStringValue(&NSString::from_str(&p.subtitle));
            }
            sub.setHidden(p.subtitle.is_empty());
        }
    }
    let detail = parts.objectAtIndex(2);
    if let Some(tf) = detail.downcast_ref::<NSTextField>() {
        tf.setStringValue(&NSString::from_str(&p.detail));
    }
    detail.setHidden(p.detail.is_empty());
    parts.objectAtIndex(3).setHidden(!p.checked);
    let words = [&p.title, &p.subtitle, &p.detail]
        .into_iter()
        .filter(|w| !w.is_empty())
        .map(String::as_str)
        .collect::<Vec<_>>()
        .join(", ");
    unsafe {
        view.setAccessibilityElement(true);
        view.setAccessibilityLabel(Some(&NSString::from_str(&words)));
        view.setAccessibilitySelected(p.checked);
    }
}

/// The `NSImage` behind an [`day_spec::ImageSource`] (docs/images.md).
///
/// Shared by realize and the `Source` patch: a swapped source must load exactly what a fresh
/// realize would have, or a piece would show different pixels depending on whether it was
/// built or updated.
fn appkit_image_for(source: &day_spec::ImageSource) -> Option<Retained<objc2_app_kit::NSImage>> {
    use objc2::AllocAnyThread as _;
    match source {
        // A vector glyph's SVG first (docs/vectors.md): NSImage renders SVG at display size
        // (macOS 11+), so vectors stay vector with no build-time raster resampling. Then the
        // shared image-file resolver (images/ then assets/ then bundle), which is macOS's native
        // path: a bundle file loaded straight into NSImage (§18.3).
        day_spec::ImageSource::Named(name) => day_spec::resource::resolve_vector_svg(name)
            .or_else(|| day_spec::resource::resolve_image_file(name))
            .and_then(|path| unsafe {
                objc2_app_kit::NSImage::initWithContentsOfFile(
                    objc2_app_kit::NSImage::alloc(),
                    &NSString::from_str(&path.to_string_lossy()),
                )
            }),
        // Bytes the app already holds (a download, a picked file, a paste) with no staged
        // resource behind them.
        day_spec::ImageSource::Bytes(bytes) => unsafe {
            objc2_app_kit::NSImage::initWithData(
                objc2_app_kit::NSImage::alloc(),
                &NSData::with_bytes(bytes),
            )
        },
        // Already decoded: share the one NSImage rather than parsing the same bytes twice.
        day_spec::ImageSource::Decoded(id) => {
            BITMAPS.with(|m| m.borrow().get(&id.0).map(|b| b.image.clone()))
        }
    }
}

/// Day `Role` → the `NSAccessibilityRole` constant to apply (§13). `None` for `Role::None`:
/// Day leaves native controls' roles untouched and only applies explicit canvas/custom roles.
fn ns_role(role: day_spec::Role) -> Option<&'static objc2_app_kit::NSAccessibilityRole> {
    use day_spec::Role;
    use objc2_app_kit::{
        NSAccessibilityButtonRole, NSAccessibilityCheckBoxRole, NSAccessibilityGroupRole,
        NSAccessibilityHeadingRole, NSAccessibilityImageRole, NSAccessibilityLevelIndicatorRole,
        NSAccessibilityOutlineRole, NSAccessibilityRadioButtonRole, NSAccessibilityRowRole,
        NSAccessibilitySliderRole, NSAccessibilityTabGroupRole, NSAccessibilityTextFieldRole,
    };
    unsafe {
        Some(match role {
            Role::Button => NSAccessibilityButtonRole,
            Role::Toggle => NSAccessibilityCheckBoxRole,
            // A tab is a radio button with the tab-button subrole (`set_a11y` adds it), which
            // is how NSTabView's own tabs read to VoiceOver; the strip is a tab group.
            Role::Tab => NSAccessibilityRadioButtonRole,
            Role::TabList => NSAccessibilityTabGroupRole,
            Role::Slider => NSAccessibilitySliderRole,
            Role::TextInput => NSAccessibilityTextFieldRole,
            // `AXHeading` lands the label in VoiceOver's headings rotor. The level has no
            // AppKit attribute of its own: the only convention (the level as `AXValue`) would
            // displace the text an NSTextField reports as its value, so the level stays
            // unspoken.
            Role::Heading(_) => NSAccessibilityHeadingRole,
            Role::Image => NSAccessibilityImageRole,
            Role::Meter => NSAccessibilityLevelIndicatorRole,
            Role::Group => NSAccessibilityGroupRole,
            // NSOutlineView already reports these itself; the mapping is for the audit's
            // expectation and for any composed stand-in (docs/tree.md).
            Role::Tree => NSAccessibilityOutlineRole,
            Role::TreeItem => NSAccessibilityRowRole,
            Role::None => return None,
        })
    }
}

/// Native `AXRole` string → Day `Role` (best-effort, for `read_native`/`a11y_audit`).
fn day_role_from_ns(ax: &str) -> day_spec::Role {
    use day_spec::Role;
    match ax {
        "AXButton" => Role::Button,
        "AXCheckBox" => Role::Toggle,
        "AXSlider" => Role::Slider,
        "AXTextField" => Role::TextInput,
        // Plain text is ambiguous with a heading, and neither carries a level; the audit
        // ignores the level either way.
        "AXStaticText" | "AXHeading" => Role::Heading(0),
        "AXOutline" => Role::Tree,
        "AXImage" => Role::Image,
        "AXLevelIndicator" | "AXProgressIndicator" => Role::Meter,
        "AXGroup" => Role::Group,
        "AXRadioButton" => Role::Tab,
        "AXTabGroup" => Role::TabList,
        _ => Role::None,
    }
}

// ---------------------------------------------------------------------------
// DayTarget: target/action + text delegate trampoline
// ---------------------------------------------------------------------------

struct TargetIvars {
    node: NodeId,
}

define_class!(
    #[unsafe(super(NSObject))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayTarget"]
    #[ivars = TargetIvars]
    struct DayTarget;

    unsafe impl NSObjectProtocol for DayTarget {}
    unsafe impl NSTextFieldDelegate for DayTarget {}

    /// A tabs host's `NSTabView` (docs/navigation.md). A pick emits against the NAV_MENU's
    /// node, exactly as the sidebar's outline view does, so as far as everything above this
    /// backend is concerned, picking a tab and clicking a sidebar row are the same event, and
    /// neither the pieces layer nor dayscript needs to know which chrome the window wears.
    unsafe impl NSTabViewDelegate for DayTarget {
        #[unsafe(method(tabView:didSelectTabViewItem:))]
        fn tab_view_did_select(
            &self,
            tab_view: &objc2_app_kit::NSTabView,
            item: Option<&objc2_app_kit::NSTabViewItem>,
        ) {
            ffi_guard::contain((), || {
                if TAB_PICK_SUPPRESS.with(|s| s.get()) {
                    return;
                }
                if let Some(item) = item {
                    let idx = unsafe { tab_view.indexOfTabViewItem(item) };
                    if idx >= 0 {
                        emit(self.ivars().node, Event::SelectionChanged(idx as i64));
                    }
                }
            })
        }
    }

    impl DayTarget {
        // Every trampoline that dispatches into the sink (and through it, app handlers) runs
        // its body through `ffi_guard::contain` (§8.5): a Rust panic unwinding out of an ObjC
        // frame is an abort, so it is caught, reported, and the reactive runtime recovered.
        // The same guard wraps every other target/delegate entry in this backend.
        #[unsafe(method(action:))]
        fn action(&self, sender: &NSControl) {
            ffi_guard::contain((), || {
                let node = self.ivars().node;
                if sender.downcast_ref::<NSSwitch>().is_some() {
                    emit(node, Event::ToggleChanged(unsafe { sender.integerValue() } != 0));
                } else if sender.downcast_ref::<NSSlider>().is_some() {
                    let value = unsafe { sender.doubleValue() };
                    // The live value first: bindings follow this, so the UI tracks the thumb.
                    emit(node, Event::ValueChanged(value));
                    // Then, once, the value the user settled on. The slider is `continuous`, so
                    // this action fires on every tick of a drag; AppKit's way to tell where in the
                    // gesture you are is the event that provoked it. A mouse-up ends a drag; a key
                    // press (arrow keys) moves the value by one discrete step and is already settled;
                    // anything else (mouse-down, mouse-dragged) is mid-gesture and commits nothing.
                    if slider_value_settled() {
                        emit(node, Event::ValueCommitted(value));
                    }
                } else {
                    emit(node, Event::Pressed);
                    // A push-on/push-off button toggled its state on the click; Day owns the
                    // selected state (`set_button_selected`), so put back what it last asked.
                    let wanted = BUTTON_SELECTED.with(|m| m.borrow().get(&ptr_of(sender)).copied());
                    if let (Some(on), Some(btn)) = (wanted, sender.downcast_ref::<NSButton>()) {
                        unsafe {
                            btn.setState(if on {
                                NSControlStateValueOn
                            } else {
                                NSControlStateValueOff
                            })
                        };
                    }
                }
            })
        }

        /// The stack-nav back header's button (docs/navigation.md): a day-initiated pop. The
        /// nav host's handler writes it into the path signal, which reconciles the pop.
        #[unsafe(method(navBack:))]
        fn nav_back(&self, _sender: &NSControl) {
            ffi_guard::contain((), || {
                emit(
                    self.ivars().node,
                    Event::NavBack {
                        already_popped: false,
                    },
                );
            })
        }
    }

    unsafe impl NSControlTextEditingDelegate for DayTarget {
        #[unsafe(method(controlTextDidChange:))]
        fn control_text_did_change(&self, notification: &NSNotification) {
            ffi_guard::contain((), || {
                let node = self.ivars().node;
                if let Some(obj) = unsafe { notification.object() }
                    && let Ok(tf) = obj.downcast::<NSTextField>() {
                        emit(node, Event::TextChanged(unsafe { tf.stringValue() }.to_string()));
                    }
            })
        }

        /// End of an editing session (docs/focus.md). Return submits: AppKit keeps the field
        /// first responder and re-selects, so it is not a focus loss; every other movement
        /// (tab, click-away, cancel) reports `FocusChanged(false)`.
        #[unsafe(method(controlTextDidEndEditing:))]
        fn control_text_did_end_editing(&self, notification: &NSNotification) {
            ffi_guard::contain((), || {
                let node = self.ivars().node;
                let movement = unsafe { notification.userInfo() }
                    .and_then(|ui| ui.objectForKey(unsafe { NSTextMovementUserInfoKey }.as_ref()))
                    .and_then(|n| n.downcast::<NSNumber>().ok())
                    .map(|n| NSTextMovement(n.integerValue()))
                    .unwrap_or(NSTextMovement::Other);
                if movement == NSTextMovement::Return {
                    emit(node, Event::Submitted);
                } else {
                    emit(node, Event::FocusChanged(false));
                }
            })
        }
    }
);

impl DayTarget {
    fn new(mtm: MainThreadMarker, node: NodeId) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(TargetIvars { node });
        unsafe { msg_send![super(this), init] }
    }
}

// ---------------------------------------------------------------------------
// DayCursorOwner: the `.cursor()` decorator's tracking-area owner (docs/cursor.md)
// ---------------------------------------------------------------------------

struct CursorIvars {
    /// The shape to set on `cursorUpdate:`; `None` leaves the platform's own choice.
    cursor: RefCell<Option<Retained<NSCursor>>>,
    /// `Cursor::None`: hide the pointer while it is inside, unhide on exit.
    hidden: Cell<bool>,
    /// Whether this owner is the one that hid the pointer (balanced by `unhide`).
    hiding: Cell<bool>,
}

// AppKit only re-evaluates the pointer's shape on `cursorUpdate:`, which it sends to a
// tracking area's owner when the pointer enters the area (and on request through
// `invalidateCursorRectsForView:`). One owner per view keeps the view class untouched: a label,
// a button, or a plain container all get the same treatment without subclassing. Nested areas
// resolve by entry order: the innermost is entered last, so its shape is the one that stays.
define_class!(
    #[unsafe(super(NSObject))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayCursorOwner"]
    #[ivars = CursorIvars]
    struct DayCursorOwner;

    unsafe impl NSObjectProtocol for DayCursorOwner {}

    impl DayCursorOwner {
        #[unsafe(method(cursorUpdate:))]
        fn cursor_update(&self, _event: &NSEvent) {
            let iv = self.ivars();
            if iv.hidden.get() {
                if !iv.hiding.replace(true) {
                    NSCursor::hide();
                }
                return;
            }
            if let Some(c) = iv.cursor.borrow().as_ref() {
                c.set();
            }
        }

        #[unsafe(method(mouseExited:))]
        fn mouse_exited(&self, _event: &NSEvent) {
            if self.ivars().hiding.replace(false) {
                NSCursor::unhide();
            }
        }
    }
);

impl DayCursorOwner {
    fn new(mtm: MainThreadMarker) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(CursorIvars {
            cursor: RefCell::new(None),
            hidden: Cell::new(false),
            hiding: Cell::new(false),
        });
        unsafe { msg_send![super(this), init] }
    }
}

/// The `NSCursor` for a [`Cursor`], or `None` where the platform's own choice should stand
/// (`Cursor::None`, which the owner hides instead, and a native name AppKit does not have).
/// AppKit has no wait, progress, help, or move shape, so those take the arrow; the zoom, frame
/// (diagonal) resize, and column/row resize cursors arrived in macOS 15 and are probed by
/// nav host, with the nearest older shape below it.
// `resizeLeftRightCursor` and `resizeUpDownCursor` are deprecated in favor of the macOS 15
// column/row resize cursors, which are probed above them; below 15 they are the shape.
#[allow(deprecated)]
fn ns_cursor(c: &Cursor) -> Option<Retained<NSCursor>> {
    let has = |sel: objc2::runtime::Sel| <NSCursor as objc2::ClassType>::class().responds_to(sel);
    Some(match c {
        Cursor::Default | Cursor::Wait | Cursor::Progress | Cursor::Help => NSCursor::arrowCursor(),
        Cursor::Pointer => NSCursor::pointingHandCursor(),
        Cursor::Text => NSCursor::IBeamCursor(),
        Cursor::VerticalText => NSCursor::IBeamCursorForVerticalLayout(),
        Cursor::Crosshair | Cursor::Cell => NSCursor::crosshairCursor(),
        Cursor::Move | Cursor::Grab => NSCursor::openHandCursor(),
        Cursor::Grabbing => NSCursor::closedHandCursor(),
        Cursor::NotAllowed => NSCursor::operationNotAllowedCursor(),
        Cursor::ContextMenu => NSCursor::contextualMenuCursor(),
        Cursor::Copy => NSCursor::dragCopyCursor(),
        Cursor::Alias => NSCursor::dragLinkCursor(),
        Cursor::ZoomIn if has(sel!(zoomInCursor)) => NSCursor::zoomInCursor(),
        Cursor::ZoomOut if has(sel!(zoomOutCursor)) => NSCursor::zoomOutCursor(),
        Cursor::ZoomIn | Cursor::ZoomOut => NSCursor::arrowCursor(),
        Cursor::NsResize => NSCursor::resizeUpDownCursor(),
        Cursor::EwResize => NSCursor::resizeLeftRightCursor(),
        Cursor::NeswResize if has(sel!(frameResizeCursorFromPosition:inDirections:)) => {
            NSCursor::frameResizeCursorFromPosition_inDirections(
                NSCursorFrameResizePosition::TopRight,
                NSCursorFrameResizeDirections::All,
            )
        }
        Cursor::NwseResize if has(sel!(frameResizeCursorFromPosition:inDirections:)) => {
            NSCursor::frameResizeCursorFromPosition_inDirections(
                NSCursorFrameResizePosition::TopLeft,
                NSCursorFrameResizeDirections::All,
            )
        }
        Cursor::NeswResize | Cursor::NwseResize => NSCursor::arrowCursor(),
        Cursor::ColResize if has(sel!(columnResizeCursor)) => NSCursor::columnResizeCursor(),
        Cursor::ColResize => NSCursor::resizeLeftRightCursor(),
        Cursor::RowResize if has(sel!(rowResizeCursor)) => NSCursor::rowResizeCursor(),
        Cursor::RowResize => NSCursor::resizeUpDownCursor(),
        Cursor::None => return None,
        Cursor::Native(name) => match &**name {
            "disappearingItem" => NSCursor::disappearingItemCursor(),
            "dragCopy" => NSCursor::dragCopyCursor(),
            "dragLink" => NSCursor::dragLinkCursor(),
            "contextualMenu" => NSCursor::contextualMenuCursor(),
            "IBeamCursorForVerticalLayout" => NSCursor::IBeamCursorForVerticalLayout(),
            _ => return None,
        },
    })
}

/// Whether the NSEvent currently being dispatched ends a slider's interaction (see the
/// `ValueCommitted` emission in `DayTarget::action:`). AppKit gives a continuous slider no
/// "drag ended" callback, so the event that provoked the action is what says where in the gesture
/// we are: a mouse-up ends a drag, an arrow key moves one discrete step and is already settled,
/// and mouse-down/mouse-dragged are mid-gesture. No current event at all (a programmatic
/// `setDoubleValue:` that fires the action) is not a user commit either.
fn slider_value_settled() -> bool {
    let Some(mtm) = MainThreadMarker::new() else {
        return false;
    };
    let Some(event) = NSApplication::sharedApplication(mtm).currentEvent() else {
        return false;
    };
    matches!(
        unsafe { event.r#type() },
        NSEventType::LeftMouseUp | NSEventType::KeyDown | NSEventType::KeyUp
    )
}

// ---------------------------------------------------------------------------
// DayTextField: NSTextField that reports focus gain (docs/focus.md)
// ---------------------------------------------------------------------------

struct FieldIvars {
    node: NodeId,
}

define_class!(
    #[unsafe(super(NSTextField))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayTextField"]
    #[ivars = FieldIvars]
    struct DayTextField;

    impl DayTextField {
        /// Focus gain. Key events go to the shared field editor, but the field itself receives
        /// `becomeFirstResponder` first, the reliable gain hook (`controlTextDidBeginEditing:`
        /// waits for the first keystroke). Loss comes from `controlTextDidEndEditing:` on the
        /// delegate.
        #[unsafe(method(becomeFirstResponder))]
        fn become_first_responder(&self) -> bool {
            let ok: bool = unsafe { msg_send![super(self), becomeFirstResponder] };
            if ok {
                field_gained_focus(self.ivars().node);
            }
            ok
        }
    }
);

impl DayTextField {
    fn new(mtm: MainThreadMarker, node: NodeId) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(FieldIvars { node });
        unsafe { msg_send![super(this), init] }
    }
}

// The secure twin (docs/textfield.md). AppKit hides characters with a class, not a property:
// `NSSecureTextField` brings its own cell and field editor, which keep the text out of the
// pasteboard, the spelling checker and the accessibility value. A `text_field` that turns
// `secure` is rebuilt as this class (`set_input_traits`), with the same focus hook.
define_class!(
    #[unsafe(super(NSSecureTextField))]
    #[thread_kind = MainThreadOnly]
    #[name = "DaySecureTextField"]
    #[ivars = FieldIvars]
    struct DaySecureTextField;

    impl DaySecureTextField {
        /// Focus gain, as on `DayTextField`.
        #[unsafe(method(becomeFirstResponder))]
        fn become_first_responder(&self) -> bool {
            let ok: bool = unsafe { msg_send![super(self), becomeFirstResponder] };
            if ok {
                field_gained_focus(self.ivars().node);
            }
            ok
        }
    }
);

impl DaySecureTextField {
    fn new(mtm: MainThreadMarker, node: NodeId) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(FieldIvars { node });
        unsafe { msg_send![super(this), init] }
    }
}

thread_local! {
    /// A plain/secure class swap in flight (`set_input_traits`): focus moves from the old
    /// field to its replacement, which the app must not see as a focus change.
    static FIELD_SWAP: Cell<bool> = const { Cell::new(false) };
}

/// Report a text field's focus gain, unless it is a class swap handing focus to the
/// replacement of a field that already had it.
fn field_gained_focus(node: NodeId) {
    if FIELD_SWAP.with(|s| s.get()) {
        return;
    }
    // Guard only the sink dispatch: the responder change already happened, so a contained
    // panic must not flip the answer AppKit acts on.
    ffi_guard::contain((), || emit(node, Event::FocusChanged(true)));
}

/// The node a `text_field`'s view reports against, or `None` when the view is not one
/// (a label is an `NSTextField` too).
fn text_field_node(v: &NSView) -> Option<NodeId> {
    v.downcast_ref::<DayTextField>()
        .map(|f| f.ivars().node)
        .or_else(|| {
            v.downcast_ref::<DaySecureTextField>()
                .map(|f| f.ivars().node)
        })
}

/// Build a `text_field`'s view, plain or secure, with its delegate wired and registered.
/// `realize` and the class swap in `set_input_traits` both come through here, so both classes
/// report text, submit and focus the same way against the same node.
fn new_text_field(mtm: MainThreadMarker, node: NodeId, secure: bool) -> Retained<NSTextField> {
    let target = DayTarget::new(mtm, node);
    // Up to `NSTextField` (the declared superclass of both), so the AsRef<NSView> bound on
    // `view_of` resolves and every `NSTextField` downcast sees either class.
    let tf: Retained<NSTextField> = if secure {
        Retained::into_super(Retained::into_super(DaySecureTextField::new(mtm, node)))
    } else {
        Retained::into_super(DayTextField::new(mtm, node))
    };
    unsafe {
        tf.setEditable(true);
        tf.setBezeled(true);
        tf.setDelegate(Some(ProtocolObject::from_ref(&*target)));
    }
    TARGETS.with(|m| m.borrow_mut().insert(ptr_of(&tf), target));
    tf
}

/// Whether `h` (a text field, or the field editor's client) holds its window's focus. A
/// focused `NSTextField`'s first responder is the shared field editor, so unwrap it back to
/// the field via its delegate.
fn owns_first_responder(window: &NSWindow, h: &NSView) -> bool {
    window.firstResponder().is_some_and(|fr| {
        if Retained::as_ptr(&fr) as *const () as usize == ptr_of(h) {
            return true;
        }
        fr.downcast::<NSText>().is_ok_and(|text| {
            unsafe { text.delegate() }
                .is_some_and(|d| Retained::as_ptr(&d) as *const () as usize == ptr_of(h))
        })
    })
}

/// An `NSTextContentType` constant by symbol name, or `None` on a system that predates it.
/// Looked up at run time because most of the vocabulary arrived in macOS 14: a direct
/// reference binds at launch, and one missing symbol would keep the whole app from starting
/// on an older system.
fn text_content_type(symbol: &std::ffi::CStr) -> Option<&'static NSString> {
    unsafe extern "C" {
        fn dlsym(
            handle: *mut std::ffi::c_void,
            symbol: *const std::ffi::c_char,
        ) -> *mut std::ffi::c_void;
    }
    // <dlfcn.h>: search every image loaded in the process.
    const RTLD_DEFAULT: *mut std::ffi::c_void = -2isize as *mut std::ffi::c_void;
    // SAFETY: `symbol` is NUL-terminated. Each name passed here is an AppKit
    // `NSString * const`, so a non-null result is the address of a pointer to an immortal
    // constant string.
    unsafe {
        let slot = dlsym(RTLD_DEFAULT, symbol.as_ptr()).cast::<*const NSString>();
        if slot.is_null() {
            None
        } else {
            (*slot).as_ref()
        }
    }
}

/// Move a view-keyed entry to the view that replaces it.
fn rekey<V>(table: &SideTable<V>, old: usize, new: usize) {
    if let Some(v) = table.take(old) {
        table.insert(new, v);
    }
}

/// A label is the shared field editor's delegate. AppKit does not forward
/// `textView:clickedOnLink:atIndex:` to an NSTextField's separate control delegate, so the
/// label itself must handle it to prevent the field editor from opening the target externally.
/// See Apple's "Working With the Field Editor" and docs/text-runs.md.
struct LabelIvars {
    node: NodeId,
    has_links: Cell<bool>,
    has_runs: Cell<bool>,
    selectable: Cell<bool>,
}

define_class!(
    #[unsafe(super(NSTextField))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayLabel"]
    #[ivars = LabelIvars]
    struct DayLabel;

    impl DayLabel {
        #[unsafe(method_id(menuForEvent:))]
        fn menu_for_event(&self, event: &objc2_app_kit::NSEvent) -> Option<Retained<NSMenu>> {
            ffi_guard::contain(None, || {
                if !self.isSelectable()
                    && let Some(menu) = inherited_context_menu(self, event)
                {
                    return menu;
                }
                unsafe { msg_send![super(self), menuForEvent: event] }
            })
        }

        #[unsafe(method(drawRect:))]
        fn draw_rect(&self, dirty: NSRect) {
            // AppKit cannot propagate a table cell's background style through arbitrary
            // Day containers. Resolve selection at paint time so keyboard focus, window
            // activation, and cell reuse all use the actual native row state.
            let mut ancestor = unsafe { self.superview() };
            let mut selection_color = None;
            if !self.ivars().has_runs.get() {
                while let Some(view) = ancestor {
                    if let Some(row) = view.downcast_ref::<objc2_app_kit::NSTableRowView>() {
                        if unsafe { row.isSelected() } {
                            selection_color = Some(unsafe {
                                if row.isEmphasized() {
                                    objc2_app_kit::NSColor::alternateSelectedControlTextColor()
                                } else {
                                    objc2_app_kit::NSColor::unemphasizedSelectedTextColor()
                                }
                            });
                        }
                        break;
                    }
                    ancestor = unsafe { view.superview() };
                }
            }
            let cell = unsafe { self.cell() }
                .and_then(|cell| cell.downcast::<objc2_app_kit::NSTextFieldCell>().ok());
            if let (Some(color), Some(cell)) = (selection_color, cell) {
                let original = unsafe { cell.textColor() };
                // Mutate the cell only for this paint; changing the field would invalidate
                // the view again. Keep the app's normal color for deselection and reuse.
                unsafe {
                    cell.setTextColor(Some(&color));
                    let _: () = msg_send![super(self), drawRect: dirty];
                    cell.setTextColor(original.as_deref());
                }
            } else {
                let _: () = unsafe { msg_send![super(self), drawRect: dirty] };
            }
        }
    }

    unsafe impl NSObjectProtocol for DayLabel {}
    unsafe impl NSTextDelegate for DayLabel {}

    unsafe impl NSTextViewDelegate for DayLabel {
        #[unsafe(method(textView:clickedOnLink:atIndex:))]
        fn clicked_on_link(
            &self,
            _tv: &NSTextView,
            link: &objc2::runtime::AnyObject,
            _index: usize,
        ) -> bool {
            ffi_guard::contain(true, || {
                // NSString targets stay verbatim (including #route); accept NSURL too.
                let url: Retained<NSString> = unsafe { msg_send![link, description] };
                emit(self.ivars().node, Event::LinkActivated(url.to_string()));
                true // Handled: AppKit must never also open the target itself.
            })
        }
    }
);

impl DayLabel {
    fn new(mtm: MainThreadMarker, node: NodeId, text: &str) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(LabelIvars {
            node,
            has_links: Cell::new(false),
            has_runs: Cell::new(false),
            selectable: Cell::new(false),
        });
        let this: Retained<Self> = unsafe { msg_send![super(this), init] };
        unsafe {
            this.setStringValue(&NSString::from_str(text));
            this.setEditable(false);
            this.setSelectable(false);
            this.setBordered(false);
            this.setBezeled(false);
            this.setDrawsBackground(false);
        }
        this
    }

    fn set_links(&self, has_links: bool) {
        self.ivars().has_links.set(has_links);
        unsafe {
            self.setSelectable(has_links || self.ivars().selectable.get());
            self.setAllowsEditingTextAttributes(has_links);
        }
    }
}

struct PanMonitor(Retained<objc2::runtime::AnyObject>);
impl Drop for PanMonitor {
    fn drop(&mut self) {
        unsafe { NSEvent::removeMonitor(&self.0) };
    }
}

// A container pan observes horizontal wheel events over its descendants, including native
// scroll views. Leave vertical scrolling and canvas 2D pans to their existing handlers.
fn install_container_pan_monitor() {
    PAN_MONITOR.with(|slot| {
        if slot.borrow().is_some() {
            return;
        }
        let block = block2::RcBlock::new(|raw: std::ptr::NonNull<NSEvent>| -> *mut NSEvent {
            let event = unsafe { raw.as_ref() };
            ffi_guard::contain(raw.as_ptr(), || {
                let dx = unsafe { event.scrollingDeltaX() };
                let dy = unsafe { event.scrollingDeltaY() };
                if dx.abs() <= dy.abs() {
                    return raw.as_ptr();
                }
                let Some(mtm) = MainThreadMarker::new() else {
                    return raw.as_ptr();
                };
                let Some(window) = event.window(mtm) else {
                    return raw.as_ptr();
                };
                let Some(content) = window.contentView() else {
                    return raw.as_ptr();
                };
                let point =
                    content.convertPoint_fromView(unsafe { event.locationInWindow() }, None);
                let mut view = content.hitTest(point);
                while let Some(v) = view {
                    if let Some(node) = PAN_NODES.with(|t| t.get(ptr_of(&v))) {
                        if v.downcast_ref::<DayCanvas>().is_some() {
                            return raw.as_ptr();
                        }
                        let raw_phase = unsafe { event.phase() };
                        let phase = if raw_phase.contains(objc2_app_kit::NSEventPhase::Began) {
                            day_spec::DragPhase::Began
                        } else if raw_phase.intersects(
                            objc2_app_kit::NSEventPhase::Ended
                                | objc2_app_kit::NSEventPhase::Cancelled,
                        ) {
                            day_spec::DragPhase::Ended
                        } else {
                            day_spec::DragPhase::Changed
                        };
                        let p = v.convertPoint_fromView(unsafe { event.locationInWindow() }, None);
                        emit(
                            node,
                            Event::Pan {
                                phase,
                                delta: Point::new(dx, dy),
                                location: Point::new(p.x, p.y),
                            },
                        );
                        return std::ptr::null_mut();
                    }
                    view = unsafe { v.superview() };
                }
                raw.as_ptr()
            })
        });
        *slot.borrow_mut() = unsafe {
            NSEvent::addLocalMonitorForEventsMatchingMask_handler(
                objc2_app_kit::NSEventMask::ScrollWheel,
                &block,
            )
        }
        .map(PanMonitor);
    });
}

// ---------------------------------------------------------------------------
// DayFlipped: top-left-origin container view
// ---------------------------------------------------------------------------

/// A `background(..)` fill: `(r, g, b, a, corner_radius)`, painted in `drawRect` with NSColor.
type Surface = (f64, f64, f64, f64, f64);

#[derive(Default)]
struct FlippedIvars {
    surface: Cell<Option<Surface>>,
    /// SurfaceRole::SectionCard: `(radius,)`, drawn with a dynamic system fill resolved at
    /// draw time, so the card tracks light/dark appearance changes automatically.
    section_card: Cell<Option<f64>>,
    /// Paint the whole view with the dynamic window background before anything else: the
    /// inspector panel wrap (docs/inspector.md). The inspector NSSplitViewItem backs its pane
    /// with a vibrancy material, and the section cards' thin quaternary fill composites over
    /// it into near-black in dark mode (and the material itself captures black offscreen; see
    /// the sidebar-screenshot rule, docs/navigation.md). An opaque appearance-resolved
    /// backdrop gives the cards the same ground System Settings draws them on.
    pane_backdrop: Cell<bool>,
}

define_class!(
    #[unsafe(super(NSView))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayFlipped"]
    #[ivars = FlippedIvars]
    struct DayFlipped;

    impl DayFlipped {
        #[unsafe(method_id(menuForEvent:))]
        fn menu_for_event(&self, event: &objc2_app_kit::NSEvent) -> Option<Retained<NSMenu>> {
            ffi_guard::contain(None, || {
                inherited_context_menu(self, event)
                    .unwrap_or_else(|| unsafe { msg_send![super(self), menuForEvent: event] })
            })
        }

        #[unsafe(method(isFlipped))]
        fn is_flipped(&self) -> bool {
            true
        }

        // Focus, and with it the keyboard (docs/focus.md): the canvas contract, opted into by
        // `Decorate::focusable`. A container never in FOCUSABLE_NODES behaves exactly as
        // before (refuses first responder, forwards every key).
        #[unsafe(method(acceptsFirstResponder))]
        fn accepts_first_responder(&self) -> bool {
            let ptr = (self as *const DayFlipped).cast::<NSView>() as usize;
            FOCUSABLE_NODES.with(|t| t.get(ptr)).is_some()
        }

        // Clicking a focusable container focuses it, the way clicking a table does. The
        // gesture recognizers still see the press: this runs before `super`, which is what
        // forwards it to them.
        #[unsafe(method(mouseDown:))]
        fn mouse_down(&self, event: &objc2_app_kit::NSEvent) {
            if transfer::pressed(self, event) { return; }
            let ptr = (self as *const DayFlipped).cast::<NSView>() as usize;
            if FOCUSABLE_NODES.with(|t| t.get(ptr)).is_some()
                && let Some(window) = self.window()
            {
                window.makeFirstResponder(Some(self));
            }
            let _: () = unsafe { msg_send![super(self), mouseDown: event] };
        }

        #[unsafe(method(becomeFirstResponder))]
        fn become_first_responder(&self) -> bool {
            let ptr = (self as *const DayFlipped).cast::<NSView>() as usize;
            if let Some(node) = FOCUSABLE_NODES.with(|t| t.get(ptr)) {
                ffi_guard::contain((), || emit(node, Event::FocusChanged(true)));
            }
            true
        }

        #[unsafe(method(resignFirstResponder))]
        fn resign_first_responder(&self) -> bool {
            let ptr = (self as *const DayFlipped).cast::<NSView>() as usize;
            if let Some(node) = FOCUSABLE_NODES.with(|t| t.get(ptr)) {
                ffi_guard::contain((), || emit(node, Event::FocusChanged(false)));
            }
            true
        }

        /// The arrows, delivered here while this container is the first responder. Anything
        /// else (and every arrow when the app registered no key handler for the node) goes
        /// to `super`, which walks the responder chain exactly as it would have without us.
        #[unsafe(method(keyDown:))]
        fn key_down(&self, event: &objc2_app_kit::NSEvent) {
            let ptr = (self as *const DayFlipped).cast::<NSView>() as usize;
            let handled = ffi_guard::contain(false, || {
                let Some(node) = FOCUSABLE_NODES.with(|t| t.get(ptr)) else {
                    return false;
                };
                let Some(key) = key_name(event) else {
                    return false;
                };
                if !day_spec::keys::handled(node) {
                    return false;
                }
                emit(
                    node,
                    Event::Key(day_spec::KeyEvent {
                        key: key.to_string(),
                        modifiers: key_modifiers(event.modifierFlags()),
                    }),
                );
                true
            });
            if !handled {
                let _: () = unsafe { msg_send![super(self), keyDown: event] };
            }
        }

        /// Show the attached context menu (docs/menus.md) explicitly rather than relying on
        /// `NSResponder`'s default `.menu` display: popping it ourselves is deterministic
        /// regardless of how the click threads through Day's container hierarchy.
        #[unsafe(method(rightMouseDown:))]
        fn right_mouse_down(&self, event: &objc2_app_kit::NSEvent) {
            if let Some(menu) = self.menuForEvent(event) {
                unsafe {
                    objc2_app_kit::NSMenu::popUpContextMenu_withEvent_forView(&menu, event, self)
                };
            } else {
                let _: () = unsafe { msg_send![super(self), rightMouseDown: event] };
            }
        }

        #[unsafe(method(drawRect:))]
        fn draw_rect(&self, _dirty: NSRect) {
            let paint = || {
                if self.ivars().pane_backdrop.get() {
                    let bounds = self.bounds();
                    unsafe {
                        // Resolved at draw time, like the section fill below, so the backdrop
                        // follows light/dark appearance changes automatically.
                        NSColor::windowBackgroundColor().setFill();
                        objc2_app_kit::NSBezierPath::bezierPathWithRect(bounds).fill();
                    }
                }
                if let Some(radius) = self.ivars().section_card.get() {
                    let bounds = self.bounds();
                    unsafe {
                        // quaternarySystemFill (macOS 14+) is the grouped-card material System
                        // Settings uses; older systems fall back to the control background.
                        let cls = objc2::class!(NSColor);
                        let has: bool = msg_send![cls, respondsToSelector: objc2::sel!(quaternarySystemFillColor)];
                        let color: objc2::rc::Retained<NSColor> = if has {
                            msg_send![cls, quaternarySystemFillColor]
                        } else {
                            msg_send![cls, controlBackgroundColor]
                        };
                        color.setFill();
                        let path = objc2_app_kit::NSBezierPath::bezierPathWithRoundedRect_xRadius_yRadius(
                            bounds, radius, radius,
                        );
                        path.fill();
                    }
                }
                if let Some((r, g, b, a, radius)) = self.ivars().surface.get() {
                    let bounds = self.bounds();
                    unsafe {
                        NSColor::colorWithSRGBRed_green_blue_alpha(r, g, b, a).setFill();
                        let path = if radius > 0.0 {
                            objc2_app_kit::NSBezierPath::bezierPathWithRoundedRect_xRadius_yRadius(
                                bounds, radius, radius,
                            )
                        } else {
                            objc2_app_kit::NSBezierPath::bezierPathWithRect(bounds)
                        };
                        path.fill();
                    }
                }
            };
            // Paint under the standard counterpart of this view's appearance. Inside an
            // NSVisualEffectView subtree (the inspector pane) the effective appearance is
            // a vibrant one (NSAppearanceNameVibrantDark/-Light), and the system fills'
            // vibrant variants are opaque blend colors that only composite correctly in an
            // `allowsVibrancy` view: drawn plainly, dark-mode quaternary fill comes out
            // near-black instead of lightening. Resolving under aqua/darkAqua gives exactly
            // the fills System Settings draws with, and re-resolves on every theme change
            // (this runs per draw, and appearance flips redraw).
            unsafe {
                let names = objc2_foundation::NSArray::from_slice(&[
                    objc2_app_kit::NSAppearanceNameAqua,
                    objc2_app_kit::NSAppearanceNameDarkAqua,
                ]);
                let standard = self
                    .effectiveAppearance()
                    .bestMatchFromAppearancesWithNames(&names)
                    .and_then(|n| objc2_app_kit::NSAppearance::appearanceNamed(&n));
                match standard {
                    Some(appearance) => {
                        let block = block2::StackBlock::new(paint);
                        appearance.performAsCurrentDrawingAppearance(&block);
                    }
                    None => paint(),
                }
            }
        }
    }
    unsafe impl NSObjectProtocol for DayFlipped {}
    unsafe impl NSDraggingSource for DayFlipped {
        #[unsafe(method(draggingSession:sourceOperationMaskForDraggingContext:))]
        fn source_mask(&self, _session: &objc2_app_kit::NSDraggingSession, _context: objc2_app_kit::NSDraggingContext) -> objc2_app_kit::NSDragOperation { objc2_app_kit::NSDragOperation::Copy }
    }
    impl DayFlipped {
        #[unsafe(method(mouseDragged:))]
        fn transfer_dragged(&self, event: &NSEvent) {
            if !transfer::dragged(self, event) { let _: () = unsafe { msg_send![super(self), mouseDragged: event] }; }
        }
        #[unsafe(method(draggingEntered:))]
        fn transfer_entered(&self, info: &ProtocolObject<dyn objc2_app_kit::NSDraggingInfo>) -> objc2_app_kit::NSDragOperation { transfer::proposal(self, info) }
        #[unsafe(method(draggingUpdated:))]
        fn transfer_updated(&self, info: &ProtocolObject<dyn objc2_app_kit::NSDraggingInfo>) -> objc2_app_kit::NSDragOperation { transfer::proposal(self, info) }
        #[unsafe(method(performDragOperation:))]
        fn transfer_drop(&self, info: &ProtocolObject<dyn objc2_app_kit::NSDraggingInfo>) -> bool { transfer::receive(self, info) }
    }

);

impl DayFlipped {
    fn new(mtm: MainThreadMarker) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(FlippedIvars::default());
        unsafe { msg_send![super(this), init] }
    }

    /// Apply a `background`/`corner_radius` surface. The fill (rounded by `corner_radius`) is
    /// drawn in `drawRect` with NSColor, not via the layer's `backgroundColor`, whose CGColorRef
    /// argument objc2's `msg_send` cannot type-check. A rounded child clip does use the CALayer
    /// (`cornerRadius` + `masksToBounds` are a CGFloat + `BOOL`, which are fine).
    /// SurfaceRole::SectionCard: the fill resolves dynamically in drawRect (theme-adaptive).
    fn set_section_card(&self, corner_radius: f64) {
        self.ivars().section_card.set(Some(corner_radius));
        unsafe {
            let _: () = msg_send![self, setNeedsDisplay: true];
        }
    }

    /// Opaque window-background backdrop (the inspector panel wrap; see `FlippedIvars`).
    fn set_pane_backdrop(&self) {
        self.ivars().pane_backdrop.set(true);
        unsafe {
            let _: () = msg_send![self, setNeedsDisplay: true];
        }
    }

    fn set_surface(&self, bg: Option<day_spec::Color>, corner_radius: f64, clips: bool) {
        self.ivars()
            .surface
            .set(bg.map(|c| (c.r, c.g, c.b, c.a, corner_radius)));
        unsafe {
            let _: () = msg_send![self, setNeedsDisplay: true];
            if clips || corner_radius > 0.0 {
                let _: () = msg_send![self, setWantsLayer: true];
                let layer: *mut objc2::runtime::AnyObject = msg_send![self, layer];
                if !layer.is_null() {
                    let _: () = msg_send![layer, setCornerRadius: corner_radius];
                    let _: () = msg_send![layer, setMasksToBounds: true];
                }
            }
        }
    }
}

// ---------------------------------------------------------------------------
// DayCanvas — a flipped view replaying the Day display list in drawRect (§11)
// ---------------------------------------------------------------------------

struct CanvasIvars;

define_class!(
    #[unsafe(super(NSView))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayCanvas"]
    #[ivars = CanvasIvars]
    struct DayCanvas;

    impl DayCanvas {
        #[unsafe(method(isFlipped))]
        fn is_flipped(&self) -> bool {
            true
        }

        /// A summon-time context menu (docs/menus.md): built when the right-click lands,
        /// from the provider `set_context_menu_fn` registered — so a canvas can select what
        /// is under the pointer and offer commands for that selection.
        #[unsafe(method_id(menuForEvent:))]
        fn menu_for_event(
            &self,
            event: &objc2_app_kit::NSEvent,
        ) -> Option<Retained<NSMenu>> {
            let f = CTX_MENU_FNS.with(|t| t.get(self as *const Self as usize));
            let Some(f) = f else {
                return unsafe { msg_send![super(self), menuForEvent: event] };
            };
            // Guarded: the provider is app code (it usually re-selects, then builds).
            ffi_guard::contain(None, || {
                let p = self.convertPoint_fromView(unsafe { event.locationInWindow() }, None);
                let items = f(day_spec::Point::new(p.x, p.y));
                if items.is_empty() {
                    return None;
                }
                Some(build_ns_menu(self.mtm(), "", &items))
            })
        }

        // Focus, and with it the keyboard (docs/focus.md, docs/menus.md). A canvas is the one
        // built-in piece with no native control under it, so nothing else would ever make it
        // the first responder — and without that, arrow keys aimed at what it draws could only
        // be caught by watching the whole app.
        #[unsafe(method(acceptsFirstResponder))]
        fn accepts_first_responder(&self) -> bool {
            true
        }

        // Clicking a canvas focuses it, the way clicking a table or a text field does. The
        // gesture recognizers (tap/drag) still see the press — this runs before `super`, which
        // is what forwards it to them.
        #[unsafe(method(mouseDown:))]
        fn mouse_down(&self, event: &objc2_app_kit::NSEvent) {
            if let Some(window) = self.window() {
                window.makeFirstResponder(Some(self));
            }
            let _: () = unsafe { msg_send![super(self), mouseDown: event] };
        }

        // Report focus both ways, so `.focused(signal)` binds two-way and dayscript's
        // `assert_focused` can see it.
        #[unsafe(method(becomeFirstResponder))]
        fn become_first_responder(&self) -> bool {
            let ptr = (self as *const DayCanvas).cast::<NSView>() as usize;
            if let Some(node) = KEY_NODES.with(|t| t.get(ptr)) {
                ffi_guard::contain((), || emit(node, Event::FocusChanged(true)));
            }
            true
        }

        #[unsafe(method(resignFirstResponder))]
        fn resign_first_responder(&self) -> bool {
            let ptr = (self as *const DayCanvas).cast::<NSView>() as usize;
            if let Some(node) = KEY_NODES.with(|t| t.get(ptr)) {
                ffi_guard::contain((), || emit(node, Event::FocusChanged(false)));
            }
            true
        }

        /// The arrows, delivered to this canvas because it is the first responder. Anything
        /// else — and every arrow when the app registered no handler for this node — goes to
        /// `super`, which walks the responder chain exactly as it would have without us.
        #[unsafe(method(keyDown:))]
        fn key_down(&self, event: &objc2_app_kit::NSEvent) {
            let ptr = (self as *const DayCanvas).cast::<NSView>() as usize;
            let handled = ffi_guard::contain(false, || {
                let Some(node) = KEY_NODES.with(|t| t.get(ptr)) else {
                    return false;
                };
                let Some(key) = key_name(event) else {
                    return false;
                };
                // A canvas nobody asked keys from does not get to keep them: an enclosing
                // scroll view still scrolls, and an unclaimed key still beeps the way the
                // platform means it to.
                if !day_spec::keys::handled(node) {
                    return false;
                }
                emit(
                    node,
                    Event::Key(day_spec::KeyEvent {
                        key: key.to_string(),
                        modifiers: key_modifiers(event.modifierFlags()),
                    }),
                );
                true
            });
            if !handled {
                let _: () = unsafe { msg_send![super(self), keyDown: event] };
            }
        }

        #[unsafe(method(drawRect:))]
        fn draw_rect(&self, _dirty: NSRect) {
            let ptr = (self as *const DayCanvas).cast::<NSView>() as usize;
            let ops = OPS.with(|t| t.get(ptr)).unwrap_or_default();
            paint_ops(&ops);
        }

        /// Hover entry/motion/exit (docs/canvas.md "Interaction"). The tracking area is installed
        /// by `enable_gesture`; `updateTrackingAreas` below keeps it the size of the view.
        #[unsafe(method(mouseEntered:))]
        fn mouse_entered(&self, event: &objc2_app_kit::NSEvent) {
            self.report_hover(event, day_spec::DragPhase::Began);
        }

        #[unsafe(method(mouseMoved:))]
        fn mouse_moved(&self, event: &objc2_app_kit::NSEvent) {
            self.report_hover(event, day_spec::DragPhase::Changed);
        }

        #[unsafe(method(mouseExited:))]
        fn mouse_exited(&self, event: &objc2_app_kit::NSEvent) {
            self.report_hover(event, day_spec::DragPhase::Ended);
        }

        #[unsafe(method(scrollWheel:))]
        fn scroll_wheel(&self, event: &objc2_app_kit::NSEvent) {
            let ptr = (self as *const DayCanvas).cast::<NSView>() as usize;
            let Some(node) = PAN_NODES.with(|t| t.get(ptr)) else {
                let _: () = unsafe { msg_send![super(self), scrollWheel: event] };
                return;
            };
            ffi_guard::contain((), || {
                // Trackpads bracket a pan with phases; a discrete wheel tick has none and
                // arrives as a lone Changed — exactly the Event::Pan contract.
                let raw = unsafe { event.phase() };
                let phase = if raw.contains(objc2_app_kit::NSEventPhase::Began) {
                    day_spec::DragPhase::Began
                } else if raw.contains(objc2_app_kit::NSEventPhase::Ended)
                    || raw.contains(objc2_app_kit::NSEventPhase::Cancelled)
                {
                    day_spec::DragPhase::Ended
                } else {
                    day_spec::DragPhase::Changed
                };
                let delta = Point::new(unsafe { event.scrollingDeltaX() }, unsafe {
                    event.scrollingDeltaY()
                });
                let win = unsafe { event.locationInWindow() };
                let loc = self.convertPoint_fromView(win, None);
                emit(
                    node,
                    Event::Pan {
                        phase,
                        delta,
                        location: Point::new(loc.x, loc.y),
                    },
                );
            })
        }
    }
);

impl DayCanvas {
    fn new(mtm: MainThreadMarker) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(CanvasIvars);
        unsafe { msg_send![super(this), init] }
    }

    /// One hover phase, reported to whichever node asked for it (docs/canvas.md "Interaction").
    ///
    /// `mouseEntered:`/`mouseExited:` are scoped by the tracking area, but **`mouseMoved:` is
    /// not**: it walks the responder chain, so a focused canvas hears about motion anywhere in
    /// its window — including outside itself. Hence the bounds test, without which a canvas
    /// reports a hover for a pointer that is nowhere near it (measured: a pointer parked outside
    /// the window entirely still produced hover positions).
    fn report_hover(&self, event: &objc2_app_kit::NSEvent, phase: day_spec::DragPhase) {
        let ptr = (self as *const DayCanvas).cast::<NSView>() as usize;
        let Some(node) = HOVER_NODES.with(|t| t.get(ptr)) else {
            return;
        };
        ffi_guard::contain((), || {
            let win = unsafe { event.locationInWindow() };
            let loc = self.convertPoint_fromView(win, None);
            let b = self.bounds();
            let inside = loc.x >= b.origin.x
                && loc.x <= b.origin.x + b.size.width
                && loc.y >= b.origin.y
                && loc.y <= b.origin.y + b.size.height;
            // An exit is reported wherever it happens — that is the point of it — but a move
            // outside the view is not this view's hover.
            if !inside && phase != day_spec::DragPhase::Ended {
                return;
            }
            emit(
                node,
                Event::Hover {
                    phase,
                    location: Point::new(loc.x, loc.y),
                },
            );
        });
    }
}

/// The tracking area a hovering canvas needs. `InVisibleRect` makes it follow the view's bounds,
/// so there is no rect to keep in step with layout; `ActiveInKeyWindow` matches the cursor areas
/// already installed here — a background window does not report hovers.
fn install_tracking_area(h: &NSView) {
    let opts = NSTrackingAreaOptions::MouseEnteredAndExited
        | NSTrackingAreaOptions::MouseMoved
        | NSTrackingAreaOptions::ActiveInKeyWindow
        | NSTrackingAreaOptions::InVisibleRect;
    let any: &objc2::runtime::AnyObject = h;
    let area = unsafe {
        NSTrackingArea::initWithRect_options_owner_userInfo(
            NSTrackingArea::alloc(),
            NSRect::ZERO,
            opts,
            Some(any),
            None,
        )
    };
    unsafe { h.addTrackingArea(&area) };
}

// ---------------------------------------------------------------------------
// DayGesture — tap/drag recognizer target, node-id keyed (docs/shapes.md)
// ---------------------------------------------------------------------------

struct GestureIvars {
    node: NodeId,
    kind: day_spec::GestureKind,
}

define_class!(
    #[unsafe(super(NSObject))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayGesture"]
    #[ivars = GestureIvars]
    struct DayGesture;

    unsafe impl NSObjectProtocol for DayGesture {}

    impl DayGesture {
        #[unsafe(method(fire:))]
        fn fire(&self, g: &NSGestureRecognizer) {
            ffi_guard::contain((), || {
                let node = self.ivars().node;
                let view = g.view();
                let loc = g.locationInView(view.as_deref());
                let at = Point::new(loc.x, loc.y);
                let phase = match g.state() {
                    NSGestureRecognizerState::Began => day_spec::DragPhase::Began,
                    NSGestureRecognizerState::Ended
                    | NSGestureRecognizerState::Cancelled
                    | NSGestureRecognizerState::Failed => day_spec::DragPhase::Ended,
                    _ => day_spec::DragPhase::Changed,
                };
                let obj: &objc2::runtime::AnyObject = g.as_ref();
                match self.ivars().kind {
                    day_spec::GestureKind::Drag => {
                        let translation = if let Some(pan) = obj.downcast_ref::<NSPanGestureRecognizer>() {
                            let t = unsafe { pan.translationInView(view.as_deref()) };
                            Point::new(t.x, t.y)
                        } else {
                            Point::ZERO
                        };
                        emit(node, Event::Drag { phase, location: at, translation });
                    }
                    day_spec::GestureKind::Pinch => {
                        // Cumulative since Began: `magnification` is the total delta (0 =
                        // unchanged), and Day's contract wants a factor.
                        let scale = if let Some(m) =
                            obj.downcast_ref::<objc2_app_kit::NSMagnificationGestureRecognizer>()
                        {
                            1.0 + unsafe { m.magnification() }
                        } else {
                            1.0
                        };
                        emit(node, Event::Pinch { phase, scale, location: at });
                    }
                    _ => emit(node, Event::Tap(at)),
                }
            })
        }
    }
);

impl DayGesture {
    fn new(mtm: MainThreadMarker, node: NodeId, kind: day_spec::GestureKind) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(GestureIvars { node, kind });
        unsafe { msg_send![super(this), init] }
    }
}

// ---------------------------------------------------------------------------
// Navigation (docs/navigation.md): NSSplitView host, sidebar + detail panes.
// Page FRAMES are pane-owned (autoresized); Day lays content inside the size each
// page reports from setFrameSize:. Day's set_frame on pages is skipped.
// ---------------------------------------------------------------------------

/// The stack presentation's back header (desktop has no system back affordance — this bar
/// gives a pushed page its way out, like AdwNavigationView's header on GTK). Hidden at root.
struct NavHeader {
    bar: Retained<NSView>,
    title: Retained<NSTextField>,
    /// Title per stack level (index 0 = root); the field shows the last.
    titles: Vec<String>,
    _target: Retained<DayTarget>,
}

/// Height of the stack-nav back header while a pushed page is showing.
const NAV_HEADER_H: f64 = 34.0;

// Drag limits for both draggable panes come from day-spec (`NAV_SIDEBAR_MIN_W` and friends): a
// sidebar NSSplitViewItem enforces them itself, which is why the divider no longer needs
// restoring by hand after every window resize.
use day_spec::{NAV_LIST_MAX_W, NAV_LIST_MIN_W, NAV_SIDEBAR_MAX_W, NAV_SIDEBAR_MIN_W};

/// The content-list width to place divider 1 at, once, the first time the pane is showing —
/// `None` when the pane is collapsed or has already been placed. Latches on the way out, so the
/// two callers (the first frame pass, and the patch that reveals the pane) cannot both spend it.
fn take_list_placement(state: &mut NavState) -> Option<f64> {
    if !state.list_visible || state.list_positioned {
        return None;
    }
    state.list_positioned = true;
    state.list_width
}

/// A tabs host's `NSTabView` margins inside its pane: the sides and the foot, and the top —
/// deeper, since the tabs themselves stand about a segment's height above the bezel.
const NAV_TABVIEW_INSET: f64 = 12.0;
const NAV_TABVIEW_INSET_TOP: f64 = 8.0;

/// The `NavPresentation::Tabs` container: a real `NSTabView` — the Mac's own tab control, top
/// tabs on a bezel — whose items own the detail pages. The page frames stay native-owned
/// exactly as in a split: the tab view frames the selected item's view, and the page's
/// `setFrameSize:` reports it. The labels come from the NAV_MENU's rows, which arrive after
/// the pages' host (day-core mounts top-down: the rows page joins the host before its menu is
/// built), so `adopt_menu_for_tabs` runs when the menu is inserted and whenever its rows are
/// rebuilt.
///
/// Until 2026-09-12 this was an `NSSegmentedControl` docked at the foot, built from the rows
/// page's menu at the moment that page was inserted — before the menu existed — so no bar was
/// ever built and a tabs host showed its first page alone.
struct TabHost {
    view: Retained<objc2_app_kit::NSTabView>,
    /// The delegate reporting a native tab pick against the NAV_MENU's node; set once the menu
    /// is known.
    target: Option<Retained<DayTarget>>,
}

thread_local! {
    /// A Day-driven tab selection in flight (`NavPatch::Select`, a label sync): the tab view's
    /// delegate must not echo it back as `SelectionChanged`.
    static TAB_PICK_SUPPRESS: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
}

/// Give the tab view its labels from the rows, and its selection. Rows and items are
/// index-aligned (destination `i` is item `i`); a count mismatch mid-rebuild labels what both
/// have.
fn sync_tab_labels(tabs: &TabHost, titles: &[String], selected: usize) {
    unsafe {
        let n = tabs.view.numberOfTabViewItems().max(0) as usize;
        for (i, title) in titles.iter().enumerate().take(n) {
            tabs.view
                .tabViewItemAtIndex(i as isize)
                .setLabel(&NSString::from_str(title));
        }
        if n > 0 {
            TAB_PICK_SUPPRESS.with(|s| s.set(true));
            tabs.view
                .selectTabViewItemAtIndex(selected.min(n - 1) as isize);
            TAB_PICK_SUPPRESS.with(|s| s.set(false));
        }
    }
}

/// A NAV_MENU reached a tabs host (its rows page sits in the host's collapsed sidebar pane):
/// the menu's rows become the tab labels and its node the delegate's target. Walks up from the
/// menu, so the innermost host — the one whose rows these are — is the one that takes them.
fn adopt_menu_for_tabs(mtm: MainThreadMarker, menu: &NSView) {
    let Some((titles, node)) = NAV_MENUS.with(|m| {
        m.borrow().get(&ptr_of(menu)).map(|(_, d)| {
            let ivars = d.ivars();
            (
                ivars
                    .items
                    .borrow()
                    .iter()
                    .map(|s| s.to_string())
                    .collect::<Vec<String>>(),
                ivars.node,
            )
        })
    }) else {
        return;
    };
    let mut up = unsafe { menu.superview() };
    while let Some(v) = up {
        let reached = NAV_STATE.with(|m| {
            let mut m = m.borrow_mut();
            let Some(s) = m.get_mut(&ptr_of(&v)) else {
                return false;
            };
            let selected = s.selected;
            if let Some(tabs) = s.tabs.as_mut() {
                if tabs.target.is_none() {
                    let target = DayTarget::new(mtm, node);
                    unsafe {
                        tabs.view
                            .setDelegate(Some(ProtocolObject::from_ref(&*target)))
                    };
                    tabs.target = Some(target);
                }
                sync_tab_labels(tabs, &titles, selected);
            }
            true
        });
        if reached {
            return;
        }
        up = unsafe { v.superview() };
    }
}

struct NavState {
    sidebar_wrap: Retained<NSView>,
    detail_wrap: Retained<NSView>,
    /// The container behind the host view. A view holds NO strong reference to its controller,
    /// and the split view controller is what owns the items, their holding priorities, the
    /// sidebar's material and the split's delegate duties — so it has to be retained here or
    /// the sidebar loses its treatment the moment this realize returns.
    _split_vc: Retained<objc2_app_kit::NSSplitViewController>,
    /// The sidebar item, for the `SidebarToggle` duty (docs/toolbars.md). AppKit's own
    /// `NSToolbarToggleSidebarItem` reaches the controller through the responder chain; this is
    /// the path dayscript and any non-toolbar caller take.
    sidebar_item: Retained<objc2_app_kit::NSSplitViewItem>,
    /// The content-list pane (docs/navigation.md), `Some` only on a host whose
    /// `NavProps::list_width` was set: the wrap its `Pane::List` page fills, and the
    /// `contentList` split item `NavPatch::ListVisible` collapses. The pane PERSISTS through
    /// every presentation (`Cap::NavContentList` = Native) — a narrow window collapses the
    /// sidebar and keeps the list, exactly as a narrow Mail.app does.
    list_wrap: Option<Retained<NSView>>,
    list_item: Option<Retained<objc2_app_kit::NSSplitViewItem>>,
    /// The app's requested content-list width (`NavProps::list_width`) — applied once, at the
    /// first frame pass, by placing divider 1 (see `set_frame`).
    list_width: Option<f64>,
    /// Whether the content-list pane is showing (`NavProps::list_visible`, then
    /// `NavPatch::ListVisible`). Placing divider 1 for a pane that is collapsed is what re-opens
    /// it, so both placement paths ask first.
    list_visible: bool,
    /// Whether divider 1 has been placed at the app's requested width yet. Separate from
    /// `positioned` because the pane may not exist on screen when the first frame pass runs: an
    /// app opening on a full-width destination has nothing to size then, and spending the
    /// one-time placement there is what left the list at the solver's own width when it did
    /// appear.
    list_positioned: bool,
    /// Detail pages in stack order (the sidebar page is not in here in split mode; in stack
    /// mode `split == false`, the root page is here too, so push/pop visibility covers it).
    pages: Vec<Retained<NSView>>,
    /// The host's sidebar page, once it has one — what a re-present moves between the sidebar
    /// pane and the head of `pages` (docs/size-classes.md).
    sidebar_page: Option<Retained<NSView>>,
    /// The content-list pane's page, re-framed when the pane is first revealed: it was inserted
    /// into a collapsed wrap, where autoresizing can only keep it at zero.
    list_page: Option<Retained<NSView>>,
    positioned: bool,
    /// Which of the four presentations is drawn right now (docs/size-classes.md). All of them are
    /// the same `NSSplitViewController`: a stack is that split with its sidebar collapsed, a rail
    /// is it with a narrow one, and a tab bar is a collapsed sidebar plus the bottom bar below.
    presentation: NavPresentation,
    /// The detail page on screen, as an index into `pages`. Maintained by every patch that
    /// changes it — push, pop and select alike — so a re-present can carry it across.
    selected: usize,
    /// The tab view (`NavPresentation::Tabs` only), holding the detail pages as its items and
    /// labeled from the same rows the sidebar's outline view shows; a pick emits
    /// `SelectionChanged` against the same NAV_MENU node.
    tabs: Option<TabHost>,
    /// Back header (stack presentation only).
    header: Option<NavHeader>,
    /// The host's own title, kept so a re-present into a stack can seed a fresh back header
    /// with the same root title the initial build would have used.
    root_title: String,
    /// The host's node, for the same reason — a back header's button targets it.
    node: NodeId,
    /// How far the host reaches up under the window's title bar (see `pane_under_title_bar`):
    /// the strip each pane's wrap is kept below. Zero for a host that does not start at the top
    /// of a pinned window.
    title_strip: f64,
}

/// A split item's view: a transparent pane that runs the item's full height, with `wrap` (the
/// view Day's pages and the rest of this backend frame themselves against) inside it.
///
/// `NSSplitViewController` expects its split view to reach the top of a full-size-content window
/// and lays its title-bar treatment over the top of every item: a title-bar background, and on
/// macOS 26 and later the frosted scroll pocket. Day pins its content below the title bar
/// (`pin_below_title_bar`), so a split framed where Day lays it out put that treatment over the
/// first strip of every page instead, blurring a detail page's heading. The host is framed up
/// under the bar instead (`set_frame`), and each wrap is held below the strip inside its pane, so
/// the treatment lands on the bar, the sidebar's material runs to the top of the window as
/// `allowsFullHeightLayout` intends, and every page still starts where Day laid it out.
fn pane_under_title_bar(mtm: MainThreadMarker, wrap: &NSView) -> Retained<NSView> {
    let pane = view_of(DayFlipped::new(mtm));
    unsafe {
        wrap.setFrame(pane.bounds());
        wrap.setAutoresizingMask(
            objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable
                | objc2_app_kit::NSAutoresizingMaskOptions::ViewHeightSizable,
        );
        pane.addSubview(wrap);
    }
    pane
}

/// Hold `wrap` `strip` points below the top of the pane that holds it.
fn place_below_strip(wrap: &NSView, strip: f64) {
    let Some(pane) = (unsafe { wrap.superview() }) else {
        return;
    };
    let b = pane.bounds();
    unsafe {
        wrap.setFrame(NSRect::new(
            NSPoint::new(0.0, strip),
            NSSize::new(b.size.width, (b.size.height - strip).max(0.0)),
        ))
    };
}

/// The stack presentation's back header: a chevron + centered title docked above the pages,
/// hidden at the root. Desktop has no system back affordance, so a pushed page carries its own
/// way out (docs/navigation.md).
///
/// Built here rather than inline because a host that RE-PRESENTS into a stack needs one at that
/// moment (docs/size-classes.md), and a header that differed from the one a stack-at-launch host
/// gets would be a second shape to keep in step.
fn build_nav_header(
    mtm: MainThreadMarker,
    id: NodeId,
    detail_wrap: &NSView,
    root_title: &str,
) -> NavHeader {
    let bar = view_of(DayFlipped::new(mtm));
    let target = DayTarget::new(mtm, id);
    let back = unsafe {
        // Invariant: NSImageNameGoBackTemplate is one of AppKit's own named images, present
        // on every macOS release this backend builds for.
        let img = objc2_app_kit::NSImage::imageNamed(objc2_app_kit::NSImageNameGoBackTemplate)
            .expect("NSGoBackTemplate");
        let tobj: &objc2::runtime::AnyObject = target.as_ref();
        objc2_app_kit::NSButton::buttonWithImage_target_action(
            &img,
            Some(tobj),
            Some(sel!(navBack:)),
            mtm,
        )
    };
    let title = unsafe { NSTextField::labelWithString(&NSString::from_str(root_title), mtm) };
    unsafe {
        back.setFrame(NSRect::new(
            NSPoint::new(6.0, 4.0),
            NSSize::new(30.0, NAV_HEADER_H - 8.0),
        ));
        title.setFont(Some(&NSFont::boldSystemFontOfSize(13.0)));
        title.setAlignment(objc2_app_kit::NSTextAlignment::Center);
        title.setLineBreakMode(objc2_app_kit::NSLineBreakMode::ByTruncatingTail);
        title.setFrame(NSRect::new(
            NSPoint::new(44.0, 9.0),
            NSSize::new((detail_wrap.bounds().size.width - 88.0).max(0.0), 18.0),
        ));
        title.setAutoresizingMask(objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable);
        bar.setFrame(NSRect::new(
            NSPoint::new(0.0, 0.0),
            NSSize::new(detail_wrap.bounds().size.width, NAV_HEADER_H),
        ));
        bar.setAutoresizingMask(objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable);
        bar.addSubview(&back);
        bar.addSubview(&title);
        bar.setHidden(true);
        detail_wrap.addSubview(&bar);
    }
    NavHeader {
        bar,
        title,
        titles: vec![root_title.to_string()],
        _target: target,
    }
}

/// The frame a stack page occupies inside the detail wrap: full bounds at the root, inset below
/// the back header while a pushed page is showing. (A tabs host's pages are framed by its
/// `NSTabView`, never through here.)
fn nav_page_frame(wrap: &NSView, header_visible: bool) -> NSRect {
    let b = wrap.bounds();
    let top = if header_visible { NAV_HEADER_H } else { 0.0 };
    NSRect::new(
        NSPoint::new(0.0, top),
        NSSize::new(b.size.width, (b.size.height - top).max(0.0)),
    )
}

/// The row titles and the NAV_MENU node of the menu inside `page`, if it has one.
///
/// The tab bar needs the same rows the sidebar shows, and they arrive at the NAV_MENU rather
/// than at the host. Rather than plumb a second copy through the props, this walks down to the
/// menu that is already there — the sidebar page is Day-built and shallow, so the search is a
/// handful of views — and reads the titles it has stored for its own outline view.
fn nav_menu_rows(page: &NSView) -> Option<(Vec<String>, NodeId)> {
    fn walk(v: &NSView, out: &mut Option<(Vec<String>, NodeId)>) {
        if out.is_some() {
            return;
        }
        let found = NAV_MENUS.with(|m| {
            m.borrow()
                .get(&(v as *const NSView as usize))
                .map(|(_, d)| {
                    let ivars = d.ivars();
                    (
                        ivars.items.borrow().iter().map(|s| s.to_string()).collect(),
                        ivars.node,
                    )
                })
        });
        if found.is_some() {
            *out = found;
            return;
        }
        for sub in unsafe { v.subviews() }.iter() {
            walk(&sub, out);
        }
    }
    let mut out = None;
    walk(page, &mut out);
    out
}

/// Apply a presentation to the sidebar split item. All four are the same item at a different
/// thickness or collapsed outright, which is why a morph never rebuilds the split.
fn apply_sidebar_item(item: &objc2_app_kit::NSSplitViewItem, pres: NavPresentation) {
    let shown = matches!(pres, NavPresentation::Split | NavPresentation::Rail);
    unsafe {
        item.setCanCollapse(shown);
        item.setCollapsed(!shown);
        match pres {
            NavPresentation::Split => {
                item.setAllowsFullHeightLayout(true);
                item.setMinimumThickness(NAV_SIDEBAR_MIN_W);
                item.setMaximumThickness(NAV_SIDEBAR_MAX_W);
            }
            // macOS has no rail: nothing in AppKit is a vertical strip of icon-only
            // destinations, and a source list pinned to icon width just truncates every row to an
            // ellipsis. `NavPresentation::Rail` is explicitly ROUNDABLE for exactly this case, so
            // it lands on the neighbor a Mac does have — an ordinary sidebar. Windows rounds the
            // other way (`PaneDisplayMode = LeftCompact` is a real rail there).
            NavPresentation::Rail => {
                item.setAllowsFullHeightLayout(true);
                item.setMinimumThickness(NAV_SIDEBAR_MIN_W);
                item.setMaximumThickness(NAV_SIDEBAR_MAX_W);
            }
            // Zero the thickness bounds before collapsing takes effect, or the pane keeps a
            // minimum width and the detail never reaches the window edge.
            NavPresentation::Stack | NavPresentation::Tabs => {
                item.setMinimumThickness(0.0);
                item.setMaximumThickness(0.0);
            }
        }
    }
}

/// Show/hide the stack-nav back header for the given page stack and re-frame the pages under
/// it. The header shows exactly while a pushed page (depth ≥ 1 above the root) is on top; each
/// page's `DayNavPage::setFrameSize` reports the new size so Day re-lays its content.
/// The split view of the navigation host in `window` that has a content-list pane, for the
/// tracking separator pinned to its second divider (docs/toolbars.md).
pub(crate) fn list_split_view(window: usize) -> Option<Retained<objc2_app_kit::NSSplitView>> {
    NAV_STATE.with(|m| {
        m.borrow()
            .values()
            .find(|st| {
                st.list_item.is_some()
                    && st
                        .sidebar_wrap
                        .window()
                        .is_some_and(|w| Retained::as_ptr(&w) as usize == window)
            })
            .map(|st| unsafe { st._split_vc.splitView() })
    })
}

fn sync_nav_header(hdr: &NavHeader, wrap: &NSView, pages: &[Retained<NSView>]) {
    let visible = pages.len() >= 2;
    hdr.bar.setHidden(!visible);
    unsafe {
        hdr.title.setStringValue(&NSString::from_str(
            hdr.titles.last().map(String::as_str).unwrap_or(""),
        ));
    }
    let frame = nav_page_frame(wrap, visible);
    for page in pages {
        unsafe { page.setFrame(frame) };
    }
}

/// Re-present a live nav host (docs/size-classes.md): the window crossed a breakpoint, so the
/// chrome changes but the pages do not.
///
/// Both presentations already share one `NSSplitViewController` — a stack is the same split with
/// its sidebar item collapsed to zero thickness — so the morph is three moves, and none of them
/// touches a page's CONTENT:
///
/// 1. the sidebar item collapses or expands (AppKit animates it and re-runs the titlebar
///    separator on its own),
/// 2. the sidebar PAGE moves between the sidebar wrap and the head of the detail stack,
/// 3. the back header appears or hides, since only a stack has one.
///
/// `addSubview` re-parents a view rather than rebuilding it, so every page keeps its subtree,
/// its scroll position, and its first responder across the move.
fn nav_present(mtm: MainThreadMarker, host: &Handle, next: NavPresentation) {
    let Some((sidebar_page, detail_wrap, sidebar_wrap, sidebar_item, was, root_title, id, sel)) =
        NAV_STATE.with(|m| {
            let st = m.borrow();
            let s = st.get(&ptr_of(host))?;
            Some((
                s.sidebar_page.clone(),
                s.detail_wrap.clone(),
                s.sidebar_wrap.clone(),
                s.sidebar_item.clone(),
                s.presentation,
                s.root_title.clone(),
                s.node,
                s.selected,
            ))
        })
    else {
        return;
    };
    if was == next {
        return;
    }
    apply_sidebar_item(&sidebar_item, next);
    // Settle the split now rather than at the next natural layout pass. `setCollapsed` marks the
    // split view as needing layout; without this the pane keeps its old width for one more frame,
    // which the dayscript screenshot seam captures (it renders the window offscreen the instant
    // the patch returns) and which a user crossing a breakpoint sees as a stutter.
    NAV_STATE.with(|m| {
        if let Some(s) = m.borrow().get(&ptr_of(host)) {
            unsafe { s._split_vc.splitView().layoutSubtreeIfNeeded() };
        }
    });
    // A stack needs a back header; nothing else may show one. Built on demand and kept
    // afterwards — rebuilding it on every morph would leak a target per crossing.
    let stacked = next == NavPresentation::Stack;
    let mut header = NAV_STATE.with(|m| m.borrow_mut().get_mut(&ptr_of(host))?.header.take());
    if stacked && header.is_none() {
        header = Some(build_nav_header(mtm, id, &detail_wrap, &root_title));
    }
    if let Some(hdr) = header.as_ref() {
        hdr.bar.setHidden(true);
    }
    // No tab view here: `Tabs` is a PINNED style on this backend (`Cap::NavTabsAdaptive` is
    // off), resolved the same at every width, so a host never morphs into or out of it — its
    // `NSTabView` is built at realize and lives for the host.
    // Which page is on screen, by IDENTITY: moving the sidebar page in or out of the detail list
    // shifts every index past it, so an index captured now would name the wrong page after.
    let mut pages = NAV_STATE.with(|m| {
        m.borrow()
            .get(&ptr_of(host))
            .map(|s| s.pages.clone())
            .unwrap_or_default()
    });
    let shown_page = pages.get(sel).cloned();
    // The sidebar page is a stack ROOT only while stacked; otherwise it lives in its own pane,
    // which is the sidebar in `Split`/`Rail` and a collapsed one behind a tab bar in `Tabs`.
    if let Some(page) = sidebar_page {
        pages.retain(|p| ptr_of(p) != ptr_of(&page));
        unsafe {
            if stacked {
                detail_wrap.addSubview(&page);
                pages.insert(0, page.clone());
            } else {
                page.setFrame(sidebar_wrap.bounds());
                sidebar_wrap.addSubview(&page);
            }
        }
        // A pane always shows its page; as a stack root it may have been hidden under a push.
        page.setHidden(false);
    }
    let shown = shown_page
        .and_then(|p| pages.iter().position(|q| ptr_of(q) == ptr_of(&p)))
        .unwrap_or_else(|| pages.len().saturating_sub(1));
    for (i, page) in pages.iter().enumerate() {
        page.setHidden(i != shown);
    }
    NAV_STATE.with(|m| {
        let mut m = m.borrow_mut();
        if let Some(s) = m.get_mut(&ptr_of(host)) {
            s.presentation = next;
            s.pages = pages;
            s.selected = shown;
            s.header = header;
            if let Some(hdr) = s.header.as_ref() {
                // Depth drives visibility, and the header is meaningless anywhere but a stack.
                if stacked {
                    sync_nav_header(hdr, &s.detail_wrap, &s.pages);
                } else {
                    hdr.bar.setHidden(true);
                }
            }
            if !stacked {
                // Leaving the stack: the pages were inset below the header, so give them the
                // pane back.
                let frame = nav_page_frame(&s.detail_wrap, false);
                for page in &s.pages {
                    unsafe { page.setFrame(frame) };
                }
            }
        }
    });
}

// ---------------------------------------------------------------------------
// The sidebar pane holds its width through NSSplitViewController's own holding priorities
// (docs/navigation.md) — a sidebar NSSplitViewItem pins its thickness and lets the detail
// absorb a window resize, which is exactly the Finder/Mail behavior the hand-rolled
// `splitView:shouldAdjustSizeOfSubview:` delegate used to approximate. The controller IS the
// split's delegate, so Day must not install one of its own.
// ---------------------------------------------------------------------------

struct CoverSheet(Retained<NSWindow>);
impl Drop for CoverSheet {
    fn drop(&mut self) {
        // Sheet transitions may run a nested AppKit update cycle. Defer them until the
        // core's tree borrow has ended; this retained pointer travels only to the main queue.
        let raw = Retained::into_raw(self.0.clone()) as usize;
        dispatch2::DispatchQueue::main().exec_async(move || {
            ffi_guard::contain((), || unsafe {
                let window = Retained::from_raw(raw as *mut NSWindow).unwrap();
                if let Some(parent) = window.sheetParent() {
                    parent.endSheet(&window);
                }
                window.orderOut(None);
                window.setContentView(None);
            });
        });
    }
}
struct NavPageIvars {
    node: NodeId,
    /// A presented cover's strip under the window's title bar: the page paints it (its frame
    /// starts above the layout area) but lays its content out below it, and reports the
    /// remaining height (see `pin_below_title_bar`).
    top_inset: Cell<f64>,
    sheet: Cell<bool>,
    /// A half sheet (docs/cover.md): the window sheet stands half the parent's height.
    half: Cell<bool>,
}

define_class!(
    #[unsafe(super(NSView))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayNavPage"]
    #[ivars = NavPageIvars]
    struct DayNavPage;

    impl DayNavPage {
        #[unsafe(method(isFlipped))]
        fn is_flipped(&self) -> bool {
            true
        }

        #[unsafe(method(setFrameSize:))]
        fn set_frame_size(&self, size: NSSize) {
            let _: () = unsafe { msg_send![super(self), setFrameSize: size] };
            // Pane-driven resize (splitter drag, window resize): report the usable size
            // so NavLayout re-lays this page's content (enqueue-only, §8.3).
            ffi_guard::contain((), || {
                let inset = self.ivars().top_inset.get();
                emit(
                    self.ivars().node,
                    Event::FrameChanged(Size::new(size.width, (size.height - inset).max(0.0))),
                );
            })
        }
    }
);

impl DayNavPage {
    fn new(mtm: MainThreadMarker, node: NodeId) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(NavPageIvars {
            node,
            top_inset: Cell::new(0.0),
            sheet: Cell::new(false),
            half: Cell::new(false),
        });
        unsafe { msg_send![super(this), init] }
    }
}

// ---------------------------------------------------------------------------
// Inspector (docs/inspector.md): an NSSplitViewController whose trailing pane is a REAL
// inspector item (`inspectorWithViewController:`) — the system treatment for exactly this
// surface: its own backing material, the standard thickness handling, full-height layout
// under the titlebar. Day's bound signal is the only visibility driver (the item cannot be
// user-collapsed), so this backend never emits `Event::InspectorChanged`.
// ---------------------------------------------------------------------------

struct InspectorState {
    content_wrap: Handle,
    panel_wrap: Handle,
    /// Retained so the controller (the split's delegate) lives as long as its split.
    _split_vc: Retained<objc2_app_kit::NSSplitViewController>,
    panel_item: Retained<objc2_app_kit::NSSplitViewItem>,
}

// ---------------------------------------------------------------------------
// Split (docs/split.md): a plain `NSSplitView` inside a flipped wrap (the wrap is the handle,
// so `set_frame`'s nav-host treatment of split views never sees it), two arranged flipped
// subviews as the panes, and a delegate that places the divider by the bound share, keeps
// both panes above the minimum, and reports a drag back as the new share.
// ---------------------------------------------------------------------------

struct SplitState {
    split: Retained<objc2_app_kit::NSSplitView>,
    first_wrap: Handle,
    second_wrap: Handle,
    delegate: Retained<DaySplitDelegate>,
}

struct SplitDelegateIvars {
    node: NodeId,
    min_pane: f64,
    /// The share as last patched or reported: what a report is compared against, and where
    /// the divider goes when the split first has a size or turns.
    share: Cell<f64>,
    /// The divider has been placed once; before that the split has no size to place it in.
    positioned: Cell<bool>,
    /// Day is moving the divider itself: the resize that follows is not a report.
    suppress: Cell<bool>,
}

define_class!(
    #[unsafe(super(NSObject))]
    #[thread_kind = MainThreadOnly]
    #[name = "DaySplitDelegate"]
    #[ivars = SplitDelegateIvars]
    struct DaySplitDelegate;

    unsafe impl NSObjectProtocol for DaySplitDelegate {}

    unsafe impl NSSplitViewDelegate for DaySplitDelegate {
        #[unsafe(method(splitViewDidResizeSubviews:))]
        fn did_resize(&self, notification: &NSNotification) {
            ffi_guard::contain((), || {
                let Some(obj) = notification.object() else {
                    return;
                };
                let Ok(sv) = obj.downcast::<objc2_app_kit::NSSplitView>() else {
                    return;
                };
                let iv = self.ivars();
                let usable = split_usable(&sv);
                if usable <= 0.0 {
                    return;
                }
                // The first resize with a size: place the divider by the share, once.
                if !iv.positioned.replace(true) {
                    split_place(&sv, iv);
                    return;
                }
                if iv.suppress.get() {
                    return;
                }
                let Some(first) = sv.subviews().iter().next() else {
                    return;
                };
                let f = first.frame();
                let a = if sv.isVertical() {
                    f.size.width
                } else {
                    f.size.height
                };
                let share = (a / usable).clamp(0.0, 1.0);
                if (share - iv.share.get()).abs() > 1e-4 {
                    iv.share.set(share);
                    emit(iv.node, Event::ValueChanged(share));
                }
            })
        }

        #[unsafe(method(splitView:constrainMinCoordinate:ofSubviewAt:))]
        fn constrain_min(
            &self,
            _sv: &objc2_app_kit::NSSplitView,
            proposed: f64,
            _index: isize,
        ) -> f64 {
            proposed.max(self.ivars().min_pane)
        }

        #[unsafe(method(splitView:constrainMaxCoordinate:ofSubviewAt:))]
        fn constrain_max(
            &self,
            sv: &objc2_app_kit::NSSplitView,
            proposed: f64,
            _index: isize,
        ) -> f64 {
            proposed.min((split_usable(sv) - self.ivars().min_pane).max(0.0))
        }
    }
);

impl DaySplitDelegate {
    fn new(mtm: MainThreadMarker, node: NodeId, min_pane: f64, share: f64) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(SplitDelegateIvars {
            node,
            min_pane,
            share: Cell::new(share.clamp(0.0, 1.0)),
            positioned: Cell::new(false),
            suppress: Cell::new(false),
        });
        unsafe { msg_send![super(this), init] }
    }
}

/// The length the two panes share along the split's axis: the frame minus the divider.
fn split_usable(sv: &objc2_app_kit::NSSplitView) -> f64 {
    let frame = sv.frame();
    let len = if sv.isVertical() {
        frame.size.width
    } else {
        frame.size.height
    };
    (len - sv.dividerThickness()).max(0.0)
}

/// Move the divider so the first pane takes the share, silently (Day's own write, not a drag).
fn split_place(sv: &objc2_app_kit::NSSplitView, iv: &SplitDelegateIvars) {
    let usable = split_usable(sv);
    if usable <= 0.0 {
        return;
    }
    iv.suppress.set(true);
    unsafe { sv.setPosition_ofDividerAtIndex(iv.share.get() * usable, 0) };
    iv.suppress.set(false);
}

// ---------------------------------------------------------------------------

// ---------------------------------------------------------------------------
// DayNavMenuData — flat NSOutlineView source list for nav_menu() (docs/navigation.md)
// ---------------------------------------------------------------------------

struct NavMenuIvars {
    node: NodeId,
    items: RefCell<Vec<Retained<NSString>>>,
    /// Pre-resolved template icons per row (docs/navigation.md), `None` where a row has no icon.
    /// Template images tint with the source-list's selection/appearance, so they read in light,
    /// dark, and while selected — the macOS-idiomatic sidebar look (Finder/Mail).
    icons: RefCell<Vec<Option<Retained<objc2_app_kit::NSImage>>>>,
    /// How much of each icon's box its drawing spans (`nav_icon_fill`), index-aligned with
    /// `icons`: the cell sizes the icon so the drawing matches a system sidebar glyph.
    icon_fills: RefCell<Vec<f64>>,
    /// Per-row icon tint (docs/vectors.md): recolors the template glyph via contentTintColor;
    /// `None` keeps the source-list's neutral template tint.
    tints: RefCell<Vec<Option<day_spec::Color>>>,
    /// Trailing accessory per item row (an unread count), `None` where a row has none.
    badges: RefCell<Vec<Option<Retained<NSString>>>>,
    /// Trailing accessory GLYPH per row, in the same slot as `badges` and drawn after it —
    /// a starred page's star. Resolved to images once per rebuild, like `icons`.
    icon_progress: RefCell<Vec<(usize, Option<f64>)>>,
    badge_icons: RefCell<Vec<Option<Retained<objc2_app_kit::NSImage>>>>,
    /// Tint for `badge_icons`; `None` keeps the neutral template tint.
    badge_tints: RefCell<Vec<Option<day_spec::Color>>>,
    /// Per-row context menu (docs/menus.md), empty = none. Built into an NSMenu and attached
    /// to the row's cell view, so a secondary click pops it like any native sidebar menu.
    menus: RefCell<Vec<Vec<day_spec::MenuItem>>>,
    /// Which items drag to reorder (`NavMenuProps::movable`); empty when none do.
    movable: RefCell<Vec<bool>>,
    /// Movable rows may cross section headers (`NavMenuProps::regroup`); set at creation.
    regroup: std::cell::Cell<bool>,
    /// Which movable items keep their section's sorted order (`NavMenuProps::sorted`).
    sorted: RefCell<Vec<bool>>,
    /// The outline's rows, in display order: `Some(i)` is item `i`, `None` is a section
    /// header. Day addresses rows by ITEM index, so every selection crossing the boundary
    /// goes through this map — a header must never shift what index 3 means.
    rows: RefCell<Vec<Option<usize>>>,
    /// One retained NSString per outline row: the row's text (a header's or an item's).
    row_objects: RefCell<Vec<Retained<NSString>>>,
    /// One NSNumber per outline row, holding the row's index: the outline's item IDENTITY.
    /// NSOutlineView matches items with `isEqual:`, so an NSString cannot be the identity —
    /// a section header titled "Controls" and an item titled "Controls" would collapse into one
    /// row, and the header would wear the item's icon. Row indexes are unique by construction.
    row_ids: RefCell<Vec<Retained<NSNumber>>>,
    /// Programmatic selection in flight: don't re-emit SelectionChanged.
    suppress: std::cell::Cell<bool>,
}

struct NavCellIvars {
    /// The trailing accessories (an unread count, a status glyph), when the row has any: the
    /// label ends before them.
    accessory: RefCell<Option<Retained<NSView>>>,
    /// The unread count among them, sized to follow the row's text.
    count: RefCell<Option<Retained<NSTextField>>>,
    /// How much of the icon's box its drawing spans (`nav_icon_fill`).
    icon_fill: std::cell::Cell<f64>,
}

define_class!(
    /// A sidebar row's cell. `NSTableCellView` lays out its icon and label itself, at the
    /// size the outline's row size style gives them: the system's Sidebar icon size setting,
    /// followed live (docs/navigation.md). This only makes room for the trailing accessories,
    /// which AppKit knows nothing about.
    #[unsafe(super(objc2_app_kit::NSTableCellView))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayNavCell"]
    #[ivars = NavCellIvars]
    struct DayNavCell;

    unsafe impl NSObjectProtocol for DayNavCell {}

    impl DayNavCell {
        #[unsafe(method(layout))]
        fn layout(&self) {
            let _: () = unsafe { msg_send![super(self), layout] };
            ffi_guard::contain((), || self.fit_accessories());
        }
    }
);

impl DayNavCell {
    fn new(mtm: MainThreadMarker) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(NavCellIvars {
            accessory: RefCell::new(None),
            count: RefCell::new(None),
            icon_fill: std::cell::Cell::new(1.0),
        });
        unsafe { msg_send![super(this), init] }
    }

    /// After AppKit's layout: the count takes a size two points under the label's, and the
    /// label, which AppKit stretches to the cell's trailing edge, ends 6pt before the
    /// accessories so a long title truncates instead of running under its count. A showing
    /// progress ring re-fits the icon AppKit just sized.
    fn fit_accessories(&self) {
        let label = unsafe { self.textField() };
        if let (Some(label), Some(count)) = (&label, self.ivars().count.borrow().as_ref()) {
            let size = unsafe { label.font() }.map_or(NSFont::smallSystemFontSize(), |f| {
                (f.pointSize() - 2.0).max(9.0)
            });
            if unsafe { count.font() }.is_none_or(|f| f.pointSize() != size) {
                unsafe {
                    count.setFont(Some(&NSFont::monospacedDigitSystemFontOfSize_weight(
                        size,
                        objc2_app_kit::NSFontWeightRegular,
                    )));
                }
                self.layoutSubtreeIfNeeded();
            }
        }
        if let (Some(label), Some(accessory)) = (label, self.ivars().accessory.borrow().as_ref()) {
            let mut frame = label.frame();
            let end = accessory.frame().origin.x - 6.0;
            if frame.origin.x + frame.size.width > end {
                frame.size.width = (end - frame.origin.x).max(0.0);
                label.setFrame(frame);
            }
        }
        if let Some(icon) = unsafe { self.imageView() } {
            fit_nav_icon(&icon, self.ivars().icon_fill.get());
            nav_progress::fit(&icon);
        }
    }
}

thread_local! {
    /// The side of a system sidebar glyph per symbol configuration (see `fit_nav_icon`).
    static NAV_GLYPH_SIDES: RefCell<HashMap<u64, f64>> = RefCell::new(HashMap::new());
}

/// Draw a sidebar row's icon so its drawing is the size a system sidebar draws its SF Symbol,
/// centered in the slot AppKit lays out for it; `fill` is how much of the image's box the
/// drawing spans (`nav_icon_fill`). The slot is wider than the glyph AppKit puts there (22pt for a
/// 16pt glyph at Medium), and Day's icons are artwork that fills whatever frame it gets, so
/// left at the slot's size they read a third larger and heavier than Finder's or Mail's.
/// The side is measured, not tabled: a square symbol (`gearshape`) drawn with the symbol
/// configuration the row size style gave this image view, so it tracks the Sidebar icon size
/// setting and whatever a later macOS draws.
fn fit_nav_icon(icon: &objc2_app_kit::NSImageView, fill: f64) {
    let Some(config) = (unsafe { icon.symbolConfiguration() }) else {
        return;
    };
    let slot = icon.frame();
    // Configurations compare by value, and AppKit gives every cell of a row size style an
    // equal one, so the hash names the style.
    let key = config.hash() as u64;
    let side = NAV_GLYPH_SIDES
        .with(|m| m.borrow().get(&key).copied())
        .or_else(|| {
            let symbol =
                objc2_app_kit::NSImage::imageWithSystemSymbolName_accessibilityDescription(
                    &NSString::from_str("gearshape"),
                    None,
                )?;
            let side = symbol.imageWithSymbolConfiguration(&config)?.size().height;
            NAV_GLYPH_SIDES.with(|m| m.borrow_mut().insert(key, side));
            Some(side)
        });
    // The box that puts the drawing itself at the glyph's size: a Material Symbols icon keeps
    // the margin of its grid inside the box, so its box is that much larger.
    let Some(side) = side
        .filter(|s| *s > 0.0)
        .map(|s| (s / fill.clamp(0.25, 1.0)).round())
    else {
        return;
    };
    if slot.size.width <= side && slot.size.height <= side {
        return;
    }
    icon.setFrame(NSRect::new(
        NSPoint::new(
            (slot.origin.x + (slot.size.width - side) / 2.0).round(),
            (slot.origin.y + (slot.size.height - side) / 2.0).round(),
        ),
        NSSize::new(side, side),
    ));
}

define_class!(
    #[unsafe(super(objc2_app_kit::NSTableRowView))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayNavRowView"]
    struct DayNavRowView;

    unsafe impl NSObjectProtocol for DayNavRowView {}

    impl DayNavRowView {
        /// Always report the emphasized (key-window) state, so the selected sidebar row draws
        /// the accent pill with auto-whitened label/icon in both themes. Without this, a run
        /// whose window never becomes key (scripted screenshot captures) falls back to the
        /// unemphasized selection fill, which under a forced appearance rendered as a
        /// near-black pill that swallowed the row's label.
        #[unsafe(method(isEmphasized))]
        fn is_emphasized(&self) -> bool {
            true
        }
    }
);

define_class!(
    #[unsafe(super(objc2_app_kit::NSOutlineView))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayNavOutlineView"]
    struct DayNavOutlineView;

    unsafe impl NSObjectProtocol for DayNavOutlineView {}

    impl DayNavOutlineView {
        /// The clicked row's context menu (docs/menus.md): NSTableView-family views consume
        /// right-clicks themselves, so per-row menus are served here — resolve the row under
        /// the click, then build the same NSMenu the piece decorator would.
        #[unsafe(method_id(menuForEvent:))]
        fn menu_for_event(
            &self,
            event: &objc2_app_kit::NSEvent,
        ) -> Option<Retained<NSMenu>> {
            ffi_guard::contain(None, || {
                let point = self.convertPoint_fromView(unsafe { event.locationInWindow() }, None);
                let row = unsafe { self.rowAtPoint(point) };
                let data = NAV_OUTLINE_MENUS.with(|t| t.get(self as *const _ as usize));
                // `define_class!` rewrites the return, so no early `return` — one expression.
                match data {
                    None => None,
                    Some(d) => {
                        let items = d
                            .item_of_row(row)
                            .and_then(|i| d.ivars().menus.borrow().get(i).cloned())
                            .unwrap_or_default();
                        if items.is_empty() {
                            None
                        } else {
                            Some(build_ns_menu(d.mtm(), "", &items))
                        }
                    }
                }
            })
        }
    }
);

define_class!(
    #[unsafe(super(NSObject))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayNavMenuData"]
    #[ivars = NavMenuIvars]
    struct DayNavMenuData;

    unsafe impl NSObjectProtocol for DayNavMenuData {}

    unsafe impl NSOutlineViewDataSource for DayNavMenuData {
        #[unsafe(method(outlineView:numberOfChildrenOfItem:))]
        fn number_of_children(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            item: Option<&objc2::runtime::AnyObject>,
        ) -> isize {
            if item.is_none() {
                self.ivars().row_objects.borrow().len() as isize
            } else {
                0
            }
        }

        #[unsafe(method_id(outlineView:child:ofItem:))]
        fn child_of_item(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            index: isize,
            _item: Option<&objc2::runtime::AnyObject>,
        ) -> Retained<objc2::runtime::AnyObject> {
            let ids = self.ivars().row_ids.borrow();
            // AppKit only asks for children it was told exist, but a stale query racing a
            // reload must degrade (an unmatched identity) rather than index out of bounds —
            // a panic here unwinds into an ObjC frame and aborts.
            let id = ids
                .get(index as usize)
                .cloned()
                .unwrap_or_else(|| NSNumber::new_isize(-1));
            unsafe { objc2::rc::Retained::cast_unchecked(id) }
        }

        #[unsafe(method(outlineView:isItemExpandable:))]
        fn is_expandable(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            _item: &objc2::runtime::AnyObject,
        ) -> bool {
            false
        }

        // --- drag-to-reorder (docs/navigation.md "Reordering sidebar destinations"): the
        // outline's own drag pipeline, with the Gap placeholder Finder's sidebar shows. A row
        // moves within the run of movable rows around it, or, regrouping, into any section of
        // movable rows (`regroup_gap`); the app's data change brings the new order back as
        // `NavMenuPatch::Items`.

        #[unsafe(method_id(outlineView:pasteboardWriterForItem:))]
        fn pasteboard_writer_for_item(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            item: &objc2::runtime::AnyObject,
        ) -> Option<Retained<ProtocolObject<dyn objc2_app_kit::NSPasteboardWriting>>> {
            let make = || {
                let row = Self::outline_row(item);
                let index = self.item_of_row(row)?;
                if !self.is_movable(index) {
                    return None;
                }
                let pbitem = objc2_app_kit::NSPasteboardItem::new();
                unsafe {
                    pbitem.setString_forType(
                        &NSString::from_str(&row.to_string()),
                        &NSString::from_str(DAY_NAV_PASTEBOARD_TYPE),
                    );
                }
                Some(ProtocolObject::from_retained(pbitem))
            };
            ffi_guard::contain(None, make)
        }

        #[unsafe(method(outlineView:validateDrop:proposedItem:proposedChildIndex:))]
        fn validate_drop(
            &self,
            ov: &objc2_app_kit::NSOutlineView,
            info: &ProtocolObject<dyn objc2_app_kit::NSDraggingInfo>,
            item: Option<&objc2::runtime::AnyObject>,
            child_index: isize,
        ) -> objc2_app_kit::NSDragOperation {
            ffi_guard::contain(objc2_app_kit::NSDragOperation::None, || {
                let Some(drop) = self.nav_drop(ov, info, item, child_index) else {
                    return objc2_app_kit::NSDragOperation::None;
                };
                // A drop past the run's end lands at that end: move the gap there.
                if drop.retarget {
                    unsafe { ov.setDropItem_dropChildIndex(None, drop.gap as isize) };
                }
                objc2_app_kit::NSDragOperation::Move
            })
        }

        #[unsafe(method(outlineView:acceptDrop:item:childIndex:))]
        fn accept_drop(
            &self,
            ov: &objc2_app_kit::NSOutlineView,
            info: &ProtocolObject<dyn objc2_app_kit::NSDraggingInfo>,
            item: Option<&objc2::runtime::AnyObject>,
            child_index: isize,
        ) -> bool {
            ffi_guard::contain(false, || {
                let Some(drop) = self.nav_drop(ov, info, item, child_index) else {
                    return false;
                };
                // Deferred through the event queue: the app's callback never runs inside
                // AppKit's drop, and its data change reloads the rows in the new order.
                match drop.moves {
                    Some(NavMove::Reorder { from, to }) => {
                        emit(self.ivars().node, Event::ListReorder { from, to });
                    }
                    Some(NavMove::Regroup {
                        from,
                        section,
                        before,
                    }) => emit(
                        self.ivars().node,
                        Event::NavRegroup {
                            from,
                            section,
                            before,
                        },
                    ),
                    None => {}
                }
                true
            })
        }
    }

    unsafe impl NSControlTextEditingDelegate for DayNavMenuData {}

    unsafe impl NSOutlineViewDelegate for DayNavMenuData {
        /// Section headers are AppKit group rows: the source-list treatment (small, bold,
        /// secondary) comes free, and they are excluded from selection below.
        #[unsafe(method(outlineView:isGroupItem:))]
        fn is_group_item(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            item: &objc2::runtime::AnyObject,
        ) -> bool {
            let row = Self::outline_row(item);
            row >= 0 && self.item_of_row(row).is_none()
        }

        #[unsafe(method(outlineView:shouldSelectItem:))]
        fn should_select(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            item: &objc2::runtime::AnyObject,
        ) -> bool {
            self.item_of_row(Self::outline_row(item)).is_some()
        }

        #[unsafe(method_id(outlineView:viewForTableColumn:item:))]
        fn view_for(
            &self,
            ov: &objc2_app_kit::NSOutlineView,
            _col: Option<&objc2_app_kit::NSTableColumn>,
            item: &objc2::runtime::AnyObject,
        ) -> Option<Retained<NSView>> {
            let mtm = self.mtm();
            let row = Self::outline_row(item);
            let text = self
                .ivars()
                .row_objects
                .borrow()
                .get(usize::try_from(row).unwrap_or(usize::MAX))
                .cloned();
            // No early returns: the method_id macro owns the return conversion.
            text.map(|text| {
                let text: &NSString = &text;
                let Some(index) = self.item_of_row(row) else {
                    // A section header: a plain label. AppKit gives group rows their own
                    // typography and places the text, so this only supplies it.
                    let cell = DayNavCell::new(mtm);
                    let label = unsafe { NSTextField::labelWithString(text, mtm) };
                    unsafe {
                        label.cell().inspect(|c| {
                            c.setLineBreakMode(objc2_app_kit::NSLineBreakMode::ByTruncatingTail)
                        });
                        cell.addSubview(&label);
                        cell.setTextField(Some(&label));
                    }
                    return objc2::rc::Retained::into_super(objc2::rc::Retained::into_super(cell));
                };
                let icon = self
                    .ivars()
                    .icons
                    .borrow()
                    .get(index)
                    .and_then(|o| o.clone());
                let badge = self
                    .ivars()
                    .badges
                    .borrow()
                    .get(index)
                    .and_then(|o| o.clone());
                let badge_icon = self
                    .ivars()
                    .badge_icons
                    .borrow()
                    .get(index)
                    .and_then(|o| o.clone());
                let badge_tint = self
                    .ivars()
                    .badge_tints
                    .borrow()
                    .get(index)
                    .copied()
                    .flatten();
                // The cell places the icon and the label itself, at the row size style's size
                // (the system's Sidebar icon size); `DayNavCell` keeps the label clear of the
                // trailing accessories.
                let cell = DayNavCell::new(mtm);
                let label = unsafe { NSTextField::labelWithString(text, mtm) };
                unsafe {
                    // Feed titles are arbitrarily long, so the label truncates with an
                    // ellipsis within the frame the cell gives it.
                    label.cell().inspect(|c| {
                        c.setLineBreakMode(objc2_app_kit::NSLineBreakMode::ByTruncatingTail)
                    });
                    cell.addSubview(&label);
                    cell.setTextField(Some(&label));
                    // The badge sits at the trailing edge and keeps its intrinsic width; the
                    // label truncates into whatever is left, so a long feed name never pushes
                    // its own unread count off the pane.
                    // Both accessories share the trailing slot: the count (if any) and then
                    // the status glyph (if any), in a stack so a row can carry either or both
                    // without the constraints below caring which it got.
                    let accessory = objc2_app_kit::NSStackView::new(mtm);
                    accessory.setTranslatesAutoresizingMaskIntoConstraints(false);
                    accessory.setOrientation(
                        objc2_app_kit::NSUserInterfaceLayoutOrientation::Horizontal,
                    );
                    accessory.setSpacing(4.0);
                    let mut has_accessory = false;
                    let trailing: Retained<NSView> = match &badge {
                        Some(text) => {
                            let b = NSTextField::labelWithString(text, mtm);
                            b.setTranslatesAutoresizingMaskIntoConstraints(false);
                            b.setTextColor(Some(&objc2_app_kit::NSColor::secondaryLabelColor()));
                            b.setAlignment(objc2_app_kit::NSTextAlignment::Right);
                            b.setFont(Some(
                                &objc2_app_kit::NSFont::monospacedDigitSystemFontOfSize_weight(
                                    objc2_app_kit::NSFont::smallSystemFontSize(),
                                    objc2_app_kit::NSFontWeightRegular,
                                ),
                            ));
                            b.setContentCompressionResistancePriority_forOrientation(
                                objc2_app_kit::NSLayoutPriorityRequired,
                                objc2_app_kit::NSLayoutConstraintOrientation::Horizontal,
                            );
                            *cell.ivars().count.borrow_mut() = Some(b.clone());
                            accessory.addArrangedSubview(&objc2::rc::Retained::into_super(
                                objc2::rc::Retained::into_super(b),
                            ));
                            has_accessory = true;
                            let v: Retained<NSView> =
                                objc2::rc::Retained::into_super(accessory.clone());
                            v
                        }
                        None => objc2::rc::Retained::into_super(accessory.clone()),
                    };
                    // The status glyph, tinted where the app gave it a meaning-bearing color
                    // (a star is yellow because that is what a star IS, not because the theme
                    // says so). Template images take contentTintColor exactly as the row's
                    // leading icon does.
                    if let Some(img) = &badge_icon {
                        let iv = objc2_app_kit::NSImageView::new(mtm);
                        iv.setImage(Some(img));
                        iv.setTranslatesAutoresizingMaskIntoConstraints(false);
                        if let Some(c) = badge_tint {
                            iv.setContentTintColor(Some(&nscolor(c)));
                        }
                        iv.setContentCompressionResistancePriority_forOrientation(
                            objc2_app_kit::NSLayoutPriorityRequired,
                            objc2_app_kit::NSLayoutConstraintOrientation::Horizontal,
                        );
                        accessory.addArrangedSubview(&objc2::rc::Retained::into_super(iv));
                        has_accessory = true;
                    }
                    cell.addSubview(&trailing);
                    if has_accessory {
                        *cell.ivars().accessory.borrow_mut() = Some(trailing.clone());
                    }
                    objc2_app_kit::NSLayoutConstraint::activateConstraints(
                        &objc2_foundation::NSArray::from_retained_slice(&[
                            trailing
                                .trailingAnchor()
                                .constraintEqualToAnchor_constant(&cell.trailingAnchor(), -6.0),
                            trailing
                                .centerYAnchor()
                                .constraintEqualToAnchor(&cell.centerYAnchor()),
                        ]),
                    );
                }
                if let Some(img) = icon {
                    let fill = self.ivars().icon_fills.borrow().get(index).copied();
                    cell.ivars().icon_fill.set(fill.unwrap_or(1.0));
                    let tint = self.ivars().tints.borrow().get(index).copied().flatten();
                    let iv = unsafe { objc2_app_kit::NSImageView::new(mtm) };
                    unsafe {
                        iv.setImage(Some(&img));
                        // Per-row tint (docs/vectors.md): the icons are template images, so
                        // contentTintColor recolors the alpha mask; None keeps the neutral look.
                        if let Some(t) = tint {
                            iv.setContentTintColor(Some(&nscolor(t)));
                        }
                        iv.setImageScaling(
                            objc2_app_kit::NSImageScaling::ScaleProportionallyUpOrDown,
                        );
                        cell.addSubview(&iv);
                        cell.setImageView(Some(&iv));
                        let progress = self
                            .ivars()
                            .icon_progress
                            .borrow()
                            .iter()
                            .find(|(row, _)| *row == index)
                            .map(|(_, f)| *f);
                        nav_progress::update(&iv, progress);
                    }
                }
                objc2::rc::Retained::into_super(objc2::rc::Retained::into_super(cell))
            })
        }

        #[unsafe(method_id(outlineView:rowViewForItem:))]
        fn row_view_for(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            _item: &objc2::runtime::AnyObject,
        ) -> Retained<objc2_app_kit::NSTableRowView> {
            let row: Retained<DayNavRowView> =
                unsafe { msg_send![DayNavRowView::alloc(self.mtm()), init] };
            objc2::rc::Retained::into_super(row)
        }

        #[unsafe(method(outlineViewSelectionDidChange:))]
        fn selection_did_change(&self, notification: &NSNotification) {
            ffi_guard::contain((), || {
                if self.ivars().suppress.get() {
                    return;
                }
                let Some(obj) = (unsafe { notification.object() }) else {
                    return;
                };
                let Ok(ov) = obj.downcast::<objc2_app_kit::NSOutlineView>() else {
                    return;
                };
                let row = unsafe { ov.selectedRow() };
                if let Some(item) = self.item_of_row(row) {
                    emit(self.ivars().node, Event::SelectionChanged(item as i64));
                }
            })
        }
    }
);

thread_local! {
    /// `nav_icon_fill` per icon name: a sidebar rebuilds its rows on every count change, and an
    /// icon's drawing does not change with them.
    static NAV_ICON_FILLS: RefCell<HashMap<String, f64>> = RefCell::new(HashMap::new());
}

/// `nav_icon_fill` for each resolved icon, by name; 1 where a row has none.
fn nav_icon_fills(
    names: &[Option<String>],
    images: &[Option<Retained<objc2_app_kit::NSImage>>],
) -> Vec<f64> {
    names
        .iter()
        .zip(images)
        .map(|(name, image)| match (name, image) {
            (Some(name), Some(image)) => NAV_ICON_FILLS.with(|m| {
                *m.borrow_mut()
                    .entry(name.clone())
                    .or_insert_with(|| nav_icon_fill(image))
            }),
            _ => 1.0,
        })
        .collect()
}

/// How much of an icon's box its drawing spans along its longer side, in (0, 1]: a Material
/// Symbols glyph keeps the 80-unit margin of its 960-unit grid (about 0.83), an SF Symbol export
/// is boxed to its content (1), and artwork usually fills its square. Measured from the alpha of
/// one small render, since a plain SVG says nothing about where its drawing sits.
fn nav_icon_fill(image: &objc2_app_kit::NSImage) -> f64 {
    const PX: f64 = 64.0;
    let Some(rep) = scaled_rep(image, Size::new(PX, PX), 1.0) else {
        return 1.0;
    };
    let (w, h) = (
        rep.pixelsWide().max(0) as usize,
        rep.pixelsHigh().max(0) as usize,
    );
    let stride = rep.bytesPerRow().max(0) as usize;
    let data = unsafe { rep.bitmapData() };
    if data.is_null() || stride < w * 4 {
        return 1.0;
    }
    // SAFETY: `scaled_rep` made a meshed 8-bit RGBA bitmap of `h` rows of `stride` bytes, which
    // `rep` owns and keeps alive for this borrow.
    let bytes = unsafe { std::slice::from_raw_parts(data, stride * h) };
    let (mut x0, mut y0, mut x1, mut y1) = (w, h, 0, 0);
    for y in 0..h {
        for x in 0..w {
            if bytes[y * stride + x * 4 + 3] > 24 {
                (x0, x1, y0, y1) = (x0.min(x), x1.max(x + 1), y0.min(y), y1.max(y + 1));
            }
        }
    }
    if x1 <= x0 || y1 <= y0 {
        return 1.0;
    }
    // The render stretched the image to a square; back in the image's own proportions, the
    // drawing's longer extent over the image's longer side is what proportional scaling keeps.
    let size = image.size();
    let (iw, ih) = (size.width.max(1.0), size.height.max(1.0));
    let (fx, fy) = ((x1 - x0) as f64 / w as f64, (y1 - y0) as f64 / h as f64);
    ((fx * iw).max(fy * ih) / iw.max(ih)).clamp(0.25, 1.0)
}

fn resolve_nav_icons(icons: &[Option<String>]) -> Vec<Option<Retained<objc2_app_kit::NSImage>>> {
    // A bundled icon name → a template NSImage (tinted by the source list); `None` per iconless row.
    icons
        .iter()
        .map(|ic| {
            let name = ic.as_deref()?;
            // Prefer the glyph SVG (docs/vectors.md): NSImage renders it at display size.
            let path = day_spec::resource::resolve_vector_svg(name)
                .or_else(|| day_spec::resource::resolve_image_file(name))?;
            use objc2::AllocAnyThread as _;
            let img = unsafe {
                objc2_app_kit::NSImage::initWithContentsOfFile(
                    objc2_app_kit::NSImage::alloc(),
                    &NSString::from_str(&path.to_string_lossy()),
                )
            }?;
            // Downloaded/user-file icons are artwork; bundled glyphs remain templates.
            unsafe { img.setTemplate(!std::path::Path::new(name).is_absolute()) };
            Some(img)
        })
        .collect()
}

impl DayNavMenuData {
    #[allow(clippy::too_many_arguments)]
    fn new(
        mtm: MainThreadMarker,
        node: NodeId,
        items: &[String],
        icons: &[Option<String>],
        badges: &[Option<String>],
        badge_icons: &[Option<String>],
        badge_tints: &[Option<day_spec::Color>],
        sections: &[Option<String>],
        tints: &[Option<day_spec::Color>],
        menus: &[Vec<day_spec::MenuItem>],
    ) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(NavMenuIvars {
            node,
            items: RefCell::new(items.iter().map(|s| NSString::from_str(s)).collect()),
            icon_fills: RefCell::new(nav_icon_fills(icons, &resolve_nav_icons(icons))),
            icons: RefCell::new(resolve_nav_icons(icons)),
            tints: RefCell::new(tints.to_vec()),
            menus: RefCell::new(menus.to_vec()),
            movable: RefCell::new(Vec::new()),
            regroup: std::cell::Cell::new(false),
            sorted: RefCell::new(Vec::new()),
            badges: RefCell::new(ns_badges(badges)),
            icon_progress: RefCell::new(Vec::new()),
            badge_icons: RefCell::new(resolve_nav_icons(badge_icons)),
            badge_tints: RefCell::new(badge_tints.to_vec()),
            rows: RefCell::new(Vec::new()),
            row_objects: RefCell::new(Vec::new()),
            row_ids: RefCell::new(Vec::new()),
            suppress: std::cell::Cell::new(false),
        });
        let this: Retained<Self> = unsafe { msg_send![super(this), init] };
        this.rebuild_rows(items, sections);
        this
    }

    /// Data-driven rows changed (`NavMenuPatch::Items`): swap the stored decorations in place.
    // The parameters are the patch's payload: index-aligned per-row decoration arrays, each
    // landing in its own ivar. Bundling them would just move the same eight fields.
    #[allow(clippy::too_many_arguments)]
    fn set_items(
        &self,
        items: &[String],
        icons: &[Option<String>],
        badges: &[Option<String>],
        badge_icons: &[Option<String>],
        badge_tints: &[Option<day_spec::Color>],
        sections: &[Option<String>],
        tints: &[Option<day_spec::Color>],
        menus: &[Vec<day_spec::MenuItem>],
    ) {
        *self.ivars().items.borrow_mut() = items.iter().map(|s| NSString::from_str(s)).collect();
        let resolved = resolve_nav_icons(icons);
        *self.ivars().icon_fills.borrow_mut() = nav_icon_fills(icons, &resolved);
        *self.ivars().icons.borrow_mut() = resolved;
        *self.ivars().tints.borrow_mut() = tints.to_vec();
        *self.ivars().menus.borrow_mut() = menus.to_vec();
        *self.ivars().badges.borrow_mut() = ns_badges(badges);
        self.ivars().icon_progress.borrow_mut().clear();
        *self.ivars().badge_icons.borrow_mut() = resolve_nav_icons(badge_icons);
        *self.ivars().badge_tints.borrow_mut() = badge_tints.to_vec();
        self.rebuild_rows(items, sections);
    }

    /// Flatten items + section headers into the outline's display rows. Each row gets its own
    /// retained NSString so the outline can tell two rows apart by identity even when their
    /// labels match (two feeds legitimately share a title).
    fn rebuild_rows(&self, items: &[String], sections: &[Option<String>]) {
        let mut rows = Vec::with_capacity(items.len());
        let mut objects = Vec::with_capacity(items.len());
        for (i, label) in items.iter().enumerate() {
            if let Some(Some(header)) = sections.get(i) {
                rows.push(None);
                objects.push(NSString::from_str(header));
            }
            rows.push(Some(i));
            objects.push(NSString::from_str(label));
        }
        let ids = (0..objects.len())
            .map(|i| NSNumber::new_isize(i as isize))
            .collect();
        *self.ivars().rows.borrow_mut() = rows;
        *self.ivars().row_objects.borrow_mut() = objects;
        *self.ivars().row_ids.borrow_mut() = ids;
    }

    /// The outline row an item object names — the index its NSNumber identity carries — or
    /// `-1` for anything that is not one of ours (a stale query racing a reload).
    fn outline_row(item: &objc2::runtime::AnyObject) -> isize {
        item.downcast_ref::<NSNumber>()
            .map(|n| n.integerValue())
            .unwrap_or(-1)
    }

    /// Outline row → day item index.
    fn item_of_row(&self, row: isize) -> Option<usize> {
        if row < 0 {
            return None;
        }
        self.ivars()
            .rows
            .borrow()
            .get(row as usize)
            .copied()
            .flatten()
    }

    /// Day item index → outline row.
    fn row_of_item(&self, item: usize) -> Option<usize> {
        self.ivars()
            .rows
            .borrow()
            .iter()
            .position(|r| *r == Some(item))
    }

    fn is_movable(&self, item: usize) -> bool {
        self.ivars()
            .movable
            .borrow()
            .get(item)
            .copied()
            .unwrap_or(false)
    }

    /// What a drop proposal means for a reorder, or `None` when it is no drop of ours: a drag
    /// from another view, of a row that cannot move, or (regrouping) to a gap no rule allows.
    /// Reordering, the gap clamps to the run of movable rows around the dragged one, which
    /// section headers and fixed rows end ([`reorder_gap`]); regrouping, see [`regroup_gap`].
    fn nav_drop(
        &self,
        ov: &objc2_app_kit::NSOutlineView,
        info: &ProtocolObject<dyn objc2_app_kit::NSDraggingInfo>,
        item: Option<&objc2::runtime::AnyObject>,
        child_index: isize,
    ) -> Option<NavDrop> {
        let src = unsafe { info.draggingSource() }?;
        if Retained::as_ptr(&src).cast::<std::ffi::c_void>()
            != std::ptr::from_ref(ov).cast::<std::ffi::c_void>()
        {
            return None;
        }
        let pb = unsafe { info.draggingPasteboard() };
        let from_row = unsafe { pb.stringForType(&NSString::from_str(DAY_NAV_PASTEBOARD_TYPE)) }?
            .to_string()
            .parse::<usize>()
            .ok()?;
        let rows = self.ivars().rows.borrow();
        // The flat outline proposes a gap among the root's children, or a row itself (a drop
        // ONTO it, index -1).
        let proposed = match item {
            Some(item) => Self::outline_row(item),
            None => child_index,
        };
        let proposed = usize::try_from(proposed).unwrap_or(rows.len());
        if self.ivars().regroup.get() {
            regroup_gap(
                &rows,
                &self.ivars().movable.borrow(),
                &self.ivars().sorted.borrow(),
                from_row,
                proposed,
                item.is_some(),
            )
        } else {
            reorder_gap(
                &rows,
                &self.ivars().movable.borrow(),
                from_row,
                proposed,
                item.is_some(),
            )
        }
    }
}

/// A drop in a sidebar outline (`DayNavMenuData::nav_drop`).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
struct NavDrop {
    /// The gap the row drops into, among the outline's rows.
    gap: usize,
    /// The proposal named some other place, and the gap moves here.
    retarget: bool,
    /// What the drop reports, or `None` for a drop back in place.
    moves: Option<NavMove>,
}

/// What a sidebar drop reports, in item indices (the rows before the move).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum NavMove {
    /// `Event::ListReorder`: `from` takes `to`'s place.
    Reorder { from: usize, to: usize },
    /// `Event::NavRegroup`: `from` joins the section whose first row is `section`, before
    /// `before` or at the section's end.
    Regroup {
        from: usize,
        section: usize,
        before: Option<usize>,
    },
}

/// A reorder drop at `proposed`, a gap among the outline's `rows` (`None` a header, `Some(i)`
/// item `i`), for the row at `from_row`; `onto` when the proposal named a row itself, which
/// reads as the gap above it. The gap clamps to the run of movable rows around the dragged
/// one, which section headers and fixed rows end. `None` when that row cannot move.
fn reorder_gap(
    rows: &[Option<usize>],
    movable: &[bool],
    from_row: usize,
    proposed: usize,
    onto: bool,
) -> Option<NavDrop> {
    let is_movable = |i: usize| movable.get(i).copied().unwrap_or(false);
    let from = (*rows.get(from_row)?).filter(|i| is_movable(*i))?;
    let in_run = |r: usize| rows[r].is_some_and(is_movable);
    let first = (0..from_row)
        .rev()
        .take_while(|r| in_run(*r))
        .last()
        .unwrap_or(from_row);
    let last = (from_row + 1..rows.len())
        .take_while(|r| in_run(*r))
        .last()
        .unwrap_or(from_row);
    let gap = proposed.clamp(first, last + 1);
    // The row's place once it has left its own: the row whose position it takes.
    let target_row = if gap > from_row { gap - 1 } else { gap };
    let moves = (target_row != from_row)
        .then(|| rows[target_row].map(|to| NavMove::Reorder { from, to }))
        .flatten();
    Some(NavDrop {
        gap,
        retarget: gap != proposed || onto,
        moves,
    })
}

/// A regroup drop at `proposed`, a gap among the outline's `rows` (as [`reorder_gap`]'s), for
/// the row at `from_row` (docs/navigation.md "Moving rows between sections"). The gap's section
/// is the nearest header above it, or the rows above the first header; `before` is the item
/// right below the gap when that row is in the same section. A drop ONTO a header reads as
/// that section's first gap, onto an item as the gap above it. `None` when the row cannot
/// move, the gap is above the first header with no rows there, the section holds a fixed row,
/// or the gap is in the row's own section and the row is sorted. Gaps are never clamped.
fn regroup_gap(
    rows: &[Option<usize>],
    movable: &[bool],
    sorted: &[bool],
    from_row: usize,
    proposed: usize,
    onto: bool,
) -> Option<NavDrop> {
    let flag = |v: &[bool], i: usize| v.get(i).copied().unwrap_or(false);
    let from = (*rows.get(from_row)?).filter(|i| flag(movable, *i))?;
    let gap = match rows.get(proposed) {
        Some(None) if onto => proposed + 1,
        _ => proposed.min(rows.len()),
    };
    // The first outline row of the section a gap (or a row, as the gap above it) sits in.
    let section_start = |gap: usize| match (0..gap).rev().find(|r| rows[*r].is_none()) {
        Some(header) => Some(header + 1),
        None => rows.first().copied().flatten().map(|_| 0),
    };
    let first = section_start(gap)?;
    let end = (first..rows.len())
        .find(|r| rows[*r].is_none())
        .unwrap_or(rows.len());
    let section = rows.get(first).copied().flatten()?;
    if !rows[first..end]
        .iter()
        .all(|r| r.is_some_and(|i| flag(movable, i)))
    {
        return None;
    }
    let own = section_start(from_row) == Some(first);
    if own && flag(sorted, from) {
        return None;
    }
    let moves = (!own || (gap != from_row && gap != from_row + 1)).then(|| NavMove::Regroup {
        from,
        section,
        before: rows.get(gap).copied().flatten(),
    });
    Some(NavDrop {
        gap,
        retarget: gap != proposed || onto,
        moves,
    })
}

#[cfg(test)]
mod nav_gap_tests {
    use super::{NavDrop, NavMove, regroup_gap, reorder_gap};

    /// 0 today, 1 [news], 2 a, 3 b, 4 e, 5 [tech], 6 c, 7 d, 8 [smart], 9 starred: items 0..=6.
    const ROWS: [Option<usize>; 10] = [
        Some(0),
        None,
        Some(1),
        Some(2),
        Some(3),
        None,
        Some(4),
        Some(5),
        None,
        Some(6),
    ];
    /// The feeds move; today and starred are fixed.
    const MOVABLE: [bool; 7] = [false, true, true, true, true, true, false];
    const SORTED: [bool; 7] = [false, true, true, true, true, true, false];
    const UNSORTED: [bool; 7] = [false; 7];

    fn regroup(from: usize, section: usize, before: Option<usize>) -> Option<NavMove> {
        Some(NavMove::Regroup {
            from,
            section,
            before,
        })
    }

    #[test]
    fn regroup_gaps_name_the_section_above_and_the_row_below() {
        let at = |from_row, gap| regroup_gap(&ROWS, &MOVABLE, &SORTED, from_row, gap, false);
        // a, into tech's first gap: before c.
        assert_eq!(
            at(2, 6),
            Some(NavDrop {
                gap: 6,
                retarget: false,
                moves: regroup(1, 4, Some(4)),
            })
        );
        // c, into the gap above tech's header: the end of news.
        assert_eq!(at(6, 5).and_then(|d| d.moves), regroup(4, 1, None));
        // a, between c and d, and at tech's end above smart's header.
        assert_eq!(at(2, 7).and_then(|d| d.moves), regroup(1, 4, Some(5)));
        assert_eq!(at(2, 8).and_then(|d| d.moves), regroup(1, 4, None));
    }

    #[test]
    fn regroup_gaps_skip_fixed_sections_fixed_rows_and_a_sorted_rows_own_section() {
        let at = |from_row, gap| regroup_gap(&ROWS, &MOVABLE, &SORTED, from_row, gap, false);
        // Smart holds starred, and the rows above the first header hold today.
        for gap in [0, 1, 9, 10] {
            assert_eq!(at(2, gap), None, "gap {gap}");
        }
        // A sorted row's own section offers no gap, its own place included.
        for gap in [2, 3, 4, 5] {
            assert_eq!(at(2, gap), None, "gap {gap}");
        }
        // Fixed rows and headers never drag.
        assert_eq!(at(0, 6), None);
        assert_eq!(at(1, 6), None);
        assert_eq!(at(9, 6), None);
    }

    #[test]
    fn regroup_gaps_reorder_an_unsorted_row_in_its_own_section() {
        let at = |from_row, gap| regroup_gap(&ROWS, &MOVABLE, &UNSORTED, from_row, gap, false);
        // a, between b and e.
        assert_eq!(at(2, 4).and_then(|d| d.moves), regroup(1, 1, Some(3)));
        // a, at news's end above tech's header.
        assert_eq!(at(2, 5).and_then(|d| d.moves), regroup(1, 1, None));
        // Back in place, either side of itself: a drop that reports nothing.
        for gap in [2, 3] {
            let drop = at(2, gap).expect("offered");
            assert_eq!(drop.moves, None, "gap {gap}");
        }
    }

    #[test]
    fn regroup_drops_onto_a_row_move_to_a_gap() {
        // Onto tech's header: its first gap. Onto d: the gap above d.
        assert_eq!(
            regroup_gap(&ROWS, &MOVABLE, &SORTED, 2, 5, true),
            Some(NavDrop {
                gap: 6,
                retarget: true,
                moves: regroup(1, 4, Some(4)),
            })
        );
        assert_eq!(
            regroup_gap(&ROWS, &MOVABLE, &SORTED, 2, 7, true),
            Some(NavDrop {
                gap: 7,
                retarget: true,
                moves: regroup(1, 4, Some(5)),
            })
        );
    }

    #[test]
    fn regroup_offers_nothing_above_a_leading_header() {
        // 0 [news], 1 a, 2 [tech], 3 b.
        let rows = [None, Some(0), None, Some(1)];
        let movable = [true, true];
        let at = |gap| regroup_gap(&rows, &movable, &[false, false], 1, gap, false);
        assert_eq!(at(0), None);
        assert_eq!(at(1).map(|d| d.moves), Some(None));
        assert_eq!(at(2).map(|d| d.moves), Some(None));
        assert_eq!(at(3).and_then(|d| d.moves), regroup(0, 1, Some(1)));
        assert_eq!(at(4).and_then(|d| d.moves), regroup(0, 1, None));
    }

    #[test]
    fn reorder_gaps_clamp_to_the_run() {
        // a past the run's end lands at its end: e's place.
        assert_eq!(
            reorder_gap(&ROWS, &MOVABLE, 2, 9, false),
            Some(NavDrop {
                gap: 5,
                retarget: true,
                moves: Some(NavMove::Reorder { from: 1, to: 3 }),
            })
        );
        // Back in place.
        assert_eq!(
            reorder_gap(&ROWS, &MOVABLE, 2, 3, false).map(|d| d.moves),
            Some(None)
        );
        // b above the run's start lands at a's place; a fixed row offers nothing.
        assert_eq!(
            reorder_gap(&ROWS, &MOVABLE, 3, 0, false).and_then(|d| d.moves),
            Some(NavMove::Reorder { from: 2, to: 1 })
        );
        assert_eq!(reorder_gap(&ROWS, &MOVABLE, 0, 3, false), None);
    }
}

/// The private pasteboard type carrying a dragged sidebar row (local reorder only).
const DAY_NAV_PASTEBOARD_TYPE: &str = "dev.daybrite.day.nav-row";

/// Badge strings, retained once per rebuild rather than per cell.
fn ns_badges(badges: &[Option<String>]) -> Vec<Option<Retained<NSString>>> {
    badges
        .iter()
        .map(|b| b.as_deref().map(NSString::from_str))
        .collect()
}

// ---------------------------------------------------------------------------
/// Force the table's visible rows to exist on the next main-loop turn — outside any `with_tree`
/// borrow, so `bind_row` may build them. `layoutSubtreeIfNeeded` is not enough: an occluded
/// window's table skips row tiling entirely, so `viewAtColumn:row:makeIfNecessary:` is the only
/// reliable way to realize rows without a draw pass (§10; see the Reload patch for why).
fn post_realize_visible_rows(key: usize) {
    <AppKit as Platform>::post(Box::new(move || {
        if let Some((table, data)) = list_entry(key) {
            unsafe { table.layoutSubtreeIfNeeded() };
            let range = unsafe { table.rowsInRect(table.visibleRect()) };
            if let Some(source) = data.ivars().source.borrow().clone()
                && let Some(report) = &source.first_visible
            {
                report(range.location.min((source.len)().saturating_sub(1)));
            }
            for row in range.location..range.location + range.length {
                let cell = unsafe { table.viewAtColumn_row_makeIfNecessary(0, row as isize, true) };
                // A snapshot/layout can have requested this cell while day-core held its
                // tree borrow. The delegate then returned an empty container; AppKit caches
                // it and will not ask viewForRow again. Complete that skipped bind here.
                if let Some(cell) = cell
                    && cell.subviews().is_empty()
                {
                    let source = data.ivars().source.borrow().clone();
                    if let Some(source) = source {
                        (source.bind_row)(row, Retained::as_ptr(&cell) as RawHandle);
                    }
                }
            }
        }
        // The builds above queued their styling effects; drain them now — outside the pump, no
        // event may arrive for a while (idle app), and a snapshot would capture bare rows.
        day_core::pump_events();
    }));
}

/// A native drop changes the snapshot synchronously and suppresses the app's echo Reload.
/// Once AppKit has unwound its drop/gap tracking, reconcile the table with that snapshot:
/// the incremental move alone can leave its row tiling and scroll extent out of sync.
/// Preserve the user's viewport and selection; never force a jump to the moved row.
fn post_settle_list_drop(key: usize) {
    <AppKit as Platform>::post(Box::new(move || {
        // Publish the deferred on_reorder before reading the final row set. App code may
        // remove rows or close the list, so resolve the native handles only after the drain.
        day_core::pump_events();
        let Some((table, data)) = list_entry(key) else {
            return;
        };
        let Some(scroll) = table.enclosingScrollView() else {
            return;
        };
        let clip = scroll.contentView();
        let origin = clip.bounds().origin;
        let selected = table.selectedRowIndexes();
        let suppressed = data.ivars().suppress.replace(true);
        table.reloadData();
        // Outside with_tree: tiling is allowed to bind/rebind Day's cell contents here.
        table.layoutSubtreeIfNeeded();
        let restored = objc2_foundation::NSMutableIndexSet::new();
        for row in 0..table.numberOfRows().max(0) as usize {
            if selected.containsIndex(row) {
                restored.addIndex(row);
            }
        }
        table.selectRowIndexes_byExtendingSelection(&restored, false);
        let mut bounds = clip.bounds();
        bounds.origin = origin;
        clip.scrollToPoint(clip.constrainBoundsRect(bounds).origin);
        scroll.reflectScrolledClipView(&clip);
        data.ivars().suppress.set(suppressed);
        post_realize_visible_rows(key);
    }));
}

// DayListData — NSTableView data-source + delegate for the recycling list (docs/list.md, §10)
//
// No custom NSTableRowView: the table runs the PLAIN style, whose standard row view lays cell
// views out at the full row bounds — no inset to pin away — and whose cell-frame slide is what
// animates a row-action swipe. (A `layout`-override pin lived here under FullWidth until
// 2026-08; it also froze row content mid-swipe, revealing actions behind a motionless row.)
// ---------------------------------------------------------------------------

define_class!(
    #[unsafe(super(NSTableView))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayListView"]
    struct DayListView;
    unsafe impl NSObjectProtocol for DayListView {}
    impl DayListView {
        /// NSTableView consumes right-clicks before the row's container sees them. Resolve
        /// its summon-time provider from the visible cell, never from the selected row.
        #[unsafe(method_id(menuForEvent:))]
        fn menu_for_event(
            &self,
            event: &objc2_app_kit::NSEvent,
        ) -> Option<Retained<NSMenu>> {
            ffi_guard::contain(None, || {
                let point = self.convertPoint_fromView(unsafe { event.locationInWindow() }, None);
                let row = unsafe { self.rowAtPoint(point) };
                let provider = if row >= 0 {
                    unsafe { self.viewAtColumn_row_makeIfNecessary(0, row, false) }
                        .and_then(|cell| list_row_menu_provider(&cell))
                } else {
                    None
                };
                match provider {
                    Some((view, provider)) => {
                        let point = view.convertPoint_fromView(
                            unsafe { event.locationInWindow() }, None,
                        );
                        let items = provider(day_spec::Point::new(point.x, point.y));
                        if items.is_empty() {
                            None
                        } else {
                            Some(build_ns_menu(self.mtm(), "", &items))
                        }
                    }
                    None => unsafe { msg_send![super(self), menuForEvent: event] },
                }
            })
        }

        #[unsafe(method(becomeFirstResponder))]
        fn become_first_responder(&self) -> bool {
            let accepted: bool = unsafe { msg_send![super(self), becomeFirstResponder] };
            if accepted {
                self.report_focus(true);
            }
            accepted
        }

        #[unsafe(method(resignFirstResponder))]
        fn resign_first_responder(&self) -> bool {
            let accepted: bool = unsafe { msg_send![super(self), resignFirstResponder] };
            if accepted {
                self.report_focus(false);
            }
            accepted
        }

        #[unsafe(method(keyDown:))]
        fn key_down(&self, event: &objc2_app_kit::NSEvent) {
            ffi_guard::contain((), || {
                let key = unsafe { event.keyCode() };
                if (key == 36 || key == 76) && unsafe { self.doubleAction() }.is_some() {
                    let row = unsafe { self.selectedRow() };
                    if row >= 0 && let Some(target) = unsafe { self.target() } {
                        let _: () = unsafe { msg_send![&*target, activateRow: self] };
                        return;
                    }
                }
                let _: () = unsafe { msg_send![super(self), keyDown: event] };
            });
        }
    }
);

/// The cell can wrap its decorated row in layout containers. Search only this visible
/// cell, not other rows; cloning the provider releases the registry borrow before app code.
fn list_row_menu_provider(view: &NSView) -> Option<(Retained<NSView>, day_spec::ContextMenuFn)> {
    if let Some(provider) = CTX_MENU_FNS.with(|t| t.get(view as *const NSView as usize)) {
        return Some((view.retain(), provider));
    }
    view.subviews()
        .iter()
        .find_map(|view| list_row_menu_provider(&view))
}

/// Plain labels receive the mouse event before their row does. Resolve the nearest dynamic
/// owner without copying providers onto descendants (which would go stale on recycling).
/// `Some(None)` means an owner deliberately returned no menu; do not fall through to a parent.
fn inherited_context_menu(
    view: &NSView,
    event: &objc2_app_kit::NSEvent,
) -> Option<Option<Retained<NSMenu>>> {
    let mut current = Some(view.retain());
    while let Some(view) = current {
        if let Some(provider) = CTX_MENU_FNS.with(|t| t.get(Retained::as_ptr(&view) as usize)) {
            let point = view.convertPoint_fromView(unsafe { event.locationInWindow() }, None);
            let items = provider(day_spec::Point::new(point.x, point.y));
            return Some((!items.is_empty()).then(|| build_ns_menu(view.mtm(), "", &items)));
        }
        current = unsafe { view.superview() };
    }
    None
}

impl DayListView {
    fn report_focus(&self, focused: bool) {
        ffi_guard::contain((), || {
            if let Some(target) = unsafe { self.target() }
                && let Some(data) = target.downcast_ref::<DayListData>()
            {
                emit(data.ivars().node, Event::FocusChanged(focused));
            }
        });
    }
}

struct ListIvars {
    node: NodeId,
    /// Injected by `attach_list` once day-core wires the driver.
    source: RefCell<Option<ListSource>>,
    selectable: std::cell::Cell<bool>,
    /// Multi-select mode (docs/list.md): every change reports the FULL selected set.
    multi: std::cell::Cell<bool>,
    /// Programmatic selection in flight: don't re-emit SelectionChanged.
    suppress: std::cell::Cell<bool>,
    /// The row-token order this table currently displays — the baseline `permutation_moves`
    /// diffs a Reload against (docs/list.md: a same-set reorder animates as row moves).
    tokens: RefCell<Vec<u64>>,
    /// `RowHeight::Automatic` (docs/list.md "Row heights"): each row is as tall as Day laid
    /// it, through `tableView:heightOfRow:`. A uniform list never answers that selector, so
    /// NSTableView keeps its fixed-pitch fast path.
    automatic: bool,
    /// The list has section headers (docs/list.md "Sections"): AppKit group rows, which float
    /// at the top as their section scrolls under them. A header sizes to its content in any
    /// list, so a sectioned list answers `tableView:heightOfRow:` even when it is uniform.
    sections: bool,
    /// The height a header nobody has bound yet is given, like `estimate` for rows.
    header_estimate: std::cell::Cell<f64>,
    /// Each self-sizing row's height by row token, as Day last laid it. By token, not row: a
    /// splice or a drag moves rows without rebinding them.
    heights: RefCell<std::collections::HashMap<u64, f64>>,
    /// The row token each bound cell shows, so `RowSizeInvalidated` (which names the cell)
    /// finds the height it corrects.
    cell_tokens: RefCell<std::collections::HashMap<usize, u64>>,
    /// The height a row nobody has bound yet is given: the last one Day measured, so a list
    /// of like rows scrolls without its rows jumping as they arrive.
    estimate: std::cell::Cell<f64>,
    /// A height pass is posted and not yet run (`post_row_heights` coalesces).
    heights_pending: std::cell::Cell<bool>,
}

define_class!(
    #[unsafe(super(NSObject))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayListData"]
    #[ivars = ListIvars]
    struct DayListData;

    unsafe impl NSObjectProtocol for DayListData {}
    unsafe impl NSControlTextEditingDelegate for DayListData {}

    impl DayListData {
        /// Only a self-sizing list answers `tableView:heightOfRow:`: NSTableView asks that
        /// of every row on each reload, and a uniform list's fixed `rowHeight` is the fast
        /// path. NSTableView reads this once, at `setDelegate:`, after `automatic` is set.
        #[unsafe(method(respondsToSelector:))]
        fn responds_to_selector(&self, selector: objc2::runtime::Sel) -> bool {
            if selector == objc2::sel!(tableView:heightOfRow:)
                && !self.ivars().automatic
                && !self.ivars().sections
            {
                false
            } else {
                unsafe { msg_send![super(self), respondsToSelector: selector] }
            }
        }

        #[unsafe(method(listViewportChanged:))]
        fn list_viewport_changed(&self, notification: &NSNotification) {
            ffi_guard::contain((), || {
                let source = self.ivars().source.borrow().clone();
                if let Some(source) = source && let Some(report) = &source.first_visible
                    && let Some(object) = notification.object()
                    && let Some(clip) = object.downcast_ref::<objc2_app_kit::NSClipView>()
                    && let Some(document) = clip.documentView()
                    && let Some(table) = document.downcast_ref::<NSTableView>() {
                    let visible = unsafe { table.rowsInRect(table.visibleRect()) };
                    report(visible.location.min((source.len)().saturating_sub(1)));
                }
            });
        }

        #[unsafe(method(activateRow:))]
        fn activate_row(&self, table: &NSTableView) {
            ffi_guard::contain((), || {
                let row = unsafe { table.selectedRow() };
                if row >= 0 { emit(self.ivars().node, Event::ListActivated(row as usize)); }
            });
        }
        #[unsafe(method(doubleClickRow:))]
        fn double_click_row(&self, table: &NSTableView) {
            ffi_guard::contain((), || {
                let row = unsafe { table.clickedRow() };
                if row >= 0 { emit(self.ivars().node, Event::ListActivated(row as usize)); }
            });
        }
    }

    unsafe impl NSTableViewDataSource for DayListData {
        #[unsafe(method(numberOfRowsInTableView:))]
        fn number_of_rows(&self, _tv: &NSTableView) -> isize {
            // Reads the piece's snapshot only (no tree access) — safe even when called
            // synchronously from reloadData inside a with_tree borrow. Guarded because
            // `len` is a day-core closure.
            ffi_guard::contain(0, || {
                self.ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .map(|s| (s.len)() as isize)
                    .unwrap_or(0)
            })
        }

        // --- drag-to-reorder (docs/list.md): NSTableView's native drag pipeline. The dragged
        // row rides the pasteboard as a private-typed string; `validateDrop` consults the app's
        // guard live (the `.gap` feedback style opens the placeholder gap only where the guard
        // allows), and `acceptDrop` commits through the sync seam, then animates the native move.

        #[unsafe(method_id(tableView:pasteboardWriterForRow:))]
        fn pasteboard_writer_for_row(
            &self,
            _tv: &NSTableView,
            row: isize,
        ) -> Option<Retained<ProtocolObject<dyn objc2_app_kit::NSPasteboardWriting>>> {
            // (Closure body: define_class converts only the TAIL expression, so early `return`s
            // must not escape the method itself.)
            let make = || {
                // Only reorderable lists write drag items — no seam, no drag.
                let reorderable = self
                    .ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .is_some_and(|s| s.reorder.is_some());
                // A group row (a section header) never lifts (docs/list.md "Sections").
                if !reorderable || row < 0 || self.is_header(row) {
                    return None;
                }
                let item = objc2_app_kit::NSPasteboardItem::new();
                unsafe {
                    item.setString_forType(
                        &NSString::from_str(&row.to_string()),
                        &NSString::from_str(DAY_ROW_PASTEBOARD_TYPE),
                    );
                }
                Some(ProtocolObject::from_retained(item))
            };
            ffi_guard::contain(None, make)
        }

        #[unsafe(method(tableView:validateDrop:proposedRow:proposedDropOperation:))]
        fn validate_drop(
            &self,
            tv: &NSTableView,
            info: &ProtocolObject<dyn objc2_app_kit::NSDraggingInfo>,
            row: isize,
            _op: objc2_app_kit::NSTableViewDropOperation,
        ) -> objc2_app_kit::NSDragOperation {
            // Guarded: `can_move` consults the app's reorder guard closure.
            ffi_guard::contain(objc2_app_kit::NSDragOperation::None, || {
                let Some((from, len)) = self.drag_context(tv, info) else {
                    return objc2_app_kit::NSDragOperation::None;
                };
                // Normalize to an above insertion point (the gap style's semantics), convert to
                // the post-removal target index, and ask the guard.
                let ins = row.clamp(0, len as isize) as usize;
                let to = insertion_to_target(from, ins, len);
                let accepted = self.can_move(from, to);
                if accepted < 0 {
                    return objc2_app_kit::NSDragOperation::None;
                }
                let accepted = (accepted as usize).min(len.saturating_sub(1));
                if accepted != to {
                    // The guard retargeted: move the gap to where the drop would actually land.
                    unsafe {
                        tv.setDropRow_dropOperation(
                            target_to_insertion(from, accepted) as isize,
                            objc2_app_kit::NSTableViewDropOperation::Above,
                        );
                    }
                }
                objc2_app_kit::NSDragOperation::Move
            })
        }

        #[unsafe(method(tableView:acceptDrop:row:dropOperation:))]
        fn accept_drop(
            &self,
            tv: &NSTableView,
            info: &ProtocolObject<dyn objc2_app_kit::NSDraggingInfo>,
            row: isize,
            _op: objc2_app_kit::NSTableViewDropOperation,
        ) -> bool {
            // (Closure body: early `return`s must not escape the define_class method itself.)
            let drop = || {
                let Some((from, len)) = self.drag_context(tv, info) else {
                    return false;
                };
                let ins = row.clamp(0, len as isize) as usize;
                let to = insertion_to_target(from, ins, len);
                let accepted = self.can_move(from, to);
                if accepted < 0 {
                    return false;
                }
                let accepted = (accepted as usize).min(len.saturating_sub(1));
                if accepted == from {
                    return true; // dropped back home — nothing to commit
                }
                // Commit through the sync seam (rotates Day's snapshot, defers the app
                // callback), THEN animate the native move — the data source already answers in
                // the new order.
                let mv = self
                    .ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .and_then(|s| s.reorder.as_ref().map(|r| r.move_row.clone()));
                let Some(mv) = mv else { return false };
                mv(from, accepted);
                // Keep the displayed-order cache in step (the commit's echo skips the Reload
                // that would otherwise refresh it — see `permutation_moves`).
                {
                    let mut toks = self.ivars().tokens.borrow_mut();
                    if from < toks.len() && accepted < toks.len() {
                        let t = toks.remove(from);
                        toks.insert(accepted, t);
                    }
                }
                unsafe { tv.moveRowAtIndex_toIndex(from as isize, accepted as isize) };
                if let Some(scroll) = tv.enclosingScrollView() {
                    post_settle_list_drop(ptr_of(&scroll));
                }
                true
            };
            // Guarded: the commit runs the seam's move closure into day-core and the app.
            ffi_guard::contain(false, drop)
        }
    }

    unsafe impl NSTableViewDelegate for DayListData {
        /// A self-sizing row's height (docs/list.md "Row heights"): the height Day laid it at
        /// once it has been bound, the running estimate until then. Asked before the row's view
        /// exists, often from inside `reloadData` under a day-core borrow, so it reads only this
        /// table's own record and the source's token snapshot.
        #[unsafe(method(tableView:heightOfRow:))]
        fn height_of_row(&self, tv: &NSTableView, row: isize) -> f64 {
            ffi_guard::contain(44.0, || {
                let ivars = self.ivars();
                let header = self.is_header(row);
                // A uniform sectioned list: rows keep the fixed pitch, headers size themselves.
                if !header && !ivars.automatic {
                    return unsafe { tv.rowHeight() };
                }
                let token = ivars
                    .source
                    .borrow()
                    .as_ref()
                    .filter(|s| row >= 0 && (row as usize) < (s.len)())
                    .map(|s| (s.token_at)(row as usize));
                token
                    .and_then(|t| ivars.heights.borrow().get(&t).copied())
                    .unwrap_or_else(|| {
                        if header {
                            ivars.header_estimate.get()
                        } else {
                            ivars.estimate.get()
                        }
                    })
            })
        }

        /// Section headers are AppKit group rows (docs/list.md "Sections"): drawn in the
        /// group style, spanning the row, and floated over their section by
        /// `floatsGroupRows`.
        #[unsafe(method(tableView:isGroupRow:))]
        fn is_group_row(&self, _tv: &NSTableView, row: isize) -> bool {
            ffi_guard::contain(false, || self.is_header(row))
        }

        /// A header is not an item: clicks and arrow keys pass over it.
        #[unsafe(method(tableView:shouldSelectRow:))]
        fn should_select_row(&self, _tv: &NSTableView, row: isize) -> bool {
            ffi_guard::contain(true, || !self.is_header(row))
        }

        #[unsafe(method_id(tableView:viewForTableColumn:row:))]
        fn view_for_row(
            &self,
            tv: &NSTableView,
            _col: Option<&NSTableColumn>,
            row: isize,
        ) -> Option<Retained<NSView>> {
            // Guarded: `bind_row` builds the app's row content.
            ffi_guard::contain(None, || {
                let mtm = self.mtm();
                // Headers pool apart from rows, so a recycled cell keeps its kind and rebinds.
                let header = self.is_header(row);
                let ident = NSString::from_str(if header { DAY_HEADER_CELL } else { DAY_ROW_CELL });
                // Recycle a cell view if one is free; else make a fresh flipped container.
                let cell: Retained<NSView> =
                    unsafe { tv.makeViewWithIdentifier_owner(&ident, None) }.unwrap_or_else(|| {
                        let v: Retained<NSView> = Retained::into_super(DayFlipped::new(mtm));
                        unsafe { v.setIdentifier(Some(&ident)) };
                        v
                    });
                // Day builds row content the first time it sees this cell, and rebinds
                // (slot-write) when the cell is recycled. NSTableView calls this outside
                // reloadData's stack, so the re-entry into with_tree is safe.
                let source = self.ivars().source.borrow().clone();
                if let Some(source) = source {
                    let raw = Retained::as_ptr(&cell) as RawHandle;
                    (source.bind_row)(row as usize, raw);
                    if self.ivars().automatic || header {
                        self.note_row_height(tv, &source, row, raw, header);
                    }
                }
                Some(cell)
            })
        }

        #[unsafe(method(tableView:didRemoveRowView:forRow:))]
        fn did_remove_row_view(
            &self,
            _tv: &NSTableView,
            row_view: &objc2_app_kit::NSTableRowView,
            _row: isize,
        ) {
            // The row went back to the reuse pool (a reload dropping it past a shrunk source, a
            // scroll): clear its day element ids so it stops answering lookups, as the tree's
            // `outlineView:didRemoveRowView:forRow:` does. Deferred, since this fires inside
            // reload stacks that hold the day-core borrow, and re-checked: a cell the same
            // turn's reload already reused has a window again, and its fresh ids must survive.
            ffi_guard::contain((), || {
                let Some(cell) = row_view.subviews().iter().find(|sub| {
                    sub.identifier()
                        .map(|i| {
                            let i = i.to_string();
                            i == DAY_ROW_CELL || i == DAY_HEADER_CELL
                        })
                        .unwrap_or(false)
                }) else {
                    return;
                };
                // Raw +1 pointers across the post (the closure must be Send, which Retained is
                // not; everything stays on the main thread). AppKit may free a removed row view.
                let cell = Retained::into_raw(cell) as usize;
                let Some(this) = (unsafe {
                    Retained::retain(self as *const DayListData as *mut DayListData)
                }) else {
                    return;
                };
                let this = Retained::into_raw(this) as usize;
                <AppKit as Platform>::post(Box::new(move || {
                    // Reclaim both +1s first, so every early return balances them.
                    let this = unsafe { Retained::from_raw(this as *mut DayListData) };
                    let cell = unsafe { Retained::from_raw(cell as *mut NSView) };
                    let (Some(this), Some(cell)) = (this, cell) else {
                        return;
                    };
                    if cell.window().is_some() {
                        return; // reused already: its ids are the live row's
                    }
                    let recycle = this
                        .ivars()
                        .source
                        .borrow()
                        .as_ref()
                        .map(|s| s.recycle.clone());
                    if let Some(recycle) = recycle {
                        recycle(Retained::as_ptr(&cell) as RawHandle);
                    }
                }));
            })
        }

        #[unsafe(method(tableViewSelectionDidChange:))]
        fn selection_did_change(&self, notification: &NSNotification) {
            ffi_guard::contain((), || {
                if self.ivars().suppress.get() || !self.ivars().selectable.get() {
                    return;
                }
                let Some(obj) = (unsafe { notification.object() }) else {
                    return;
                };
                let Ok(tv) = obj.downcast::<NSTableView>() else {
                    return;
                };
                if self.ivars().multi.get() {
                    // Multi-select: report the FULL set (ascending; empty = cleared).
                    let idx = unsafe { tv.selectedRowIndexes() };
                    let mut rows = Vec::with_capacity(idx.count());
                    let mut i = idx.firstIndex();
                    while i != objc2_foundation::NSNotFound as usize {
                        rows.push(i as i64);
                        i = unsafe { idx.indexGreaterThanIndex(i) };
                    }
                    emit(self.ivars().node, Event::SelectionSet(rows));
                } else {
                    let row = unsafe { tv.selectedRow() };
                    if row >= 0 {
                        emit(self.ivars().node, Event::SelectionChanged(row as i64));
                    } else {
                        // CLEARED. `selectedRow()` answers -1, which is not a row, so there is
                        // nothing for `SelectionChanged` to carry and nothing for `on_select` to
                        // be called with — but the app still has to hear about it, or a detail
                        // pane goes on showing the row the user just deselected. The empty set is
                        // how that is said (`on_selection`, docs/list.md); reporting nothing was
                        // a silent contract break, since single-selection backends are documented
                        // as firing it with a one-element OR EMPTY set.
                        emit(self.ivars().node, Event::SelectionSet(Vec::new()));
                    }
                }
            })
        }

        // --- swipe actions (docs/list.md): NSTableView's row-action pipeline. AppKit calls
        // this as the two-finger swipe starts, so the offer reflects the row's state at
        // GESTURE time; a full swipe across activates the first action (AppKit's own
        // full-slide behavior). The handler commits through the seam, which defers the app's
        // callback to the event drain.
        #[unsafe(method_id(tableView:rowActionsForRow:edge:))]
        fn row_actions_for_row(
            &self,
            tv: &NSTableView,
            row: isize,
            edge: objc2_app_kit::NSTableRowActionEdge,
        ) -> Retained<NSArray<objc2_app_kit::NSTableViewRowAction>> {
            // Guarded: `actions_at` runs the app's provider closure.
            ffi_guard::contain(NSArray::new(), || {
                let sw = self
                    .ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .and_then(|s| s.swipe.clone());
                let Some(sw) = sw else {
                    return NSArray::new();
                };
                if row < 0 {
                    return NSArray::new();
                }
                // AppKit's Leading/Trailing already speak reading direction, same as ours.
                let day_edge = if edge == objc2_app_kit::NSTableRowActionEdge::Leading {
                    day_spec::SwipeEdge::Leading
                } else {
                    day_spec::SwipeEdge::Trailing
                };
                let offer = (sw.actions_at)(row as usize, day_edge);
                let actions: Vec<Retained<objc2_app_kit::NSTableViewRowAction>> = offer
                    .iter()
                    .enumerate()
                    .map(|(i, a)| {
                        let style = if a.destructive {
                            objc2_app_kit::NSTableViewRowActionStyle::Destructive
                        } else {
                            objc2_app_kit::NSTableViewRowActionStyle::Regular
                        };
                        let perform = sw.perform.clone();
                        // Retained only for the swipe session: AppKit releases the actions
                        // (and this block) when the revealed buttons close.
                        let table = tv.retain();
                        let handler = block2::RcBlock::new(
                            move |_action: std::ptr::NonNull<
                                objc2_app_kit::NSTableViewRowAction,
                            >,
                                  row: isize| {
                                ffi_guard::contain((), || {
                                    perform(row as usize, day_edge, i);
                                    // A button press leaves the buttons revealed; close
                                    // them (a full slide already closed itself).
                                    unsafe { table.setRowActionsVisible(false) };
                                })
                            },
                        );
                        let action =
                            objc2_app_kit::NSTableViewRowAction::rowActionWithStyle_title_handler(
                                style,
                                &NSString::from_str(&a.label),
                                &handler,
                            );
                        if let Some(t) = a.tint {
                            unsafe { action.setBackgroundColor(Some(&nscolor(t))) };
                        }
                        // Glyph above the label — the Mail row-action look. The SF symbol
                        // resolves per OS release; an unknown name yields no image and the
                        // button keeps its label alone.
                        if let Some(sym) = a.symbol {
                            let img = objc2_app_kit::NSImage::imageWithSystemSymbolName_accessibilityDescription(
                                &NSString::from_str(day_spec::sf_symbol_name(sym)),
                                None,
                            );
                            if let Some(img) = img {
                                unsafe { action.setImage(Some(&img)) };
                            }
                        }
                        action
                    })
                    .collect();
                NSArray::from_retained_slice(&actions)
            })
        }
    }
);

impl DayListData {
    fn new(
        mtm: MainThreadMarker,
        node: NodeId,
        selectable: bool,
        multi: bool,
        automatic: bool,
        sections: bool,
    ) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(ListIvars {
            node,
            source: RefCell::new(None),
            selectable: std::cell::Cell::new(selectable),
            multi: std::cell::Cell::new(multi),
            suppress: std::cell::Cell::new(false),
            tokens: RefCell::new(Vec::new()),
            automatic,
            sections,
            header_estimate: std::cell::Cell::new(28.0),
            heights: RefCell::new(std::collections::HashMap::new()),
            cell_tokens: RefCell::new(std::collections::HashMap::new()),
            estimate: std::cell::Cell::new(44.0),
            heights_pending: std::cell::Cell::new(false),
        });
        unsafe { msg_send![super(this), init] }
    }

    /// A self-sizing row was just bound to `cell`: record the height Day laid it at, and if
    /// the table drew the row at another height (the estimate, or the row's old content),
    /// correct it on the next turn. Not here: this runs inside NSTableView's own tiling.
    fn note_row_height(
        &self,
        table: &NSTableView,
        source: &ListSource,
        row: isize,
        cell: RawHandle,
        header: bool,
    ) {
        let height = (source.cell_height)(cell);
        if height <= 0.0 || row < 0 {
            return;
        }
        let token = (source.token_at)(row as usize);
        self.ivars()
            .cell_tokens
            .borrow_mut()
            .insert(cell as usize, token);
        self.ivars().heights.borrow_mut().insert(token, height);
        if header {
            self.ivars().header_estimate.set(height);
        } else {
            self.ivars().estimate.set(height);
        }
        let drawn = unsafe { table.rectOfRow(row) }.size.height;
        if (drawn - height).abs() > 0.5 {
            self.post_row_heights(table);
        }
    }

    /// Whether display row `row` is a section header (docs/list.md "Sections").
    fn is_header(&self, row: isize) -> bool {
        row >= 0
            && self
                .ivars()
                .source
                .borrow()
                .as_ref()
                .and_then(|s| s.is_header.clone())
                .is_some_and(|is_header| is_header(row as usize))
    }

    /// `ListPatch::RowSizeInvalidated`: the row in `cell` was re-laid at `height`. Arrives under
    /// the day-core borrow, so it only records the height; the table is told after the pass.
    fn row_resized(&self, table: &NSTableView, cell: usize, height: f64) {
        let token = self.ivars().cell_tokens.borrow().get(&cell).copied();
        if let Some(token) = token {
            self.ivars().heights.borrow_mut().insert(token, height);
            self.post_row_heights(table);
        }
    }

    /// Tell the table, on the next main-loop turn, about every row near the viewport whose drawn
    /// height differs from the one Day laid it at. Coalesced: a pass that re-lays many rows
    /// posts one correction.
    fn post_row_heights(&self, table: &NSTableView) {
        if self.ivars().heights_pending.replace(true) {
            return;
        }
        // Raw +1 pointers across the post (the closure must be Send, which Retained is not;
        // everything stays on the main thread).
        let Some(this) = (unsafe { Retained::retain(self as *const Self as *mut Self) }) else {
            return;
        };
        let this = Retained::into_raw(this) as usize;
        let table = Retained::into_raw(table.retain()) as usize;
        <AppKit as Platform>::post(Box::new(move || {
            // Reclaim both +1s first, so every early return balances them.
            let this = unsafe { Retained::from_raw(this as *mut DayListData) };
            let table = unsafe { Retained::from_raw(table as *mut NSTableView) };
            let (Some(this), Some(table)) = (this, table) else {
                return;
            };
            this.ivars().heights_pending.set(false);
            ffi_guard::contain((), || this.apply_row_heights(&table));
        }));
    }

    fn apply_row_heights(&self, table: &NSTableView) {
        let Some(source) = self.ivars().source.borrow().clone() else {
            return;
        };
        let count = unsafe { table.numberOfRows() }.max(0) as usize;
        let shown = unsafe { table.rowsInRect(table.visibleRect()) };
        // The viewport and the rows AppKit prepares around it.
        let first = shown.location.saturating_sub(8);
        let last = (shown.location + shown.length + 8)
            .min(count)
            .min((source.len)());
        let changed = objc2_foundation::NSMutableIndexSet::new();
        {
            let heights = self.ivars().heights.borrow();
            for row in first..last {
                if let Some(&height) = heights.get(&(source.token_at)(row)) {
                    let drawn = unsafe { table.rectOfRow(row as isize) }.size.height;
                    if (drawn - height).abs() > 0.5 {
                        unsafe { changed.addIndex(row) };
                    }
                }
            }
        }
        if changed.count() == 0 {
            return;
        }
        // Unanimated: the row takes its content's height, it does not grow into it.
        NSAnimationContext::beginGrouping();
        NSAnimationContext::currentContext().setDuration(0.0);
        unsafe { table.noteHeightOfRowsWithIndexesChanged(&changed) };
        NSAnimationContext::endGrouping();
    }

    /// If this Reload is the same row set in a new order, the incremental `moveRowAtIndex`
    /// steps (each `(from, to)` interpreted against the already-moved rows, NSTableView's
    /// semantics) that transform the displayed order into the new one — and `None` for
    /// anything else (insert/remove/content change/no change), which reloads flat. Always
    /// refreshes the displayed-order cache.
    ///
    /// Every row that changes position must have a REALIZED row view (`table`): moving a
    /// viewless row (its old position sat outside the viewport, so it was never bound)
    /// animates nothing and leaves the row unbound at its new position — its content, and any
    /// element ids inside it, would simply not exist. Such a reorder returns `None` and
    /// reloads flat, which realizes and binds the row at its new position.
    fn permutation_moves(&self, table: &NSTableView) -> Option<Vec<(usize, usize)>> {
        let source = self.ivars().source.borrow();
        let source = source.as_ref()?;
        let n = (source.len)();
        let new: Vec<u64> = (0..n).map(|i| (source.token_at)(i)).collect();
        let old = std::mem::replace(&mut *self.ivars().tokens.borrow_mut(), new.clone());
        if old.len() != n || n == 0 || old == new {
            return None;
        }
        let (mut so, mut sn) = (old.clone(), new.clone());
        so.sort_unstable();
        sn.sort_unstable();
        if so != sn {
            return None;
        }
        for i in 0..n {
            if old[i] != new[i]
                && unsafe { table.rowViewAtRow_makeIfNecessary(i as isize, false) }.is_none()
            {
                return None;
            }
        }
        let mut work = old;
        let mut moves = Vec::new();
        for i in 0..n {
            if work[i] == new[i] {
                continue;
            }
            let j = (i + 1..n).find(|&j| work[j] == new[i])?;
            let t = work.remove(j);
            work.insert(i, t);
            moves.push((j, i));
        }
        Some(moves)
    }

    /// The dragged row + current row count for an in-flight LOCAL reorder drag — `None` when the
    /// drag came from anywhere but this table (day never accepts foreign drops into a list) or
    /// the pasteboard doesn't carry the day row type.
    fn drag_context(
        &self,
        tv: &NSTableView,
        info: &ProtocolObject<dyn objc2_app_kit::NSDraggingInfo>,
    ) -> Option<(usize, usize)> {
        let src = unsafe { info.draggingSource() }?;
        if Retained::as_ptr(&src) as *const std::ffi::c_void
            != tv as *const NSTableView as *const std::ffi::c_void
        {
            return None;
        }
        let pb = unsafe { info.draggingPasteboard() };
        let from = unsafe { pb.stringForType(&NSString::from_str(DAY_ROW_PASTEBOARD_TYPE)) }?
            .to_string()
            .parse::<usize>()
            .ok()?;
        let len = self.ivars().source.borrow().as_ref().map(|s| (s.len)())?;
        (from < len).then_some((from, len))
    }

    /// The guard's verdict for `from -> to` (accepted index, or -1), through the sync seam.
    fn can_move(&self, from: usize, to: usize) -> i64 {
        self.ivars()
            .source
            .borrow()
            .as_ref()
            .and_then(|s| s.reorder.as_ref().map(|r| (r.can_move)(from, to)))
            .unwrap_or(-1)
    }
}

/// The reuse identifiers of a list's row cells and its section-header cells.
const DAY_ROW_CELL: &str = "day.cell";
const DAY_HEADER_CELL: &str = "day.header";

/// The private pasteboard type carrying a dragged day list row's index (local reorder only).
const DAY_ROW_PASTEBOARD_TYPE: &str = "dev.daybrite.day.row";

/// An NSTableView drop lands at an INSERTION point (`row` with `.Above` semantics, 0..=len);
/// day's seam speaks post-removal target indices. Dropping `from` at insertion `ins`:
fn insertion_to_target(from: usize, ins: usize, len: usize) -> usize {
    let to = if ins > from { ins - 1 } else { ins };
    to.min(len.saturating_sub(1))
}

/// The inverse, for retargeting the drop gap: where the gap sits for a post-removal target.
fn target_to_insertion(from: usize, to: usize) -> usize {
    if to > from { to + 1 } else { to }
}

/// A realized LIST's scroll view ptr → (table, data source) for attach_list / update / measure.
type ListEntry = (Retained<NSTableView>, Retained<DayListData>);

/// Clone a list's (table, data) out of `LIST_STATE` under a SHORT borrow. Every caller then
/// talks to AppKit with the map free: table calls that look innocuous (`endUpdates`, a scroll's
/// tiling, `viewAtColumn:row:makeIfNecessary:`, even `layoutSubtreeIfNeeded`) can synchronously
/// re-enter `viewForRow` → `bind_row` → a flush that tears nodes down — and `release` must be
/// able to take its own borrow at that depth. Holding the map across any of them was the
/// "RefCell already borrowed" contained panic every list walkthrough used to log, 24 a run.
fn list_entry(key: usize) -> Option<ListEntry> {
    LIST_STATE.with(|m| m.borrow().get(&key).cloned())
}

// ---------------------------------------------------------------------------
// DayTreeData — NSOutlineView data-source + delegate for the hierarchical tree (docs/tree.md)
// ---------------------------------------------------------------------------

struct TreeIvars {
    node: NodeId,
    /// Injected by `attach_tree` once day-core wires the driver.
    source: RefCell<Option<TreeSource>>,
    selectable: std::cell::Cell<bool>,
    /// Programmatic selection/disclosure in flight: don't re-emit the event (echo rule).
    suppress: std::cell::Cell<bool>,
    /// token → its interned NSNumber. NSOutlineView tracks items (selection, expansion,
    /// rowForItem) by object identity/equality, so every query for a token must answer with
    /// the same object — which is also what preserves expansion across reloadData.
    items: RefCell<HashMap<u64, Retained<NSNumber>>>,
}

define_class!(
    #[unsafe(super(NSObject))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayTreeData"]
    #[ivars = TreeIvars]
    struct DayTreeData;

    unsafe impl NSObjectProtocol for DayTreeData {}

    unsafe impl NSOutlineViewDataSource for DayTreeData {
        #[unsafe(method(outlineView:numberOfChildrenOfItem:))]
        fn number_of_children(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            item: Option<&objc2::runtime::AnyObject>,
        ) -> isize {
            // Reads the piece's snapshot only (no tree access) — safe even when called
            // synchronously from reloadData inside a with_tree borrow. Guarded because
            // the closures are day-core's.
            ffi_guard::contain(0, || {
                let parent = item.and_then(Self::token_of_item);
                if item.is_some() && parent.is_none() {
                    return 0; // not one of ours (stale query racing a reload)
                }
                self.ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .map(|s| (s.children_len)(parent) as isize)
                    .unwrap_or(0)
            })
        }

        #[unsafe(method_id(outlineView:child:ofItem:))]
        fn child_of_item(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            index: isize,
            item: Option<&objc2::runtime::AnyObject>,
        ) -> Retained<objc2::runtime::AnyObject> {
            // AppKit only asks for children it was told exist, but a stale query racing a
            // reload must degrade (token 0, an unmatched identity) rather than panic — an
            // unwind here crosses an ObjC frame and aborts.
            let token = ffi_guard::contain(0, || {
                let parent = item.and_then(Self::token_of_item);
                self.ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .map(|s| (s.child_token)(parent, index.max(0) as usize))
                    .unwrap_or(0)
            });
            let ns = self.intern(token);
            unsafe { objc2::rc::Retained::cast_unchecked(ns) }
        }

        #[unsafe(method(outlineView:isItemExpandable:))]
        fn is_expandable(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            item: &objc2::runtime::AnyObject,
        ) -> bool {
            ffi_guard::contain(false, || {
                let Some(token) = Self::token_of_item(item) else {
                    return false;
                };
                self.ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .map(|s| (s.expandable)(token))
                    .unwrap_or(false)
            })
        }

        // --- drag-to-move (docs/tree.md): the dragged node rides the pasteboard as a
        // private-typed token string; `validateDrop` consults the guard live (forbidden
        // cursor where it denies, including ONTO-a-row drops via childIndex -1), and
        // `acceptDrop` commits through the sync seam — the app's own data write reloads.

        #[unsafe(method_id(outlineView:pasteboardWriterForItem:))]
        fn pasteboard_writer_for_item(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            item: &objc2::runtime::AnyObject,
        ) -> Option<Retained<ProtocolObject<dyn objc2_app_kit::NSPasteboardWriting>>> {
            let make = || {
                let movable = self
                    .ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .is_some_and(|s| s.moves.is_some());
                let token = Self::token_of_item(item)?;
                if !movable {
                    return None;
                }
                let pbitem = objc2_app_kit::NSPasteboardItem::new();
                unsafe {
                    pbitem.setString_forType(
                        &NSString::from_str(&token.to_string()),
                        &NSString::from_str(DAY_TREE_PASTEBOARD_TYPE),
                    );
                }
                Some(ProtocolObject::from_retained(pbitem))
            };
            ffi_guard::contain(None, make)
        }

        #[unsafe(method(outlineView:validateDrop:proposedItem:proposedChildIndex:))]
        fn validate_drop(
            &self,
            ov: &objc2_app_kit::NSOutlineView,
            info: &ProtocolObject<dyn objc2_app_kit::NSDraggingInfo>,
            item: Option<&objc2::runtime::AnyObject>,
            child_index: isize,
        ) -> objc2_app_kit::NSDragOperation {
            ffi_guard::contain(objc2_app_kit::NSDragOperation::None, || {
                match self.drop_proposal(ov, info, item, child_index) {
                    Some((token, parent, index)) if self.can_move(token, parent, index) => {
                        objc2_app_kit::NSDragOperation::Move
                    }
                    _ => objc2_app_kit::NSDragOperation::None,
                }
            })
        }

        #[unsafe(method(outlineView:acceptDrop:item:childIndex:))]
        fn accept_drop(
            &self,
            ov: &objc2_app_kit::NSOutlineView,
            info: &ProtocolObject<dyn objc2_app_kit::NSDraggingInfo>,
            item: Option<&objc2::runtime::AnyObject>,
            child_index: isize,
        ) -> bool {
            let drop = || {
                let Some((token, parent, index)) = self.drop_proposal(ov, info, item, child_index)
                else {
                    return false;
                };
                if !self.can_move(token, parent, index) {
                    return false;
                }
                // Commit through the sync seam: defers the app's `on_move`; the app's own
                // data write drives the Reload (no native row animation on this path).
                let mv = self
                    .ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .and_then(|s| s.moves.as_ref().map(|m| m.move_node.clone()));
                let Some(mv) = mv else { return false };
                mv(token, parent, index);
                true
            };
            ffi_guard::contain(false, drop)
        }
    }

    unsafe impl NSControlTextEditingDelegate for DayTreeData {}

    unsafe impl NSOutlineViewDelegate for DayTreeData {
        #[unsafe(method(outlineView:isGroupItem:))]
        fn is_group_item(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            item: &objc2::runtime::AnyObject,
        ) -> bool {
            Self::token_of_item(item).is_some_and(|t| {
                self.ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .is_some_and(|s| (s.section_header)(t))
            })
        }
        #[unsafe(method(outlineView:shouldSelectItem:))]
        fn should_select_item(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            item: &objc2::runtime::AnyObject,
        ) -> bool {
            Self::token_of_item(item).is_some_and(|t| {
                self.ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .is_some_and(|s| !(s.section_header)(t))
            })
        }

        #[unsafe(method_id(outlineView:viewForTableColumn:item:))]
        fn view_for_item(
            &self,
            ov: &objc2_app_kit::NSOutlineView,
            _col: Option<&NSTableColumn>,
            item: &objc2::runtime::AnyObject,
        ) -> Option<Retained<NSView>> {
            // Guarded: `bind_row` builds the app's row content.
            ffi_guard::contain(None, || {
                let mtm = self.mtm();
                let token = Self::token_of_item(item)?;
                let ident = NSString::from_str("day.tree.cell");
                // Recycle a cell view if one is free; else make a fresh flipped container
                // (DayTreeCell re-lays its Day row at its own width — indentation makes
                // every tree cell's width per-row).
                let cell: Retained<NSView> =
                    unsafe { ov.makeViewWithIdentifier_owner(&ident, None) }.unwrap_or_else(|| {
                        let v: Retained<NSView> =
                            Retained::into_super(Retained::into_super(DayTreeCell::new(mtm)));
                        unsafe { v.setIdentifier(Some(&ident)) };
                        v
                    });
                if let Some(source) = self.ivars().source.borrow().as_ref() {
                    let raw = Retained::as_ptr(&cell) as RawHandle;
                    if let Some(cell) = cell.downcast_ref::<DayTreeCell>() {
                        unsafe {
                            cell.setTextField(None);
                        }
                    }
                    (source.bind_row)(token, raw);
                    // Associate the actual Day label with NSTableCellView so AppKit can
                    // apply group typography and source-list background styles normally.
                    if (source.section_header)(token) {
                        fn label_in(view: &NSView) -> Option<Retained<NSTextField>> {
                            for child in unsafe { view.subviews() }.iter() {
                                if let Ok(label) = child.clone().downcast::<NSTextField>() {
                                    return Some(label);
                                }
                                if let Some(label) = label_in(&child) {
                                    return Some(label);
                                }
                            }
                            None
                        }
                        if let Some(label) = label_in(&cell) {
                            let cell = cell.downcast_ref::<DayTreeCell>()?;
                            unsafe {
                                cell.setTextField(Some(&label));
                            }
                        }
                    }
                }
                Some(cell)
            })
        }

        #[unsafe(method_id(outlineView:typeSelectStringForTableColumn:item:))]
        fn type_select_string(
            &self,
            _ov: &objc2_app_kit::NSOutlineView,
            _col: Option<&NSTableColumn>,
            item: &objc2::runtime::AnyObject,
        ) -> Option<Retained<NSString>> {
            ffi_guard::contain(None, || {
                let token = Self::token_of_item(item)?;
                let text = self
                    .ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .map(|s| (s.type_select_text)(token))
                    .unwrap_or_default();
                // Empty = this row doesn't participate in type-select.
                (!text.is_empty()).then(|| NSString::from_str(&text))
            })
        }

        #[unsafe(method_id(outlineView:rowViewForItem:))]
        fn row_view_for_item(
            &self,
            ov: &objc2_app_kit::NSOutlineView,
            _item: &objc2::runtime::AnyObject,
        ) -> Retained<objc2_app_kit::NSTableRowView> {
            if unsafe { ov.style() } == objc2_app_kit::NSTableViewStyle::SourceList {
                // AppKit owns source-list group backgrounds, floating headers and selection.
                unsafe { objc2_app_kit::NSTableRowView::new(self.mtm()) }
            } else {
                // The rounded-selection row (see DayTreeRowView).
                let rv: Retained<DayTreeRowView> =
                    unsafe { msg_send![DayTreeRowView::alloc(self.mtm()), init] };
                Retained::into_super(rv)
            }
        }

        #[unsafe(method(outlineViewSelectionDidChange:))]
        fn selection_did_change(&self, notification: &NSNotification) {
            ffi_guard::contain((), || {
                if self.ivars().suppress.get() || !self.ivars().selectable.get() {
                    return;
                }
                let Some(obj) = (unsafe { notification.object() }) else {
                    return;
                };
                let Ok(ov) = obj.downcast::<objc2_app_kit::NSOutlineView>() else {
                    return;
                };
                // Always the FULL token set (docs/tree.md): a tree cannot speak row indices.
                let idx = unsafe { ov.selectedRowIndexes() };
                let mut tokens = Vec::with_capacity(idx.count());
                let mut i = idx.firstIndex();
                while i != objc2_foundation::NSNotFound as usize {
                    if let Some(item) = unsafe { ov.itemAtRow(i as isize) }
                        && let Some(tok) = Self::token_of_item(&item)
                    {
                        tokens.push(tok);
                    }
                    i = unsafe { idx.indexGreaterThanIndex(i) };
                }
                emit(self.ivars().node, Event::TreeSelection(tokens));
            })
        }

        #[unsafe(method(outlineView:didRemoveRowView:forRow:))]
        fn did_remove_row_view(
            &self,
            ov: &objc2_app_kit::NSOutlineView,
            row_view: &objc2_app_kit::NSTableRowView,
            _row: isize,
        ) {
            // The row went back to the reuse pool (a collapse, a reload dropping it): clear
            // its day element ids so it stops answering `find_by_id`. DEFERRED — this fires
            // inside collapse/reload stacks that hold the day-core borrow — and re-checked:
            // a cell already reused by the same turn's reload has a window again, and its
            // fresh ids must survive.
            ffi_guard::contain((), || {
                let mut cell_ptr: Option<usize> = None;
                for sub in row_view.subviews().iter() {
                    let is_cell = sub
                        .identifier()
                        .map(|i| i.to_string() == "day.tree.cell")
                        .unwrap_or(false);
                    if is_cell {
                        cell_ptr = Some(Retained::as_ptr(&sub) as usize);
                    }
                }
                let Some(cell) = cell_ptr else { return };
                let Some(scroll) = (unsafe { ov.enclosingScrollView() }) else {
                    return;
                };
                let key = Retained::as_ptr(&scroll) as usize;
                // Carry a RETAIN across the post as a raw +1 pointer (the boxed closure must
                // be Send, which Retained is not; we stay on the main thread throughout).
                // AppKit is free to dealloc removed row views — a bare pointer died here once.
                let retained =
                    unsafe { Retained::into_raw(Retained::retain(cell as *mut NSView).unwrap()) }
                        as usize;
                <AppKit as Platform>::post(Box::new(move || {
                    // Reclaim the +1 first, unconditionally — every early return below must
                    // still balance the retain.
                    let cell_view: Retained<NSView> =
                        match unsafe { Retained::from_raw(retained as *mut NSView) } {
                            Some(v) => v,
                            None => return,
                        };
                    let recycle = tree_entry(key).and_then(|(_, data)| {
                        data.ivars()
                            .source
                            .borrow()
                            .as_ref()
                            .map(|s| s.recycle.clone())
                    });
                    let Some(recycle) = recycle else { return };
                    if cell_view.window().is_some() {
                        return; // reused already — its ids are the live row's
                    }
                    recycle(cell as RawHandle);
                }));
            })
        }

        #[unsafe(method(outlineViewItemDidExpand:))]
        fn item_did_expand(&self, notification: &NSNotification) {
            self.report_disclosure(notification, true);
        }

        #[unsafe(method(outlineViewItemDidCollapse:))]
        fn item_did_collapse(&self, notification: &NSNotification) {
            self.report_disclosure(notification, false);
        }
    }
);

impl DayTreeData {
    fn new(mtm: MainThreadMarker, node: NodeId, selectable: bool) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(TreeIvars {
            node,
            source: RefCell::new(None),
            selectable: std::cell::Cell::new(selectable),
            suppress: std::cell::Cell::new(false),
            items: RefCell::new(HashMap::new()),
        });
        unsafe { msg_send![super(this), init] }
    }

    /// The same NSNumber for a token, every time — NSOutlineView's item identity.
    fn intern(&self, token: u64) -> Retained<NSNumber> {
        self.ivars()
            .items
            .borrow_mut()
            .entry(token)
            .or_insert_with(|| NSNumber::new_u64(token))
            .clone()
    }

    fn token_of_item(item: &objc2::runtime::AnyObject) -> Option<u64> {
        item.downcast_ref::<NSNumber>().map(|n| n.as_u64())
    }

    /// A native disclosure (user click, keyboard left/right) → `Event::TreeExpanded`.
    /// Programmatic `TreePatch::Expand` applications are suppressed (the echo rule).
    fn report_disclosure(&self, notification: &NSNotification, expanded: bool) {
        ffi_guard::contain((), || {
            if self.ivars().suppress.get() {
                return;
            }
            let token = unsafe { notification.userInfo() }
                .and_then(|ui| ui.objectForKey(&*NSString::from_str("NSObject")))
                .and_then(|item| Self::token_of_item(&item));
            if let Some(token) = token {
                emit(self.ivars().node, Event::TreeExpanded { token, expanded });
            }
        })
    }

    /// The full drop proposal — `(dragged token, parent token, index)` — for a LOCAL drag
    /// from this outline; `None` for a foreign drag or an unparseable one. `index: None`
    /// means "ONTO the parent" (NSOutlineView's childIndex -1, `NSOutlineViewDropOnItemIndex`).
    fn drop_proposal(
        &self,
        ov: &objc2_app_kit::NSOutlineView,
        info: &ProtocolObject<dyn objc2_app_kit::NSDraggingInfo>,
        item: Option<&objc2::runtime::AnyObject>,
        child_index: isize,
    ) -> Option<(u64, Option<u64>, Option<usize>)> {
        let src = unsafe { info.draggingSource() }?;
        if Retained::as_ptr(&src) as *const std::ffi::c_void
            != ov as *const objc2_app_kit::NSOutlineView as *const std::ffi::c_void
        {
            return None;
        }
        let pb = unsafe { info.draggingPasteboard() };
        let token = unsafe { pb.stringForType(&NSString::from_str(DAY_TREE_PASTEBOARD_TYPE)) }?
            .to_string()
            .parse::<u64>()
            .ok()?;
        let parent = match item {
            Some(i) => Some(Self::token_of_item(i)?), // a non-token item is not ours
            None => None,
        };
        let index = (child_index >= 0).then_some(child_index as usize);
        Some((token, parent, index))
    }

    /// The guard's live verdict through the sync seam.
    fn can_move(&self, token: u64, parent: Option<u64>, index: Option<usize>) -> bool {
        self.ivars()
            .source
            .borrow()
            .as_ref()
            .and_then(|s| s.moves.as_ref().map(|m| (m.can_move)(token, parent, index)))
            .map(|v| v == MoveVerdict::Allow)
            .unwrap_or(false)
    }
}

// DayOutlineView — an NSOutlineView that PINS its width to its clip on every layout pass.
// A table sizes itself from its COLUMNS, and the autoresizing mask only tracks deltas, so
// any early pass at a different pane width leaves a permanent offset (a 233pt table in a
// 220pt pane, whose selection pill then clips mid-corner). Enforcing it in `layout` — not
// in occasional deferred posts — closes every window where a stale width could draw.
define_class!(
    #[unsafe(super(objc2_app_kit::NSOutlineView))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayOutlineView"]
    struct DayOutlineView;

    impl DayOutlineView {
        #[unsafe(method(layout))]
        fn layout(&self) {
            sync_tree_width(self);
            let _: () = unsafe { msg_send![super(self), layout] };
        }

        /// A summon-time ROW context menu (docs/menus.md, docs/tree.md): right-click asks
        /// the tree's `row_menu` provider for the row under the pointer.
        #[unsafe(method_id(menuForEvent:))]
        fn menu_for_event(
            &self,
            event: &objc2_app_kit::NSEvent,
        ) -> Option<Retained<NSMenu>> {
            ffi_guard::contain(None, || {
                let scroll = unsafe { self.enclosingScrollView() }?;
                let (_, data) = tree_entry(Retained::as_ptr(&scroll) as usize)?;
                let row_menu = data
                    .ivars()
                    .source
                    .borrow()
                    .as_ref()
                    .and_then(|s| s.row_menu.clone())?;
                let p = self.convertPoint_fromView(unsafe { event.locationInWindow() }, None);
                let row = unsafe { self.rowAtPoint(p) };
                if row < 0 {
                    return None;
                }
                let token =
                    unsafe { self.itemAtRow(row) }.and_then(|i| DayTreeData::token_of_item(&i))?;
                let items = row_menu(token);
                if items.is_empty() {
                    return None;
                }
                Some(build_ns_menu(self.mtm(), "", &items))
            })
        }
    }
);

// DayTreeRowView — a tree row with the MODERN selection: a rounded pill, inset from the
// pane's edges, in the system's semantic selection colors (accent when the tree has focus,
// the quiet gray otherwise). Drawn by hand rather than through `NSTableViewStyle::Inset`,
// whose machinery pads the table wider than its clip and fights day's fixed-frame layout —
// and a hand-drawn plain color also captures correctly offscreen, where materials go black
// (docs/navigation.md's sidebar-screenshot rule).
define_class!(
    #[unsafe(super(objc2_app_kit::NSTableRowView))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayTreeRowView"]
    struct DayTreeRowView;

    impl DayTreeRowView {
        #[unsafe(method(drawSelectionInRect:))]
        fn draw_selection_in_rect(&self, _dirty: NSRect) {
            if !unsafe { self.isSelected() } {
                return;
            }
            let color = if unsafe { self.isEmphasized() } {
                unsafe { objc2_app_kit::NSColor::selectedContentBackgroundColor() }
            } else {
                unsafe { objc2_app_kit::NSColor::unemphasizedSelectedContentBackgroundColor() }
            };
            let b = self.bounds();
            let pill = NSRect::new(
                NSPoint::new(b.origin.x + 5.0, b.origin.y + 1.0),
                NSSize::new(
                    (b.size.width - 10.0).max(0.0),
                    (b.size.height - 2.0).max(0.0),
                ),
            );
            unsafe {
                color.setFill();
                objc2_app_kit::NSBezierPath::bezierPathWithRoundedRect_xRadius_yRadius(
                    pill, 5.0, 5.0,
                )
                .fill();
            }
        }
    }
);

// DayTreeCell — a tree row's flipped cell container. NSOutlineView frames it at the row's
// INDENTED position, so its width is per-row; every native layout pass re-lays the Day row
// content inside it at that width through the seam's `layout_cell`.
define_class!(
    #[unsafe(super(objc2_app_kit::NSTableCellView))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayTreeCell"]
    struct DayTreeCell;

    impl DayTreeCell {
        #[unsafe(method(isFlipped))]
        fn is_flipped(&self) -> bool {
            true
        }

        #[unsafe(method(layout))]
        fn layout(&self) {
            let _: () = unsafe { msg_send![super(self), layout] };
            ffi_guard::contain((), || {
                let width = self.bounds().size.width;
                if width <= 0.0 {
                    return;
                }
                // This cell's tree: walk up to the outline, then to its scroll host, which
                // keys TREE_STATE. (The cell may be in the reuse pool — no outline — or the
                // tree may be mid-teardown; both just skip.)
                let mut cur = unsafe { self.superview() };
                let mut outline: Option<Retained<objc2_app_kit::NSOutlineView>> = None;
                while let Some(v) = cur {
                    cur = unsafe { v.superview() };
                    if let Ok(ov) = v.downcast::<objc2_app_kit::NSOutlineView>() {
                        outline = Some(ov);
                        break;
                    }
                }
                let Some(ov) = outline else { return };
                let Some(scroll) = (unsafe { ov.enclosingScrollView() }) else {
                    return;
                };
                let f = tree_entry(Retained::as_ptr(&scroll) as usize)
                    .and_then(|(_, data)| {
                        data.ivars()
                            .source
                            .borrow()
                            .as_ref()
                            .map(|s| s.layout_cell_size.clone())
                    });
                if let Some(f) = f {
                    f(self as *const Self as RawHandle, Size::new(width, self.bounds().size.height));
                }
            })
        }
    }
);

impl DayTreeCell {
    fn new(mtm: MainThreadMarker) -> Retained<Self> {
        unsafe { msg_send![Self::alloc(mtm), init] }
    }
}

/// The private pasteboard type carrying a dragged day tree node's token (local moves only).
const DAY_TREE_PASTEBOARD_TYPE: &str = "dev.daybrite.day.tree.node";

/// A realized TREE's scroll view ptr → (outline, data source).
type TreeEntry = (
    Retained<objc2_app_kit::NSOutlineView>,
    Retained<DayTreeData>,
);

/// Clone a tree's (outline, data) out of `TREE_STATE` under a SHORT borrow — the same
/// re-entrancy rule as `list_entry` (its comment has the war story).
fn tree_entry(key: usize) -> Option<TreeEntry> {
    TREE_STATE.with(|m| m.borrow().get(&key).cloned())
}

/// Keep the outline exactly as wide as its clip — DayOutlineView calls this on every layout
/// pass (its comment has the why). The list never noticed the width drift because it lays
/// row content at the HOST's width; tree rows lay out at the CELL's, which exposes it.
fn sync_tree_width(outline: &objc2_app_kit::NSOutlineView) {
    let Some(scroll) = (unsafe { outline.enclosingScrollView() }) else {
        return;
    };
    let clip_w = unsafe { scroll.contentView() }.bounds().size.width;
    let f = outline.frame();
    if clip_w > 0.0 && (f.size.width - clip_w).abs() > 0.5 {
        unsafe {
            outline.setFrameSize(NSSize::new(clip_w, f.size.height));
            outline.sizeLastColumnToFit();
        }
    }
}

/// Realize the tree's visible rows on the next main-loop turn, outside any borrow — the
/// tree twin of `post_realize_visible_rows` (its comment explains the occluded-window trap).
fn post_realize_visible_tree_rows(key: usize) {
    <AppKit as Platform>::post(Box::new(move || {
        if let Some((outline, _)) = tree_entry(key) {
            let range = unsafe { outline.rowsInRect(outline.visibleRect()) };
            for row in range.location..range.location + range.length {
                let _ = unsafe { outline.viewAtColumn_row_makeIfNecessary(0, row as isize, true) };
            }
        }
        day_core::pump_events();
    }));
}

/// A realized NAV_MENU's native outline view paired with its data-source object.
type NavMenuEntry = (
    Retained<objc2_app_kit::NSOutlineView>,
    Retained<DayNavMenuData>,
);

fn ns_rect(r: day_spec::Rect) -> NSRect {
    NSRect::new(
        NSPoint::new(r.origin.x, r.origin.y),
        NSSize::new(r.size.width, r.size.height),
    )
}

fn draw_op(op: &DrawOp) {
    unsafe {
        match op {
            // One path for the whole batch, then one fill or stroke: the template is appended
            // once per position, so the rasterizer is entered once however many copies there are
            // (docs/canvas.md "Stamping"). A gradient resolves against the batch's own bounds,
            // which is what makes a stamped scatter shade across the group rather than repeating
            // the ramp inside every dot.
            DrawOp::Stamp(st) => {
                let batch = unsafe { objc2_app_kit::NSBezierPath::bezierPath() };
                for p in &st.at {
                    if let Some(copy) = bezier(&st.shape.translated(p.x, p.y)) {
                        unsafe { batch.appendBezierPath(&copy) };
                    }
                }
                let color = match &st.paint {
                    day_spec::Paint::Solid(c) => *c,
                    // A gradient over a stamped batch clips to the whole batch path; the solid
                    // fallback below keeps the marks visible on a backend path that cannot.
                    _ => day_spec::Color::WHITE,
                };
                match &st.stroke {
                    None => {
                        nscolor(color).setFill();
                        unsafe { batch.fill() };
                    }
                    Some(style) => {
                        nscolor(color).setStroke();
                        apply_stroke_style(&batch, style);
                        unsafe { batch.stroke() };
                    }
                }
            }
            DrawOp::Fill(shape, paint) => match paint {
                day_spec::Paint::Solid(color) => {
                    nscolor(*color).setFill();
                    if let Some(p) = bezier(shape) {
                        p.fill();
                    }
                }
                day_spec::Paint::Linear(g) => {
                    // Native linear gradient: clip to the shape's path, then NSGradient along
                    // the line resolved from the gradient's unit points in the shape's bounds.
                    if let (Some(p), Some(grad)) = (bezier(shape), nsgradient(&g.stops)) {
                        let b = shape.bounds();
                        let (s, e) = (g.start.resolve(b), g.end.resolve(b));
                        NSGraphicsContext::saveGraphicsState_class();
                        p.addClip();
                        grad.drawFromPoint_toPoint_options(
                            NSPoint::new(s.x, s.y),
                            NSPoint::new(e.x, e.y),
                            objc2_app_kit::NSGradientDrawingOptions::DrawsBeforeStartingLocation
                                | objc2_app_kit::NSGradientDrawingOptions::DrawsAfterEndingLocation,
                        );
                        NSGraphicsContext::restoreGraphicsState_class();
                    }
                }
                day_spec::Paint::Radial(g) => {
                    // Native radial gradient: clip to the path, map unit space onto the bounds
                    // (elliptical in non-square bounds), draw circular in unit coordinates.
                    if let (Some(p), Some(grad)) = (bezier(shape), nsgradient(&g.stops)) {
                        let b = shape.bounds();
                        NSGraphicsContext::saveGraphicsState_class();
                        p.addClip();
                        concat_unit_to_bounds(b);
                        let c = NSPoint::new(g.center.x, g.center.y);
                        grad.drawFromCenter_radius_toCenter_radius_options(
                            c,
                            0.0,
                            c,
                            g.radius,
                            objc2_app_kit::NSGradientDrawingOptions::DrawsBeforeStartingLocation
                                | objc2_app_kit::NSGradientDrawingOptions::DrawsAfterEndingLocation,
                        );
                        NSGraphicsContext::restoreGraphicsState_class();
                    }
                }
            },
            DrawOp::Stroke(shape, paint, style) => {
                if let Some(p) = bezier(shape) {
                    apply_stroke_style(&p, style);
                    match paint {
                        day_spec::Paint::Solid(color) => {
                            nscolor(*color).setStroke();
                            p.stroke();
                        }
                        // No gradient-stroke primitive here either: turn the stroke into the
                        // region it covers and draw the gradient through that clip.
                        // No gradient-stroke primitive: convert the stroke into the REGION it
                        // covers (CoreGraphics can, and NSGraphicsContext hands us its context),
                        // clip to that, then draw the gradient through it.
                        _ => {
                            let Some(ctx) = NSGraphicsContext::currentContext() else {
                                return;
                            };
                            let cg = ctx.CGContext();
                            NSGraphicsContext::saveGraphicsState_class();
                            objc2_core_graphics::CGContext::add_path(Some(&cg), Some(&p.CGPath()));
                            objc2_core_graphics::CGContext::replace_path_with_stroked_path(Some(
                                &cg,
                            ));
                            objc2_core_graphics::CGContext::clip(Some(&cg));
                            draw_gradient_in(paint, shape.bounds());
                            NSGraphicsContext::restoreGraphicsState_class();
                        }
                    }
                }
            }
            DrawOp::Clip(shape) => {
                // `addClip` intersects with the current clip and honors the path's winding rule.
                if let Some(p) = bezier(shape) {
                    p.addClip();
                }
            }
            DrawOp::Text {
                text,
                at,
                size,
                color,
                anchor,
                font,
            } => {
                let font = canvas_nsfont(*size, font);
                let attrs = canvas_text_attrs(&font, *color);
                let ns = NSString::from_str(text);
                let mut origin = NSPoint::new(at.x, at.y);
                // `drawAtPoint:` takes the top-leading corner of the line box, so any other
                // anchor is an offset from it. The size comes from the attributes the draw is
                // about to use, which is why the alignment belongs here and not in the app: the
                // caller would have to ask for these same metrics through `measure_text` first.
                if *anchor != day_spec::TextAnchor::LEADING {
                    let sz: NSSize = msg_send![&ns, sizeWithAttributes: &*attrs];
                    let (dx, dy) = anchor.offset(sz.width, sz.height, font.ascender());
                    origin.x += dx;
                    origin.y += dy;
                }
                let _: () = msg_send![&ns, drawAtPoint: origin, withAttributes: &*attrs];
            }
            // A released bitmap draws nothing rather than a placeholder: the canvas re-records
            // on every tracked read, so a handle can be dropped between the record and the
            // replay, and a frame that flashes a grey box is worse than one that omits the image.
            DrawOp::Image {
                image,
                rect,
                opacity,
            } => {
                let img = BITMAPS.with(|m| m.borrow().get(&image.0).map(|b| b.image.clone()));
                if let Some(img) = img {
                    let dest = NSRect::new(
                        NSPoint::new(rect.origin.x, rect.origin.y),
                        NSSize::new(rect.size.width, rect.size.height),
                    );
                    // DayCanvas is flipped (top-left origin). Respect that context so image
                    // rows stay upright, including under the canvas's rotation/zoom transforms.
                    // A zero `fromRect` means the whole image; `fraction` multiplies its alpha.
                    img.drawInRect_fromRect_operation_fraction_respectFlipped_hints(
                        dest,
                        NSRect::ZERO,
                        objc2_app_kit::NSCompositingOperation::SourceOver,
                        *opacity,
                        true,
                        None,
                    );
                }
            }
            DrawOp::Save => NSGraphicsContext::saveGraphicsState_class(),
            DrawOp::Restore => NSGraphicsContext::restoreGraphicsState_class(),
            DrawOp::Concat(m) => {
                let t = NSAffineTransform::new();
                t.setTransformStruct(NSAffineTransformStruct {
                    m11: m.a,
                    m12: m.b,
                    m21: m.c,
                    m22: m.d,
                    tX: m.tx,
                    tY: m.ty,
                });
                t.concat();
            }
        }
    }
}

/// An `NSGradient` from a display-list gradient's stops (sRGB, like every canvas color).
fn nsgradient(
    stops: &[(f64, day_spec::Color)],
) -> Option<objc2::rc::Retained<objc2_app_kit::NSGradient>> {
    if stops.is_empty() {
        return None;
    }
    let colors = objc2_foundation::NSArray::from_retained_slice(
        &stops.iter().map(|(_, c)| nscolor(*c)).collect::<Vec<_>>(),
    );
    let locations: Vec<f64> = stops.iter().map(|(o, _)| *o).collect();
    unsafe {
        objc2_app_kit::NSGradient::initWithColors_atLocations_colorSpace(
            objc2_app_kit::NSGradient::alloc(),
            &colors,
            locations.as_ptr(),
            &objc2_app_kit::NSColorSpace::sRGBColorSpace(),
        )
    }
}

/// Concat a bounds-mapping transform (unit gradient space → `b`) onto the current context, so a
/// circular gradient drawn in unit coordinates renders elliptically stretched to the bounds.
fn concat_unit_to_bounds(b: day_spec::Rect) {
    let t = NSAffineTransform::new();
    t.setTransformStruct(NSAffineTransformStruct {
        m11: b.size.width,
        m12: 0.0,
        m21: 0.0,
        m22: b.size.height,
        tX: b.origin.x,
        tY: b.origin.y,
    });
    unsafe { t.concat() };
}

/// Put a [`day_spec::StrokeStyle`] onto a path.
///
/// NOTE: this backend used to force ROUND caps on every stroke. It now honors the style, whose
/// default is BUTT — the same default the spec and every other backend use. A line that wants
/// round ends asks for `StrokeStyle::round`.
fn apply_stroke_style(p: &objc2_app_kit::NSBezierPath, style: &day_spec::StrokeStyle) {
    use day_spec::{LineCap, LineJoin};
    unsafe {
        p.setLineWidth(style.width);
        p.setLineCapStyle(match style.cap {
            LineCap::Butt => objc2_app_kit::NSLineCapStyle::Butt,
            LineCap::Round => objc2_app_kit::NSLineCapStyle::Round,
            LineCap::Square => objc2_app_kit::NSLineCapStyle::Square,
        });
        if style.is_plain() {
            return;
        }
        p.setLineJoinStyle(match style.join {
            LineJoin::Miter => objc2_app_kit::NSLineJoinStyle::Miter,
            LineJoin::Round => objc2_app_kit::NSLineJoinStyle::Round,
            LineJoin::Bevel => objc2_app_kit::NSLineJoinStyle::Bevel,
        });
        p.setMiterLimit(style.miter_limit);
        if !style.dash.is_empty() {
            let pattern: Vec<objc2_core_foundation::CGFloat> = style.dash.to_vec();
            p.setLineDash_count_phase(pattern.as_ptr(), pattern.len() as isize, style.dash_phase);
        }
    }
}

/// Draw a gradient through whatever clip is installed, in AppKit's own NSGradient terms.
/// Shared by the gradient FILL arms and the gradient STROKE arm, which differ only in what they
/// clipped to first.
fn draw_gradient_in(paint: &day_spec::Paint, bounds: day_spec::Rect) {
    let opts = objc2_app_kit::NSGradientDrawingOptions::DrawsBeforeStartingLocation
        | objc2_app_kit::NSGradientDrawingOptions::DrawsAfterEndingLocation;
    match paint {
        day_spec::Paint::Linear(g) => {
            if let Some(grad) = nsgradient(&g.stops) {
                let (s, e) = (g.start.resolve(bounds), g.end.resolve(bounds));
                unsafe {
                    grad.drawFromPoint_toPoint_options(
                        NSPoint::new(s.x, s.y),
                        NSPoint::new(e.x, e.y),
                        opts,
                    )
                };
            }
        }
        day_spec::Paint::Radial(g) => {
            if let Some(grad) = nsgradient(&g.stops) {
                NSGraphicsContext::saveGraphicsState_class();
                concat_unit_to_bounds(bounds);
                let c = NSPoint::new(g.center.x, g.center.y);
                unsafe {
                    grad.drawFromCenter_radius_toCenter_radius_options(c, 0.0, c, g.radius, opts)
                };
                NSGraphicsContext::restoreGraphicsState_class();
            }
        }
        day_spec::Paint::Solid(_) => {}
    }
}

fn apply_button_content(
    btn: &NSButton,
    title: &str,
    icon: Option<&day_spec::Icon>,
    icon_only: bool,
) {
    let image = icon.and_then(|i| crate::toolbar::image_for(i, title, btn.mtm()));
    if let Some(image) = &image {
        let size = image.size();
        let longest = size.width.max(size.height);
        if longest > 0.0 {
            image.setSize(objc2_foundation::NSSize::new(
                size.width * 20.0 / longest,
                size.height * 20.0 / longest,
            ));
        }
    }
    let style = BUTTON_STYLES
        .with(|m| m.borrow().get(&ptr_of(btn)).copied())
        .unwrap_or_default();
    BUTTON_IMAGES.with(|images| {
        images.remove(ptr_of(btn));
        if let Some(image) = &image {
            images.insert(ptr_of(btn), image.clone());
        }
    });
    set_button_title(btn, title, style);
    // The position first: the image setter pads a glyph that sits beside a title, and leaves
    // an icon-only one alone, by reading it.
    unsafe {
        btn.setImagePosition(if image.is_none() {
            objc2_app_kit::NSCellImagePosition::NoImage
        } else if icon_only {
            objc2_app_kit::NSCellImagePosition::ImageOnly
        } else {
            objc2_app_kit::NSCellImagePosition::ImageLeading
        });
    }
    set_button_image(btn, style);
    unsafe {
        // The title is the spoken name (an icon-only button shows none), unless the app named
        // the button itself; overwriting that here replaced app labels on every title change.
        if !APP_LABELED.with(|t| t.contains(ptr_of(btn))) {
            btn.setAccessibilityLabel(Some(&NSString::from_str(title)));
        }
        let tooltip = (icon_only && image.is_some()).then(|| NSString::from_str(title));
        btn.setToolTip(tooltip.as_deref());
    }
}

/// Bordered buttons do not reliably apply contentTintColor to template images. Keep
/// the native button, but supply an image that draws the original vector's alpha in
/// the requested contrast color at the destination resolution.
fn set_button_image(btn: &NSButton, style: day_spec::props::ButtonStyleSpec) {
    use day_spec::props::ButtonStyleSpec as S;
    let image = BUTTON_IMAGES.with(|images| images.with(ptr_of(btn), |image| image.clone()));
    let image = image.map(|source| {
        let S::Tinted(fill) = style else {
            return source;
        };
        let size = source.size();
        let ink = nscolor(S::on_tint(fill));
        let draw = block2::RcBlock::new(move |rect: NSRect| {
            source.drawInRect_fromRect_operation_fraction(
                rect,
                NSRect::ZERO,
                objc2_app_kit::NSCompositingOperation::SourceOver,
                1.0,
            );
            unsafe {
                ink.setFill();
                objc2_app_kit::NSRectFillUsingOperation(
                    rect,
                    objc2_app_kit::NSCompositingOperation::SourceIn,
                );
            }
            objc2::runtime::Bool::YES
        });
        objc2_app_kit::NSImage::imageWithSize_flipped_drawingHandler(size, false, &draw)
    });
    unsafe {
        let position = btn.imagePosition();
        // Beside a title, the glyph gets a clear gap: AppKit draws a leading image flush
        // against the text, so the image carries the space itself (a template stays one, so
        // the label color still tints it). The cell centers the image in its slot, so half
        // the extra width lands on each side.
        let image = image.map(|source| {
            // The position is set after this on a fresh button, so an unset one counts as
            // "beside a title"; only an icon-only button keeps the glyph as drawn.
            if position == objc2_app_kit::NSCellImagePosition::ImageOnly {
                return source;
            }
            let size = source.size();
            let template = source.isTemplate();
            let padded = NSSize::new(size.width + 8.0, size.height);
            let draw = block2::RcBlock::new(move |_rect: NSRect| {
                source.drawInRect_fromRect_operation_fraction(
                    NSRect::new(NSPoint::new(0.0, 0.0), size),
                    NSRect::ZERO,
                    objc2_app_kit::NSCompositingOperation::SourceOver,
                    1.0,
                );
                objc2::runtime::Bool::YES
            });
            let out =
                objc2_app_kit::NSImage::imageWithSize_flipped_drawingHandler(padded, false, &draw);
            out.setTemplate(template);
            out
        });
        btn.setImage(image.as_deref());
        btn.setImagePosition(position);
        btn.setImageHugsTitle(true);
    }
}

/// Put `ButtonProps::selected` on an `NSButton`, keeping it an NSButton. A momentary button
/// shows no state, so the first `true` makes it push-on/push-off, whose on state AppKit draws
/// as the bezel's highlighted fill and VoiceOver reads as selected; a button that never
/// selects keeps its momentary type. A click toggles the state natively before the action
/// runs, so the `action:` handler restores the value recorded here.
fn set_button_selected(btn: &objc2_app_kit::NSButton, on: bool) {
    BUTTON_SELECTED.with(|m| m.borrow_mut().insert(ptr_of(btn), on));
    unsafe {
        if on {
            btn.setButtonType(objc2_app_kit::NSButtonType::PushOnPushOff);
        }
        btn.setState(if on {
            NSControlStateValueOn
        } else {
            NSControlStateValueOff
        });
    }
}

/// The corner radius of the tint painted behind a tinted button's bezel: the rounded push
/// bezel's own, so the fill reads as the bezel rather than as a box around it.
const TINT_CORNER_RADIUS: f64 = 6.0;

/// Put a [`day_spec::props::ButtonStyleSpec`] on an `NSButton`, keeping it an NSButton.
///
/// Prominent = the return-key default button. Tinted = `bezelColor`, which AppKit composites
/// through the button's own bezel — so the pressed darkening, the focus ring and the disabled
/// look all still come from the control rather than from us painting a rectangle. macOS 26
/// composites the push bezel as a system material that ignores `bezelColor` on screen (an
/// offscreen `cacheDisplay` still honors it), so the tint is also painted on the control's
/// backing layer, where the translucent material lets it through; on older systems the opaque
/// tinted bezel covers that layer, so nothing changes there.
fn apply_button_style(btn: &objc2_app_kit::NSButton, style: day_spec::props::ButtonStyleSpec) {
    use day_spec::props::ButtonStyleSpec as S;
    let title = unsafe { btn.title() }.to_string();
    unsafe {
        // Reset first, so a patch from one style to another leaves nothing of the old one.
        btn.setKeyEquivalent(&NSString::from_str(""));
        btn.setBezelColor(None);
        btn.setBordered(!matches!(style, S::Plain));
        match style {
            S::Prominent => btn.setKeyEquivalent(&NSString::from_str("\r")),
            S::Tinted(c) => btn.setBezelColor(Some(&nscolor(c))),
            // Bordered is the stock NSButton look already; Automatic asks for nothing, and an
            // NSButton hugs a one-glyph title already, so Compact asks for nothing either.
            S::Bordered | S::Automatic | S::Compact | S::Plain => {}
        }
        btn.setWantsLayer(true);
        if let Some(layer) = btn.layer() {
            match style {
                S::Tinted(c) => {
                    layer.setBackgroundColor(Some(&nscolor(c).CGColor()));
                    layer.setCornerRadius(TINT_CORNER_RADIUS);
                }
                _ => layer.setBackgroundColor(None),
            }
        }
    }
    BUTTON_STYLES.with(|m| m.borrow_mut().insert(ptr_of(btn), style));
    let ink = match style {
        S::Tinted(c) => Some(nscolor(S::on_tint(c))),
        _ => None,
    };
    unsafe {
        btn.setContentTintColor(ink.as_deref());
    }
    set_button_title(btn, &title, style);
    set_button_image(btn, style);
}

/// Set a button's title, coloring it for the tint where there is one.
///
/// `contentTintColor` is NOT the seam for this: on a bordered `NSButton`,
/// AppKit keeps drawing the title in its own control text color — which is how a
/// white-on-rust button came out black-on-rust. An ATTRIBUTED title is the documented way to
/// control the text color, so that is what a tinted button gets.
///
/// The button's own font is carried into the attributes: an attributed title supplies the whole
/// run, so leaving the font out would drop the control font and render at the system default.
fn set_button_title(
    btn: &objc2_app_kit::NSButton,
    title: &str,
    style: day_spec::props::ButtonStyleSpec,
) {
    use day_spec::props::ButtonStyleSpec as S;
    // Changing an attributed title can reset NSButton's image placement. A reactive
    // tint must keep an icon-only button icon-only, including its native template tint.
    let position = unsafe { btn.imagePosition() };
    let S::Tinted(fill) = style else {
        // Plain title: AppKit picks the label color that suits the bezel it is drawing.
        unsafe {
            btn.setTitle(&NSString::from_str(title));
            btn.setImagePosition(position);
        }
        return;
    };
    unsafe {
        let col = nscolor(S::on_tint(fill));
        let font = btn
            .font()
            .unwrap_or_else(|| NSFont::systemFontOfSize(NSFont::systemFontSize()));
        // Centered, matching a plain NSButton title: an attributed title carries its own
        // paragraph style, and the default is left-aligned.
        let para = objc2_app_kit::NSMutableParagraphStyle::new();
        para.setAlignment(objc2_app_kit::NSTextAlignment::Center);
        let keys: [&NSString; 3] = [
            objc2_app_kit::NSFontAttributeName,
            objc2_app_kit::NSForegroundColorAttributeName,
            objc2_app_kit::NSParagraphStyleAttributeName,
        ];
        let objs: [&objc2::runtime::AnyObject; 3] = [
            font.as_ref() as &objc2::runtime::AnyObject,
            col.as_ref() as &objc2::runtime::AnyObject,
            para.as_ref() as &objc2::runtime::AnyObject,
        ];
        let attrs = objc2_foundation::NSDictionary::from_slices::<NSString>(&keys, &objs);
        let s = objc2_foundation::NSAttributedString::initWithString_attributes(
            objc2_foundation::NSAttributedString::alloc(),
            &NSString::from_str(title),
            Some(&attrs),
        );
        btn.setAttributedTitle(&s);
        btn.setImagePosition(position);
    }
}

// NSImageView supports aspect-fit but not aspect-fill. Expand its native drawing about
// the center and clip to the view; this retains vector rendering and template tinting.
define_class!(
    #[unsafe(super(objc2_app_kit::NSImageView))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayFillImageView"]
    struct FillImageView;

    impl FillImageView {
        #[unsafe(method(drawRect:))]
        fn draw_rect(&self, dirty: NSRect) {
            let bounds = self.bounds();
            let image = unsafe { self.image() };
            let Some(size) = image.map(|image| image.size()).filter(|size| {
                size.width > 0.0 && size.height > 0.0
                    && bounds.size.width > 0.0 && bounds.size.height > 0.0
            }) else {
                let _: () = unsafe { msg_send![super(self), drawRect: dirty] };
                return;
            };
            let x = bounds.size.width / size.width;
            let y = bounds.size.height / size.height;
            let scale = x.max(y) / x.min(y);
            let cx = bounds.origin.x + bounds.size.width / 2.0;
            let cy = bounds.origin.y + bounds.size.height / 2.0;
            NSGraphicsContext::saveGraphicsState_class();
            objc2_app_kit::NSBezierPath::bezierPathWithRect(bounds).addClip();
            let transform = NSAffineTransform::transform();
            transform.translateXBy_yBy(cx, cy);
            transform.scaleBy(scale);
            transform.translateXBy_yBy(-cx, -cy);
            transform.concat();
            let _: () = unsafe { msg_send![super(self), drawRect: bounds] };
            NSGraphicsContext::restoreGraphicsState_class();
        }

        #[unsafe(method(setFrameSize:))]
        fn set_frame_size(&self, size: NSSize) {
            let _: () = unsafe { msg_send![super(self), setFrameSize: size] };
            NSView::setNeedsDisplay(self, true);
        }
    }
);

fn bezier(shape: &day_spec::Shape) -> Option<objc2::rc::Retained<objc2_app_kit::NSBezierPath>> {
    use day_spec::Shape;
    use objc2_app_kit::NSBezierPath;
    unsafe {
        Some(match shape {
            Shape::Rect(r) => NSBezierPath::bezierPathWithRect(ns_rect(*r)),
            Shape::RoundedRect(r, rad) => {
                NSBezierPath::bezierPathWithRoundedRect_xRadius_yRadius(ns_rect(*r), *rad, *rad)
            }
            Shape::Ellipse(r) => NSBezierPath::bezierPathWithOvalInRect(ns_rect(*r)),
            Shape::Arc {
                rect,
                start_deg,
                sweep_deg,
            } => {
                let p = NSBezierPath::new();
                let center = NSPoint::new(
                    rect.origin.x + rect.size.width / 2.0,
                    rect.origin.y + rect.size.height / 2.0,
                );
                let radius = rect.size.width.min(rect.size.height) / 2.0;
                // Flipped view: increasing angle is visually clockwise, matching the spec.
                p.appendBezierPathWithArcWithCenter_radius_startAngle_endAngle(
                    center,
                    radius,
                    *start_deg,
                    *start_deg + *sweep_deg,
                );
                p
            }
            Shape::Line(a, b) => {
                let p = NSBezierPath::new();
                p.moveToPoint(NSPoint::new(a.x, a.y));
                p.lineToPoint(NSPoint::new(b.x, b.y));
                p
            }
            Shape::Polygon(pts) => {
                if pts.len() < 2 {
                    return None;
                }
                let p = NSBezierPath::new();
                p.moveToPoint(NSPoint::new(pts[0].x, pts[0].y));
                for pt in &pts[1..] {
                    p.lineToPoint(NSPoint::new(pt.x, pt.y));
                }
                p.closePath();
                p
            }
            Shape::Path(path) => {
                use day_spec::PathSeg;
                if path.segs.is_empty() {
                    return None;
                }
                let p = NSBezierPath::new();
                // NSBezierPath's own quadratic API is macOS 14+, so quads are ELEVATED to
                // cubics with the standard formula (c1 = p0 + 2/3(c - p0), c2 = p1 + 2/3(c -
                // p1)), which is exact rather than an approximation.
                let mut cur = NSPoint::new(0.0, 0.0);
                for seg in &path.segs {
                    match seg {
                        PathSeg::Move(a) => {
                            cur = NSPoint::new(a.x, a.y);
                            p.moveToPoint(cur);
                        }
                        PathSeg::Line(a) => {
                            cur = NSPoint::new(a.x, a.y);
                            p.lineToPoint(cur);
                        }
                        PathSeg::Quad(c, a) => {
                            let (end, ctl) = (NSPoint::new(a.x, a.y), NSPoint::new(c.x, c.y));
                            let c1 = NSPoint::new(
                                cur.x + 2.0 / 3.0 * (ctl.x - cur.x),
                                cur.y + 2.0 / 3.0 * (ctl.y - cur.y),
                            );
                            let c2 = NSPoint::new(
                                end.x + 2.0 / 3.0 * (ctl.x - end.x),
                                end.y + 2.0 / 3.0 * (ctl.y - end.y),
                            );
                            p.curveToPoint_controlPoint1_controlPoint2(end, c1, c2);
                            cur = end;
                        }
                        PathSeg::Cubic(c1, c2, a) => {
                            cur = NSPoint::new(a.x, a.y);
                            p.curveToPoint_controlPoint1_controlPoint2(
                                cur,
                                NSPoint::new(c1.x, c1.y),
                                NSPoint::new(c2.x, c2.y),
                            );
                        }
                        PathSeg::Close => p.closePath(),
                    }
                }
                p.setWindingRule(match path.rule {
                    day_spec::FillRule::NonZero => objc2_app_kit::NSWindingRule::NonZero,
                    day_spec::FillRule::EvenOdd => objc2_app_kit::NSWindingRule::EvenOdd,
                });
                p
            }
        })
    }
}

// ---------------------------------------------------------------------------
// DayUndoManager — the native FRONT of the app's one undo stack (docs/model.md)
// ---------------------------------------------------------------------------

/// The mirrored [`day_spec::UndoState`]: what the stock Edit menu reads through the standard
/// `undo:`/`redo:` validation. The stack itself lives in day-model; this object only answers
/// questions and forwards invocations — two histories can never fork.
struct UndoIvars {
    state: std::cell::RefCell<day_spec::UndoState>,
}

define_class!(
    #[unsafe(super(objc2_foundation::NSUndoManager))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayUndoManager"]
    #[ivars = UndoIvars]
    struct DayUndoManager;

    /// Overrides of the questions AppKit's menu validation asks, answered from the mirrored
    /// state — and of the two verbs, forwarded as `Event::Undo` (enqueue-only, like every
    /// other event). Registration/grouping machinery of the superclass is never used.
    impl DayUndoManager {
        #[unsafe(method(canUndo))]
        fn can_undo(&self) -> bool {
            self.ivars().state.borrow().can_undo
        }

        #[unsafe(method(canRedo))]
        fn can_redo(&self) -> bool {
            self.ivars().state.borrow().can_redo
        }

        #[unsafe(method(undo))]
        fn do_undo(&self) {
            ffi_guard::contain((), || emit(WINDOW_NODE, Event::Undo { redo: false }))
        }

        #[unsafe(method(redo))]
        fn do_redo(&self) {
            ffi_guard::contain((), || emit(WINDOW_NODE, Event::Undo { redo: true }))
        }

        #[unsafe(method_id(undoMenuItemTitle))]
        fn undo_menu_item_title(&self) -> Retained<NSString> {
            // Route through the superclass's own title former, so "Undo" itself comes out in
            // the system language; the action label arrived already localized from the app.
            let label = self.ivars().state.borrow().undo_label.clone();
            unsafe { self.undoMenuTitleForUndoActionName(&NSString::from_str(&label)) }
        }

        #[unsafe(method_id(redoMenuItemTitle))]
        fn redo_menu_item_title(&self) -> Retained<NSString> {
            let label = self.ivars().state.borrow().redo_label.clone();
            unsafe { self.redoMenuTitleForUndoActionName(&NSString::from_str(&label)) }
        }
    }
);

fn undo_front(mtm: MainThreadMarker) -> Retained<DayUndoManager> {
    UNDO_FRONT.with(|u| {
        u.borrow_mut()
            .get_or_insert_with(|| {
                let this = DayUndoManager::alloc(mtm).set_ivars(UndoIvars {
                    state: std::cell::RefCell::new(day_spec::UndoState::default()),
                });
                unsafe { msg_send![super(this), init] }
            })
            .clone()
    })
}

// ---------------------------------------------------------------------------
// DayWinDelegate — resize + close + key tracking, per window
// ---------------------------------------------------------------------------

/// `node`: the day window-root id this delegate's window reports to. `None` = the PRIMARY
/// window — resize goes to `WINDOW_NODE` and close terminates the app; a secondary window
/// (docs/windows.md) reports to its own root and close tears down just that window.
struct WinIvars {
    node: Option<NodeId>,
    /// The tab group this window was opened in (`WindowTabbing::Group`/`Preferred`): the
    /// tab bar's "+" opens another window of the same group.
    group: Option<String>,
    /// The last display state reported (`WindowState::code`), so a resize that does not change
    /// the zoom state reports nothing.
    last_state: Cell<i32>,
}

define_class!(
    #[unsafe(super(NSObject))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayWinDelegate"]
    #[ivars = WinIvars]
    struct DayWinDelegate;

    unsafe impl NSObjectProtocol for DayWinDelegate {}

    /// The responder chain's last stop for the standard edit nav hosts: a focused text view
    /// answered `cut:`/`copy:`/`paste:` long before the window asked its delegate, so what
    /// arrives here is the app's to handle — the same precedence the undo manager route uses.
    impl DayWinDelegate {
        /// Edit ▸ Undo. The stock item's nil-target `undo:` finds no implementor among Day's
        /// plain views, so the delegate is where the chain lands — resolving through the
        /// acting manager keeps a focused field's typing undo ahead of the document stack.
        #[unsafe(method(undo:))]
        fn edit_undo(&self, _sender: Option<&objc2::runtime::AnyObject>) {
            ffi_guard::contain((), || {
                if let Some(m) = self.acting_undo_manager() {
                    unsafe { m.undo() };
                }
            });
        }

        /// Edit ▸ Redo.
        #[unsafe(method(redo:))]
        fn edit_redo(&self, _sender: Option<&objc2::runtime::AnyObject>) {
            ffi_guard::contain((), || {
                if let Some(m) = self.acting_undo_manager() {
                    unsafe { m.redo() };
                }
            });
        }

        #[unsafe(method(cut:))]
        fn edit_cut(&self, _sender: Option<&objc2::runtime::AnyObject>) {
            ffi_guard::contain((), || emit(WINDOW_NODE, Event::Edit(day_spec::EditOp::Cut)));
        }

        #[unsafe(method(copy:))]
        fn edit_copy(&self, _sender: Option<&objc2::runtime::AnyObject>) {
            ffi_guard::contain((), || emit(WINDOW_NODE, Event::Edit(day_spec::EditOp::Copy)));
        }

        #[unsafe(method(paste:))]
        fn edit_paste(&self, _sender: Option<&objc2::runtime::AnyObject>) {
            ffi_guard::contain((), || emit(WINDOW_NODE, Event::Edit(day_spec::EditOp::Paste)));
        }

        #[unsafe(method(selectAll:))]
        fn edit_select_all(&self, _sender: Option<&objc2::runtime::AnyObject>) {
            ffi_guard::contain((), || {
                emit(WINDOW_NODE, Event::Edit(day_spec::EditOp::SelectAll));
            });
        }

        /// AppKit's menu validation, the same machinery that greys Edit items for text views:
        /// the bridge state answers for cut/copy, and paste additionally requires the
        /// pasteboard to actually hold text.
        #[unsafe(method(validateMenuItem:))]
        fn validate_menu_item(&self, item: &NSMenuItem) -> bool {
            ffi_guard::contain(false, || {
                let state = EDIT_STATE.with(|s| s.get());
                match unsafe { item.action() } {
                    // The undo pair enables from the acting manager and takes its titles
                    // ("Undo Move Shape"), exactly as AppKit's own windows do.
                    Some(a) if a == sel!(undo:) => match self.acting_undo_manager() {
                        Some(m) => {
                            item.setTitle(unsafe { m.undoMenuItemTitle() }.as_ref());
                            unsafe { m.canUndo() }
                        }
                        None => false,
                    },
                    Some(a) if a == sel!(redo:) => match self.acting_undo_manager() {
                        Some(m) => {
                            item.setTitle(unsafe { m.redoMenuItemTitle() }.as_ref());
                            unsafe { m.canRedo() }
                        }
                        None => false,
                    },
                    Some(a) if a == sel!(selectAll:) => state.can_select_all,
                    Some(a) if a == sel!(cut:) => state.can_cut,
                    Some(a) if a == sel!(copy:) => state.can_copy,
                    Some(a) if a == sel!(paste:) => {
                        state.can_paste && {
                            let pb = unsafe { NSPasteboard::generalPasteboard() };
                            pb.types().is_some_and(|types| !types.is_empty())
                        }
                    }
                    _ => true,
                }
            })
        }
    }

    unsafe impl NSWindowDelegate for DayWinDelegate {
        #[unsafe(method(windowDidResize:))]
        fn window_did_resize(&self, notification: &NSNotification) {
            ffi_guard::contain((), || {
                if let Some(obj) = unsafe { notification.object() }
                    && let Ok(win) = obj.downcast::<NSWindow>()
                    && let Some(size) = pin_below_title_bar(&win)
                {
                    let target = self.ivars().node.unwrap_or(WINDOW_NODE);
                    emit(target, Event::WindowResized(size));
                }
                // Zooming is a resize with no notification of its own.
                self.report_state_of(notification);
            })
        }

        #[unsafe(method(windowShouldClose:))]
        fn window_should_close(&self, _window: &NSWindow) -> bool {
            ffi_guard::contain(false, || day_core::windows::native_close_requested(self.ivars().node.unwrap_or(WINDOW_NODE)))
        }

        #[unsafe(method(windowWillClose:))]
        fn window_will_close(&self, _notification: &NSNotification) {
            ffi_guard::contain((), || {
                match self.ivars().node {
                    // Secondary window: confirm the close to day-core, which tears the
                    // subtree down on a DEFERRED hop (never inside this AppKit close frame).
                    Some(node) => emit(node, Event::WindowClosed),
                    // Primary window: closing it quits, taking secondaries with it
                    // (docs/windows.md close policy), unless the app keeps running without a
                    // window (a status item, `KeepRunning::Always`): then it closes like any
                    // other window and day-core decides.
                    None if status_item::keeps_running() => emit(WINDOW_NODE, Event::WindowClosed),
                    None => {
                        let app = NSApplication::sharedApplication(self.mtm());
                        unsafe { app.terminate(None) };
                    }
                }
            })
        }

        #[unsafe(method_id(windowWillReturnUndoManager:))]
        fn window_will_return_undo_manager(
            &self,
            _window: &NSWindow,
        ) -> Option<Retained<objc2_foundation::NSUndoManager>> {
            // The responder chain already gave a focused text field its OWN manager before
            // asking the window — typing undo stays the field's, the model stack gets the
            // rest, exactly the precedence the plan's typing rule wants.
            ffi_guard::contain(None, || {
                UNDO_FRONT.with(|u| {
                    u.borrow()
                        .as_ref()
                        .map(|m| Retained::into_super(m.clone()))
                })
            })
        }

        #[unsafe(method(windowDidBecomeKey:))]
        fn window_did_become_key(&self, _notification: &NSNotification) {
            ffi_guard::contain((), || {
                if let Some(node) = self.ivars().node {
                    emit(node, Event::WindowFocused(true));
                }
            })
        }

        #[unsafe(method(windowDidResignKey:))]
        fn window_did_resign_key(&self, _notification: &NSNotification) {
            ffi_guard::contain((), || {
                if let Some(node) = self.ivars().node {
                    emit(node, Event::WindowFocused(false));
                }
            })
        }

        #[unsafe(method(windowDidMiniaturize:))]
        fn window_did_miniaturize(&self, notification: &NSNotification) {
            ffi_guard::contain((), || self.report_state_of(notification))
        }

        #[unsafe(method(windowDidDeminiaturize:))]
        fn window_did_deminiaturize(&self, notification: &NSNotification) {
            ffi_guard::contain((), || self.report_state_of(notification))
        }

        #[unsafe(method(windowDidEnterFullScreen:))]
        fn window_did_enter_full_screen(&self, notification: &NSNotification) {
            ffi_guard::contain((), || self.report_state_of(notification))
        }

        #[unsafe(method(windowDidExitFullScreen:))]
        fn window_did_exit_full_screen(&self, notification: &NSNotification) {
            ffi_guard::contain((), || self.report_state_of(notification))
        }
    }

    // The tab bar's "+" button walks the responder chain (window → delegate) for
    // `newWindowForTab:` — present only when the app registered a new-window builder
    // (otherwise automatic tabbing is off and no "+" exists).
    impl DayWinDelegate {
        #[unsafe(method(newWindowForTab:))]
        fn new_window_for_tab(&self, _sender: Option<&NSObject>) {
            ffi_guard::contain((), || {
                // A window in a tab group of its own gets another window of that group
                // (`register_new_window_for`); everything else gets File ▸ New Window's.
                let _ = match self.ivars().group.as_deref() {
                    Some(group) => day_core::windows::open_new_window_for_group(group),
                    None => day_core::windows::open_new_window(),
                };
            })
        }
    }
);

impl DayWinDelegate {
    fn report_state_of(&self, notification: &NSNotification) {
        if let Some(obj) = unsafe { notification.object() }
            && let Ok(win) = obj.downcast::<NSWindow>()
        {
            self.report_state(&win);
        }
    }
}

/// The day name for a key press, or `None` for every key the route does not carry — the
/// [`day_spec::KeyEvent`] names (docs/menus.md).
fn key_name(event: &objc2_app_kit::NSEvent) -> Option<&'static str> {
    match unsafe { event.keyCode() } {
        123 => Some("ArrowLeft"),
        124 => Some("ArrowRight"),
        125 => Some("ArrowDown"),
        126 => Some("ArrowUp"),
        // Not the delete keys. This backend draws a menu bar, so a Delete accelerator on a
        // menu item owns them (docs/menus.md) — and a focused piece that CLAIMS a key stops
        // that accelerator from ever seeing it, which is how a canvas ends up swallowing the
        // Delete its own Edit menu was going to act on.
        //
        // A digit, main row or keypad, named by what it types. Never under ⌘, ⌥ or ⌃: those
        // combinations are accelerators, and claiming one would starve the menu the same way.
        _ => {
            let held = NSEventModifierFlags::Command
                | NSEventModifierFlags::Option
                | NSEventModifierFlags::Control;
            if event.modifierFlags().intersects(held) {
                return None;
            }
            let typed = event.characters()?.to_string();
            let mut chars = typed.chars();
            match (chars.next(), chars.next()) {
                (Some(c), None) => day_spec::KeyEvent::digit_name(c),
                _ => None,
            }
        }
    }
}

/// AppKit's modifier flags as day's mask.
fn key_modifiers(f: NSEventModifierFlags) -> u8 {
    let mut modifiers = 0u8;
    if f.contains(NSEventModifierFlags::Shift) {
        modifiers |= day_spec::KeyEvent::SHIFT;
    }
    if f.contains(NSEventModifierFlags::Command) {
        modifiers |= day_spec::KeyEvent::PRIMARY;
    }
    if f.contains(NSEventModifierFlags::Option) {
        modifiers |= day_spec::KeyEvent::ALT;
    }
    modifiers
}

impl DayWinDelegate {
    /// The manager AppKit's own undo mechanics act on: ask the FIRST RESPONDER, whose
    /// `undoManager` walks the chain itself — a field editor answers with its typing
    /// history, everything else falls through to `windowWillReturnUndoManager` and lands on
    /// the app's front. Falls back to the front when no window is key yet.
    fn acting_undo_manager(&self) -> Option<Retained<objc2_foundation::NSUndoManager>> {
        let responder = NSApplication::sharedApplication(self.mtm())
            .keyWindow()
            .and_then(|w| w.firstResponder());
        responder
            .and_then(|r| unsafe { r.undoManager() })
            .or_else(|| {
                UNDO_FRONT.with(|u| u.borrow().as_ref().map(|m| Retained::into_super(m.clone())))
            })
    }
}

impl DayWinDelegate {
    fn new(mtm: MainThreadMarker, node: Option<NodeId>, group: Option<String>) -> Retained<Self> {
        let this = Self::alloc(mtm).set_ivars(WinIvars {
            node,
            group,
            last_state: Cell::new(day_spec::WindowState::Normal.code()),
        });
        unsafe { msg_send![super(this), init] }
    }

    /// Report the window's display state if it changed since the last report
    /// (docs/windows.md "Window properties"): to the window's root node, or `WINDOW_NODE` for the
    /// primary, the same routing as `WindowResized`.
    fn report_state(&self, window: &NSWindow) {
        let state = ns_window_state(window);
        if self.ivars().last_state.replace(state.code()) != state.code() {
            log::debug!("appkit: window state now {state:?}");
            let target = self.ivars().node.unwrap_or(WINDOW_NODE);
            emit(target, Event::WindowStateChanged(state));
        }
    }
}

/// What AppKit says a window is showing as: miniaturized wins (a fullscreen window can be
/// neither), then fullscreen (whose frame also reads as zoomed), then zoomed.
fn ns_window_state(window: &NSWindow) -> day_spec::WindowState {
    if window.isMiniaturized() {
        day_spec::WindowState::Minimized
    } else if window
        .styleMask()
        .contains(objc2_app_kit::NSWindowStyleMask::FullScreen)
    {
        day_spec::WindowState::Fullscreen
    } else if window.isZoomed() {
        day_spec::WindowState::Maximized
    } else {
        day_spec::WindowState::Normal
    }
}

/// Ask AppKit for `state`, undoing whatever the window is in first: fullscreen and miniaturized
/// have to be left before a window can zoom, and each is its own toggle.
fn set_ns_window_state(window: &NSWindow, state: day_spec::WindowState) {
    use day_spec::WindowState as S;
    let current = ns_window_state(window);
    if current == state {
        return;
    }
    unsafe {
        match current {
            S::Minimized => window.deminiaturize(None),
            // Leaving fullscreen animates; asking for another state in the same turn would be
            // dropped by AppKit mid-transition, so the request stops at leaving it. The state
            // signal reads back `Normal`, and a second request takes it from there.
            S::Fullscreen => {
                window.toggleFullScreen(None);
                return;
            }
            S::Maximized if state != S::Minimized => window.zoom(None),
            _ => {}
        }
        match state {
            S::Normal => {}
            S::Minimized => window.miniaturize(None),
            S::Maximized => {
                if !window.isZoomed() {
                    window.zoom(None)
                }
            }
            S::Fullscreen => window.toggleFullScreen(None),
        }
    }
}

// ---------------------------------------------------------------------------
// The backend
// ---------------------------------------------------------------------------

/// Renderers registered by external Day Piece crates (§8.2 layer 3 — linkme convenience).
#[distributed_slice]
pub static RENDERERS: [fn() -> Renderer<AppKit>];

/// A live secondary window (docs/windows.md). The delegate is RETAINED here —
/// `setDelegate:` holds it weakly, and unlike the primary's (kept alive because `run`
/// never returns) a secondary's delegate would die at the end of `open_window` otherwise.
struct SecondaryWin {
    window: Retained<NSWindow>,
    #[allow(dead_code)] // held for lifetime only; AppKit talks to it via the weak delegate ref
    delegate: Retained<DayWinDelegate>,
    content: Handle,
}

/// Deliver an explicitly registered Escape accelerator before a field editor swallows it.
/// The monitor is local to this process and removed with the backend.
struct MenuEscapeMonitor(Retained<objc2::runtime::AnyObject>);
impl Drop for MenuEscapeMonitor {
    fn drop(&mut self) {
        unsafe { NSEvent::removeMonitor(&self.0) };
    }
}

pub struct AppKit {
    menu_escape_monitor: Option<MenuEscapeMonitor>,
    sharing: Option<objc2::rc::Retained<objc2::runtime::AnyObject>>,

    mtm: MainThreadMarker,
    registry: Registry<AppKit>,
    window: Option<Retained<NSWindow>>,
    content: Option<Handle>,
    secondary: Vec<SecondaryWin>,
    app_name: String,
    /// Where the next secondary window's top-left goes (docs/windows.md). macOS staggers new
    /// windows rather than stacking them: `cascadeTopLeftFromPoint:` places the window and
    /// answers the point after it, so threading that answer through here is the whole
    /// mechanism. `None` until the primary exists — the cascade starts from its corner.
    cascade: Option<NSPoint>,
    /// One tracking-area owner per view carrying a `.cursor()` (docs/cursor.md), keyed by the
    /// view pointer. Removed when the cursor goes back to `Default`.
    cursors: HashMap<usize, (Retained<DayCursorOwner>, Retained<NSTrackingArea>)>,
}

impl AppKit {
    /// Rebuild a `text_field` as the other class (plain ⇄ secure) and put the replacement
    /// where the old view was: same text, look and place among its siblings, same focus and
    /// selection, and every view-keyed entry moved to it. day-core drops the old handle
    /// without a `release`, so nothing keyed by it may stay behind.
    fn swap_text_field(
        &mut self,
        h: &Handle,
        old: &NSTextField,
        node: NodeId,
        secure: bool,
    ) -> Retained<NSTextField> {
        let new = new_text_field(self.mtm, node, secure);
        let (old_key, new_key) = (ptr_of(h), ptr_of(&new));
        // Focus and selection first: reading them is only meaningful while the old field
        // still edits. `stringValue` below answers the field editor's live text.
        let window = h.window();
        let focused = window
            .as_deref()
            .is_some_and(|w| owns_first_responder(w, h));
        let selection = old.currentEditor().map(|e| e.selectedRange());
        unsafe {
            new.setStringValue(&old.stringValue());
            new.setPlaceholderString(old.placeholderString().as_deref());
            new.setEnabled(old.isEnabled());
            new.setFont(old.font().as_deref());
            new.setFrame(h.frame());
            new.setHidden(h.isHidden());
            new.setMenu(h.menu().as_deref());
            new.setToolTip(h.toolTip().as_deref());
            // Opacity and transform ride the layer (`set_opacity` / `set_transform`).
            if h.wantsLayer() {
                new.setWantsLayer(true);
                new.setAlphaValue(h.alphaValue());
                let from: *mut objc2::runtime::AnyObject = msg_send![h, layer];
                let to: *mut objc2::runtime::AnyObject = msg_send![&*new, layer];
                if !from.is_null() && !to.is_null() {
                    let t: CGAffineTransform = msg_send![from, affineTransform];
                    let _: () = msg_send![to, setAffineTransform: t];
                }
            }
            // Accessibility (`set_a11y`): only what was set explicitly, so the new class
            // keeps its own defaults (a secure field's role and hidden value) for the rest.
            if let Some(id) = h.accessibilityIdentifier().filter(|s| !s.is_empty()) {
                new.setAccessibilityIdentifier(Some(&id));
            }
            if let Some(label) = h.accessibilityLabel().filter(|s| !s.is_empty()) {
                new.setAccessibilityLabel(Some(&label));
            }
            if let Some(help) = h.accessibilityHelp().filter(|s| !s.is_empty()) {
                new.setAccessibilityHelp(Some(&help));
            }
            if !h.isAccessibilityElement() {
                new.setAccessibilityElement(false);
            }
        }
        // Recognizers and the cursor's tracking area move as objects, keeping their targets.
        for r in unsafe { h.gestureRecognizers() }.iter() {
            unsafe {
                h.removeGestureRecognizer(&r);
                new.addGestureRecognizer(&r);
            }
        }
        GESTURES.with(|m| {
            let mut m = m.borrow_mut();
            if let Some(targets) = m.remove(&old_key) {
                m.insert(new_key, targets);
            }
        });
        if let Some((owner, area)) = self.cursors.remove(&old_key) {
            unsafe {
                h.removeTrackingArea(&area);
                new.addTrackingArea(&area);
            }
            self.cursors.insert(new_key, (owner, area));
        }
        PAN_NODES.with(|t| rekey(t, old_key, new_key));
        HOVER_NODES.with(|t| rekey(t, old_key, new_key));
        KEY_NODES.with(|t| rekey(t, old_key, new_key));
        FOCUSABLE_NODES.with(|t| rekey(t, old_key, new_key));
        CTX_MENU_FNS.with(|t| rekey(t, old_key, new_key));
        transfer::moved(h, &new);
        // The old field goes silent before it leaves: ending its editing session would
        // otherwise report a focus loss for a node that keeps its focus.
        unsafe { old.setDelegate(None) };
        TARGETS.with(|m| {
            m.borrow_mut().remove(&old_key);
        });
        if let Some(parent) = unsafe { h.superview() } {
            unsafe {
                parent.addSubview_positioned_relativeTo(
                    &new,
                    objc2_app_kit::NSWindowOrderingMode::Above,
                    Some(h),
                );
                h.removeFromSuperview();
            }
        }
        if focused && let Some(window) = window {
            FIELD_SWAP.with(|s| s.set(true));
            let taken = window.makeFirstResponder(Some(&new));
            FIELD_SWAP.with(|s| s.set(false));
            // Taking focus selects the whole text; put back what was selected (the caret,
            // usually). Both classes count in UTF-16 units, so the range carries over.
            if taken && let Some(editor) = new.currentEditor() {
                let len = unsafe { new.stringValue() }.length();
                let range = selection
                    .filter(|r| r.location.saturating_add(r.length) <= len)
                    .unwrap_or(objc2_foundation::NSRange::new(len, 0));
                editor.setSelectedRange(range);
            }
        }
        // Whatever else was keyed by the old view goes with it.
        day_spec::sidetable::sweep(old_key);
        new
    }

    pub fn new() -> Self {
        let mtm =
            MainThreadMarker::new().expect("day-toolkit-appkit must start on the main thread");
        let mut registry = Registry::default();
        for f in RENDERERS {
            registry.register(f());
        }
        AppKit {
            menu_escape_monitor: None,
            mtm,
            registry,
            window: None,
            sharing: None,
            content: None,
            secondary: Vec::new(),
            app_name: "Day".into(),
            cascade: None,
            cursors: HashMap::new(),
        }
    }

    /// Public helper for external renderers.
    pub fn mtm(&self) -> MainThreadMarker {
        self.mtm
    }

    /// The `NSWindow` whose content container is `host`: a secondary window, or the primary.
    fn ns_window_for(&self, host: &Handle) -> Option<Retained<NSWindow>> {
        if let Some(w) = self
            .secondary
            .iter()
            .find(|w| ptr_of(&w.content) == ptr_of(host))
        {
            return Some(w.window.clone());
        }
        self.content
            .as_ref()
            .filter(|c| ptr_of(c) == ptr_of(host))
            .and(self.window.clone())
    }

    /// Build a Day window: titled + closable (Preferences kind drops resize/minimize and
    /// disallows tabbing per macOS convention; Normal windows share the `day.normal`
    /// tabbing group), a flipped content view, and a per-window delegate (`node`: `None` =
    /// primary). The window is NOT released-when-closed — Rust's `Retained` owns it, and
    /// the AppKit default would double-release under us on close.
    fn make_window(
        &self,
        options: &WindowOptions,
        prefs_style: bool,
        node: Option<NodeId>,
    ) -> (Retained<NSWindow>, Retained<DayWinDelegate>, Handle) {
        let mtm = self.mtm;
        let (title, size, min_size, tabbing) = (
            options.title.as_str(),
            options.size,
            options.min_size,
            &options.tabbing,
        );
        let content_rect =
            NSRect::new(NSPoint::new(0.0, 0.0), NSSize::new(size.width, size.height));
        // The kind decides the controls, the chrome decides the frame (docs/window-chrome.md).
        let style = window_chrome::style_mask(options, prefs_style);
        let window = window_chrome::alloc_window(
            mtm,
            content_rect,
            style,
            options.chrome == day_spec::WindowChrome::Frameless,
        );
        unsafe { window.setReleasedWhenClosed(false) };
        window.setTitle(&NSString::from_str(title));
        if let Some(min) = min_size {
            unsafe { window.setContentMinSize(NSSize::new(min.width, min.height)) };
        }
        if let Some(max) = options.max_size {
            unsafe { window.setContentMaxSize(NSSize::new(max.width, max.height)) };
        }
        use day_spec::WindowTabbing as T;
        use objc2_app_kit::NSWindowTabbingMode as M;
        let group = match tabbing {
            T::Group(g) | T::Preferred(g) => Some(g.clone()),
            T::Automatic | T::Disallowed => None,
        };
        match tabbing {
            _ if prefs_style => window.setTabbingMode(M::Disallowed),
            T::Disallowed => window.setTabbingMode(M::Disallowed),
            // Same-kind Day windows group as native tabs (System Settings "prefer tabs",
            // View ▸ Show Tab Bar, Merge All Windows) — meaningful once a second Normal
            // window can exist; inert while automatic tabbing is globally off (see `run`).
            T::Automatic => unsafe {
                window.setTabbingIdentifier(&NSString::from_str("day.normal"))
            },
            T::Group(g) => unsafe { window.setTabbingIdentifier(&NSString::from_str(g)) },
            T::Preferred(g) => {
                unsafe { window.setTabbingIdentifier(&NSString::from_str(g)) };
                window.setTabbingMode(M::Preferred);
            }
        }
        if group.is_some() {
            // A named group is the app asking for tabs, so the class-wide switch `run` may have
            // turned off (no New Window builder) goes back on for it.
            unsafe { NSWindow::setAllowsAutomaticWindowTabbing(true, mtm) };
        }
        let delegate = DayWinDelegate::new(mtm, node, group);
        window.setDelegate(Some(ProtocolObject::from_ref(&*delegate)));
        let content = view_of(DayFlipped::new(mtm));
        window.setContentView(Some(&content));
        window_chrome::apply(&window, &content, options);
        // Tab / Shift-Tab (docs/focus.md). AppKit does NOT derive the key view loop from the view
        // hierarchy: `nextKeyView` is nil on a programmatically built window and the loop stays
        // empty, so Tab moves focus OUT of a text field and onto nothing — measured on the
        // showcase's Focus page, where three Tabs in a row left every field unfocused. Every other
        // Day backend gets traversal from its widget order for free; this is the one that has to
        // ask. Autorecalculation rather than a call at the end of each layout because Day's tree
        // is reactive: fields appear, move, and vanish between passes, and AppKit rebuilding the
        // loop on hierarchy changes is the same rule expressed once.
        window.setAutorecalculatesKeyViewLoop(true);
        (window, delegate, content)
    }
}

impl Default for AppKit {
    fn default() -> Self {
        Self::new()
    }
}

fn view_of<T: AsRef<NSView>>(x: Retained<T>) -> Handle {
    Retained::from(x.as_ref())
}

fn nscolor(c: day_spec::Color) -> Retained<NSColor> {
    unsafe { NSColor::colorWithSRGBRed_green_blue_alpha(c.r, c.g, c.b, c.a) }
}

/// The macOS native semantic text style for a logical [`Font`] (`None` for a custom size).
/// `NSFont.preferredFont(forTextStyle:)` gives the OS's own typography, tracking the system settings.
fn ns_text_style(f: Font) -> Option<&'static objc2_app_kit::NSFontTextStyle> {
    use objc2_app_kit::*;
    unsafe {
        Some(match f {
            Font::LargeTitle => NSFontTextStyleLargeTitle,
            Font::Title => NSFontTextStyleTitle1,
            Font::Title2 => NSFontTextStyleTitle2,
            Font::Title3 => NSFontTextStyleTitle3,
            Font::Headline => NSFontTextStyleHeadline,
            Font::Subheadline => NSFontTextStyleSubheadline,
            Font::Body => NSFontTextStyleBody,
            Font::Callout => NSFontTextStyleCallout,
            Font::Footnote => NSFontTextStyleFootnote,
            Font::Caption => NSFontTextStyleCaption1,
            Font::Caption2 => NSFontTextStyleCaption2,
            Font::System(_) | Font::Custom(..) => return None,
        })
    }
}

fn ns_weight(w: day_spec::FontWeight) -> objc2_app_kit::NSFontWeight {
    use day_spec::FontWeight as W;
    use objc2_app_kit::*;
    unsafe {
        match w {
            W::UltraLight => NSFontWeightUltraLight,
            W::Thin => NSFontWeightThin,
            W::Light => NSFontWeightLight,
            W::Regular => NSFontWeightRegular,
            W::Medium => NSFontWeightMedium,
            W::Semibold => NSFontWeightSemibold,
            W::Bold => NSFontWeightBold,
            W::Heavy => NSFontWeightHeavy,
            W::Black => NSFontWeightBlack,
        }
    }
}

/// The `NSFontManager` weight rung (0 … 15) for a Day weight — the scale
/// `fontWithFamily:traits:weight:size:` matches faces on (5 = regular, 9 = bold).
fn nsfm_weight(w: day_spec::FontWeight) -> isize {
    use day_spec::FontWeight as W;
    match w {
        W::UltraLight => 2,
        W::Thin => 3,
        W::Light => 4,
        W::Regular => 5,
        W::Medium => 6,
        W::Semibold => 8,
        W::Bold => 9,
        W::Heavy => 10,
        W::Black => 12,
    }
}

/// Resolve a canvas font (docs/fonts.md) at an absolute size: the system face for `None`,
/// else the family's nearest member through `NSFontManager` (which also synthesizes a bold or
/// italic the family lacks), falling back to a PostScript/full-name lookup (a bundled font
/// registered in `run`) and then to the system font with one warning.
fn canvas_nsfont(size: f64, font: &day_spec::CanvasFont) -> Retained<NSFont> {
    use objc2_app_kit::*;
    let weight = font.weight.unwrap_or(day_spec::FontWeight::Regular);
    let mtm = objc2::MainThreadMarker::new().expect("canvas draws on the main thread");
    let manager = unsafe { NSFontManager::sharedFontManager(mtm) };
    let mut traits = NSFontTraitMask::empty();
    if weight >= day_spec::FontWeight::Semibold {
        traits |= NSFontTraitMask::BoldFontMask;
    }
    if font.italic {
        traits |= NSFontTraitMask::ItalicFontMask;
    }
    let Some(family) = font.family.as_deref() else {
        let base = unsafe { NSFont::systemFontOfSize_weight(size, ns_weight(weight)) };
        return if font.italic {
            unsafe { manager.convertFont_toHaveTrait(&base, NSFontTraitMask::ItalicFontMask) }
        } else {
            base
        };
    };
    let ns_family = NSString::from_str(family);
    if let Some(f) = unsafe {
        manager.fontWithFamily_traits_weight_size(&ns_family, traits, nsfm_weight(weight), size)
    } {
        return f;
    }
    if let Some(f) = unsafe { NSFont::fontWithName_size(&ns_family, size) } {
        return if traits.is_empty() {
            f
        } else {
            unsafe { manager.convertFont_toHaveTrait(&f, traits) }
        };
    }
    log::warn!("unknown font family {family:?} — drawing canvas text in the system font");
    unsafe { NSFont::systemFontOfSize_weight(size, ns_weight(weight)) }
}

/// The attribute dictionary canvas text draws and measures with (the same one, so
/// `measure_text` and `replay` agree on the line box).
fn canvas_text_attrs(
    font: &NSFont,
    color: day_spec::Color,
) -> Retained<objc2_foundation::NSDictionary<NSString, objc2::runtime::AnyObject>> {
    let col = nscolor(color);
    // SAFETY: both are AppKit's own attribute-name constants, valid for the process lifetime.
    let keys: [&NSString; 2] = unsafe {
        [
            objc2_app_kit::NSFontAttributeName,
            objc2_app_kit::NSForegroundColorAttributeName,
        ]
    };
    let objs: [&objc2::runtime::AnyObject; 2] = [
        font as &objc2::runtime::AnyObject,
        col.as_ref() as &objc2::runtime::AnyObject,
    ];
    objc2_foundation::NSDictionary::from_slices::<NSString>(&keys, &objs)
}

/// Resolve a [`FontSpec`] to a native `NSFont`: a semantic style via `preferredFont(forTextStyle:)`
/// (or a custom system size), then an optional weight override (at the same size) and italic trait.
fn nsfont(spec: day_spec::FontSpec) -> Retained<NSFont> {
    use objc2_app_kit::*;
    let base: Retained<NSFont> = match spec.style {
        Font::System(pt) => {
            let w = spec
                .weight
                .map(ns_weight)
                .unwrap_or(unsafe { NSFontWeightRegular });
            unsafe { NSFont::systemFontOfSize_weight(pt, w) }
        }
        // A bundled family (§18.4), registered with CoreText in run(). fontWithName resolves
        // family, full, and PostScript names. A weight override maps to the bold trait (the
        // family decides what it can supply); unknown families fall back to the system font.
        Font::Custom(name, pt) => {
            match unsafe { NSFont::fontWithName_size(&NSString::from_str(name), pt) } {
                Some(f) => {
                    if spec
                        .weight
                        .is_some_and(|w| w >= day_spec::FontWeight::Semibold)
                    {
                        let mtm = objc2::MainThreadMarker::new()
                            .expect("labels realize on the main thread");
                        unsafe {
                            NSFontManager::sharedFontManager(mtm)
                                .convertFont_toHaveTrait(&f, NSFontTraitMask::BoldFontMask)
                        }
                    } else {
                        f
                    }
                }
                None => {
                    log::warn!(
                        "unknown font family {name:?} — falling back to the system font \
                         (is the file in the project's fonts/ directory?)"
                    );
                    let w = spec
                        .weight
                        .map(ns_weight)
                        .unwrap_or(unsafe { NSFontWeightRegular });
                    unsafe { NSFont::systemFontOfSize_weight(pt, w) }
                }
            }
        }
        style => {
            // Invariant: System/Custom matched above, so only the semantic styles — which
            // `ns_text_style` maps exhaustively — can reach this arm.
            let ts = ns_text_style(style).expect("semantic style");
            let opts = objc2_foundation::NSDictionary::new();
            let f = unsafe { NSFont::preferredFontForTextStyle_options(ts, &opts) };
            match spec.weight {
                // A weight override keeps the style's (system-resolved) size but re-picks the weight.
                Some(w) => unsafe { NSFont::systemFontOfSize_weight(f.pointSize(), ns_weight(w)) },
                None => f,
            }
        }
    };
    // Tabular figures. Cocoa exposes them as a whole font, not a trait, so this re-picks the
    // system font at the resolved size/weight rather than converting — which is why it only
    // applies to the system styles: a bundled `Font::Custom` family keeps its own figures (asking
    // for the system's monospaced-digit face there would silently swap the typeface).
    let base = if spec.tabular && !matches!(spec.style, Font::Custom(..)) {
        let w = spec
            .weight
            .map(ns_weight)
            .unwrap_or(unsafe { NSFontWeightRegular });
        unsafe { NSFont::monospacedDigitSystemFontOfSize_weight(base.pointSize(), w) }
    } else {
        base
    };
    // Monospace, by the same rule as tabular: Cocoa ships it as a whole font, so this re-picks
    // the system's monospaced face at the resolved size and weight. Skipped for a bundled family
    // — swapping a chosen typeface for the system mono would be a surprise, not a refinement.
    let base = if spec.monospace && !matches!(spec.style, Font::Custom(..)) {
        let w = spec
            .weight
            .map(ns_weight)
            .unwrap_or(unsafe { NSFontWeightRegular });
        unsafe { NSFont::monospacedSystemFontOfSize_weight(base.pointSize(), w) }
    } else {
        base
    };
    // Relative size (`FontSpec::scale`). Applied last, over whatever face the traits above
    // settled on, and through `convertFont_toSize` so a bundled family keeps its typeface —
    // re-picking the system font here would undo the Custom/monospace/tabular work above.
    let base = if spec.scale != 1.0 {
        let mtm = objc2::MainThreadMarker::new().expect("labels realize on the main thread");
        let pts = spec.resolved_points(base.pointSize());
        unsafe { NSFontManager::sharedFontManager(mtm).convertFont_toSize(&base, pts) }
    } else {
        base
    };
    if spec.italic {
        let mtm = objc2::MainThreadMarker::new().expect("labels realize on the main thread");
        unsafe {
            NSFontManager::sharedFontManager(mtm)
                .convertFont_toHaveTrait(&base, NSFontTraitMask::ItalicFontMask)
        }
    } else {
        base
    }
}

/// Build an `NSAttributedString` for a label's text + runs (docs/text-runs.md).
///
/// Ranges arrive as BYTE offsets into a Rust `str`; `NSAttributedString` indexes UTF-16. The
/// conversion is per-run rather than a blanket assumption: any text with an emoji or a CJK
/// character makes the two disagree, and an off-by-N range there styles the wrong words.
/// Stamp a paragraph alignment across a label's whole attributed string.
///
/// Separate from `setAlignment:` because the two live in different places: the cell has a
/// paragraph style, the attributed string carries its own, and the string's wins.
fn set_paragraph_alignment(tf: &NSTextField, align: objc2_app_kit::NSTextAlignment) {
    use objc2_foundation::{NSMutableAttributedString, NSRange};
    unsafe {
        let cur = tf.attributedStringValue();
        let m = NSMutableAttributedString::initWithAttributedString(
            NSMutableAttributedString::alloc(),
            &cur,
        );
        let style = objc2_app_kit::NSMutableParagraphStyle::new();
        style.setAlignment(align);
        // Wrapping is what makes alignment observable at all, and the default paragraph style a
        // fresh NSMutableParagraphStyle carries would otherwise reset it to clipping.
        style.setLineBreakMode(objc2_app_kit::NSLineBreakMode::ByWordWrapping);
        m.addAttribute_value_range(
            objc2_app_kit::NSParagraphStyleAttributeName,
            &style,
            NSRange::new(0, cur.length()),
        );
        tf.setAttributedStringValue(&m);
    }
}

fn attributed_label(
    text: &str,
    base_font: &NSFont,
    color: Option<day_spec::Color>,
    role: day_spec::props::TextRole,
    runs: &[day_spec::TextRun],
) -> Retained<objc2_foundation::NSAttributedString> {
    use objc2_foundation::{NSMutableAttributedString, NSRange};
    let ns = NSString::from_str(text);
    let s = unsafe {
        NSMutableAttributedString::initWithString(NSMutableAttributedString::alloc(), &ns)
    };
    let whole = NSRange::new(0, ns.length());
    unsafe {
        s.addAttribute_value_range(objc2_app_kit::NSFontAttributeName, base_font, whole);
        // Always a foreground: an attributed range with no color attribute draws in black,
        // which is unreadable in dark mode. `labelColor` is the adaptive default the field
        // would have used on its own.
        // An explicit color wins; otherwise the ROLE picks which adaptive system color to use.
        // Both are adaptive, which is the point of asking for a role instead of a grey: the
        // secondary label is legible against either appearance's background, and a literal one
        // cannot be.
        let fg = color.map(nscolor).unwrap_or_else(|| match role {
            day_spec::props::TextRole::Secondary => objc2_app_kit::NSColor::secondaryLabelColor(),
            day_spec::props::TextRole::Primary => objc2_app_kit::NSColor::labelColor(),
        });
        s.addAttribute_value_range(objc2_app_kit::NSForegroundColorAttributeName, &fg, whole);
    }
    for r in runs {
        let Some(range) = utf16_range(text, &r.range) else {
            continue;
        };
        unsafe {
            s.addAttribute_value_range(objc2_app_kit::NSFontAttributeName, &nsfont(r.font), range);
            if let Some(c) = r.color {
                s.addAttribute_value_range(
                    objc2_app_kit::NSForegroundColorAttributeName,
                    &nscolor(c),
                    range,
                );
            }
            if let Some(c) = r.background {
                s.addAttribute_value_range(
                    objc2_app_kit::NSBackgroundColorAttributeName,
                    &nscolor(c),
                    range,
                );
            }
            if r.underline.is_on() {
                let style = objc2_foundation::NSNumber::new_i64(ns_underline(r.underline));
                s.addAttribute_value_range(
                    objc2_app_kit::NSUnderlineStyleAttributeName,
                    &style,
                    range,
                );
            }
            if r.strikethrough {
                let one = objc2_foundation::NSNumber::new_i64(1);
                s.addAttribute_value_range(
                    objc2_app_kit::NSStrikethroughStyleAttributeName,
                    &one,
                    range,
                );
            }
            if let Some(url) = r.link.as_deref() {
                // The native field editor hit-tests this attribute; DayLabel handles its
                // delegate callback and reports LinkActivated without opening the URL itself.
                let value = NSString::from_str(url);
                s.addAttribute_value_range(objc2_app_kit::NSLinkAttributeName, &value, range);
            }
        }
    }
    s.into_super()
}

/// [`Underline`](day_spec::Underline) as an `NSUnderlineStyle` bitmask: the line style in the low
/// byte, the pattern in the second. `Dotted`/`Wavy` are patterns over a single line, which is
/// exactly how AppKit spells them.
fn ns_underline(u: day_spec::Underline) -> i64 {
    use day_spec::Underline as U;
    match u {
        U::None => 0,
        U::Single => 0x01,
        U::Double => 0x09,
        U::Dotted => 0x01 | 0x0100,
        U::Wavy => 0x01 | 0x0400,
    }
}

/// A byte range in `text` as an `NSRange` in UTF-16 units, or `None` if it is out of bounds.
fn utf16_range(text: &str, r: &std::ops::Range<usize>) -> Option<objc2_foundation::NSRange> {
    let start = text.get(..r.start)?.encode_utf16().count();
    let len = text.get(r.clone())?.encode_utf16().count();
    Some(objc2_foundation::NSRange::new(start, len))
}

/// Register every bundled font file (the project's `fonts/`, staged per §18.4) with CoreText for
/// this process, so `Font::Custom` family names resolve through `NSFont::fontWithName`. Called
/// once from `run()`; a failure (already registered on a hot relaunch, or a broken file) only
/// means that family won't resolve, so it logs and moves on.
fn register_bundled_fonts() {
    // CFURLRef is toll-free bridged with NSURL, so the NSURL pointer passes straight through.
    #[link(name = "CoreText", kind = "framework")]
    unsafe extern "C" {
        fn CTFontManagerRegisterFontsForURL(
            font_url: *const std::ffi::c_void,
            scope: u32, // kCTFontManagerScopeProcess = 1
            error: *mut *const std::ffi::c_void,
        ) -> bool;
    }
    for path in day_spec::fonts::bundled_fonts() {
        let url = unsafe {
            objc2_foundation::NSURL::fileURLWithPath(&NSString::from_str(&path.to_string_lossy()))
        };
        let ok = unsafe {
            CTFontManagerRegisterFontsForURL(
                Retained::as_ptr(&url) as *const std::ffi::c_void,
                1,
                std::ptr::null_mut(),
            )
        };
        if !ok {
            log::warn!("could not register bundled font {}", path.display());
        }
    }
}

/// `TextAlign` → AppKit. `Natural` rather than `Left` for the leading case: it follows the
/// writing direction, so an RTL locale aligns right without the app asking (docs/localization.md).
fn nstextalign(a: day_spec::props::TextAlign) -> objc2_app_kit::NSTextAlignment {
    match a {
        day_spec::props::TextAlign::Leading => objc2_app_kit::NSTextAlignment::Natural,
        day_spec::props::TextAlign::Center => objc2_app_kit::NSTextAlignment::Center,
        day_spec::props::TextAlign::Trailing => objc2_app_kit::NSTextAlignment::Right,
    }
}

fn configure_label_cell(tf: &NSTextField) {
    if let Some(cell) = unsafe { tf.cell() } {
        unsafe {
            cell.setWraps(true);
            cell.setUsesSingleLineMode(false);
            cell.setLineBreakMode(NSLineBreakMode::ByWordWrapping);
        }
    }
}

/// If `parent` is a scroll view, children go into its (flipped) document view.
fn content_of(parent: &Handle) -> Retained<NSView> {
    if let Some(sv) = parent.downcast_ref::<NSScrollView>()
        && let Some(doc) = unsafe { sv.documentView() }
    {
        return doc;
    }
    parent.clone()
}

/// Run `body` (which sets animatable properties on a layer-backed view) inside an
/// `NSAnimationContext` group so AppKit interpolates the change on the render server with the
/// curve's timing function, or immediately when `anim` is `None` (§8.4). `allowsImplicitAnimation`
/// makes direct property changes on layer-backed views animate. A spring maps to an overshooting
/// cubic-bezier timing function (a visible bounce without an explicit `CASpringAnimation`).
fn with_appkit_anim(anim: Option<&AnimSpec>, body: impl FnOnce()) {
    let Some(a) = anim else {
        body();
        return;
    };
    let (dur, timing) = appkit_timing(a);
    unsafe {
        NSAnimationContext::beginGrouping();
        let ctx = NSAnimationContext::currentContext();
        ctx.setDuration(dur);
        ctx.setTimingFunction(Some(&timing));
        ctx.setAllowsImplicitAnimation(true);
        body();
        NSAnimationContext::endGrouping();
    }
}

/// The `(duration_secs, timing function)` for a curve. Springs render as an overshooting bezier
/// (control point y > 1) whose overshoot grows as damping falls, over a response-derived duration.
fn appkit_timing(a: &AnimSpec) -> (f64, Retained<CAMediaTimingFunction>) {
    unsafe {
        let named = |n| {
            (
                a.duration_secs().max(0.01),
                CAMediaTimingFunction::functionWithName(n),
            )
        };
        match a.curve {
            Curve::Linear => named(kCAMediaTimingFunctionLinear),
            Curve::EaseIn => named(kCAMediaTimingFunctionEaseIn),
            Curve::EaseOut => named(kCAMediaTimingFunctionEaseOut),
            Curve::EaseInOut => named(kCAMediaTimingFunctionEaseInEaseOut),
            Curve::Spring { damping, .. } => {
                // Overshoot bezier over exactly the specified duration (authoritative timing).
                let overshoot = 1.0 + (1.0 - damping.clamp(0.0, 1.0)) as f32 * 0.55;
                (
                    a.duration_secs().max(0.05),
                    CAMediaTimingFunction::functionWithControlPoints(0.34, overshoot, 0.5, 1.0),
                )
            }
        }
    }
}

/// Warn once per kind that this backend has no registered renderer for `kind`, before falling back to
/// a visible placeholder. A missing renderer usually means the piece's `appkit` feature wasn't enabled
/// (Tier A.2 derives it automatically under `day build`; a bare `cargo` build may miss it). Deduped
/// per kind so a placeholder rendered every frame doesn't spam the log.
fn warn_missing_renderer(kind: PieceKind) {
    day_spec::placeholder::report(kind, "appkit");
}

/// The visible-but-harmless placeholder label the unregistered-kind arm renders. Shared with
/// the [`props_of`] mismatch fallback, so a wrong props payload degrades to the same surface
/// (the warning is already reported by `props_of` itself).
pub(crate) fn placeholder_view(mtm: MainThreadMarker, kind: PieceKind) -> Handle {
    view_of(unsafe {
        NSTextField::labelWithString(&NSString::from_str(&format!("⟨{kind}⟩")), mtm)
    })
}

impl Toolkit for AppKit {
    /// Settled unless a toolbar edit is still painting (toolbar.rs `CHROME_SETTLE`); AppKit's
    /// own transitions (sheets, nav pushes) complete within the turn that starts them.
    fn ui_idle(&mut self) -> bool {
        toolbar::chrome_settled()
    }

    type Handle = Handle;

    fn dark_mode(&mut self) -> bool {
        // The app's EFFECTIVE appearance — one source for the system setting, the DAY_THEME
        // launch force (applied as an NSApp override at startup), and a set_appearance call.
        let app = NSApplication::sharedApplication(self.mtm());
        app.effectiveAppearance()
            .name()
            .to_string()
            .contains("Dark")
    }

    /// System Settings › Accessibility › Display › "Reduce motion", as NSWorkspace reports it
    /// (docs/accessibility.md). `install_reduce_motion_observer` re-reads it on a flip.
    fn reduce_motion(&mut self) -> bool {
        objc2_app_kit::NSWorkspace::sharedWorkspace().accessibilityDisplayShouldReduceMotion()
    }

    /// macOS is the one platform whose badge takes arbitrary text: `NSDockTile.badgeLabel` is a
    /// `String`, so `Text` renders literally and a count is just its decimal form. A nil label
    /// clears it (docs/badge.md).
    fn set_app_badge(&mut self, badge: &day_spec::AppBadge) {
        use day_spec::AppBadge;
        let label = match badge {
            AppBadge::None => None,
            // Zero clears, matching the platform convention the doc states.
            AppBadge::Count(0) => None,
            AppBadge::Count(n) => Some(n.to_string()),
            AppBadge::Text(t) if t.is_empty() => None,
            AppBadge::Text(t) => Some(t.clone()),
            // No dedicated dot on the Dock; the smallest honest mark is a single bullet.
            AppBadge::Dot => Some("\u{2022}".to_string()),
        };
        let tile = NSApplication::sharedApplication(self.mtm()).dockTile();
        let ns = label.map(|l| objc2_foundation::NSString::from_str(&l));
        unsafe { tile.setBadgeLabel(ns.as_deref()) };
        tile.display();
    }

    fn set_appearance(&mut self, dark: Option<bool>) {
        let app = NSApplication::sharedApplication(self.mtm());
        let appearance = dark.and_then(|d| {
            objc2_app_kit::NSAppearance::appearanceNamed(unsafe {
                if d {
                    objc2_app_kit::NSAppearanceNameDarkAqua
                } else {
                    objc2_app_kit::NSAppearanceNameAqua
                }
            })
        });
        // `None` clears the override — back to the system appearance.
        unsafe { app.setAppearance(appearance.as_deref()) };
    }

    fn attach_refresh(&mut self, handle: &Self::Handle, host: NodeId) {
        controls::refresh_gesture::attach(handle, host);
    }

    fn set_presented(&mut self, handle: &Self::Handle, visible: bool) {
        unsafe {
            handle.setHidden(!visible);
        }
    }

    fn capability(&self, cap: Cap) -> Support {
        match cap {
            Cap::SearchField => Support::Native,
            Cap::ComboBox => Support::Native,
            Cap::Stepper => Support::Native,
            Cap::DateTimePicker => Support::Native,
            Cap::ColorPicker => Support::Native,
            Cap::PullRefresh => Support::Emulated,
            Cap::Pager => Support::Emulated,
            Cap::PullRefreshGesture => Support::Emulated,
            // A tracking-area owner sets an `NSCursor` per view (docs/cursor.md). Wait, progress,
            // help, and move take the arrow — AppKit draws no such shapes — and the zoom and
            // diagonal-resize cursors need macOS 15.
            Cap::Cursor => Support::Native,
            // `NSFontManager` enumerates every family and member (docs/fonts.md).
            Cap::FontList => Support::Native,
            // An image-and-text table cell's content (docs/list.md "List items").
            Cap::ListItem => Support::Native,
            // ImageIO behind `NSBitmapImageRep` reads every container macOS knows and writes
            // back PNG/JPEG/TIFF/BMP/GIF, and carries the container's own metadata dictionary
            // (docs/images.md).
            Cap::ImageDecode | Cap::ImageEncode | Cap::ImageProperties => Support::Native,
            // Canvas export (docs/canvas.md "Exporting"): the canvas painter replayed into a
            // CGBitmapContext, or a CGPDFContext that keeps shapes and text vector.
            Cap::CanvasBitmap | Cap::CanvasPdf => Support::Native,
            // The announcement-requested notification, posted from the primary window
            // (docs/accessibility.md).
            Cap::Announce => Support::Native,
            // `NSWorkspace.accessibilityDisplayShouldReduceMotion`, re-read when the workspace
            // posts its display-options change (docs/accessibility.md).
            Cap::ReduceMotion => Support::Native,
            Cap::Snapshot
            | Cap::NativeSymbols
            // The rows as chrome: `Rail` is the same source list pinned narrow, `Tabs` an
            // NSSegmentedControl docked below the pages. AppKit has no app-level tab bar —
            // NSTabView owns its own page content, the opposite of Day's model — so the bar
            // is composed from the control a Mac uses for a one-of-N switch this size.
            //
            // `Cap::NavTabsAdaptive` is deliberately NOT here: a Mac app may PIN a tab bar, but
            // a narrow Mac window hides its sidebar and pushes rather than growing one. It falls
            // through to the `Unsupported` arm below.
            | Cap::NavTabs
            | Cap::NavSplit
            // Both presentations are the same NSSplitViewController — a stack is that split with
            // its sidebar item collapsed — so re-presenting is a collapse plus one `addSubview`
            // that re-parents the sidebar page (docs/size-classes.md).
            | Cap::NavRepresent
            // A REAL `contentList` NSSplitViewItem between sidebar and detail; the pane
            // persists through every presentation (docs/navigation.md).
            | Cap::NavContentList
            | Cap::Dialogs
            | Cap::FileDialogs
            // NSOpenPanel with `canChooseDirectories` (docs/files.md).
            | Cap::FolderDialog
            | Cap::Animation
            // NSTextView natively honors all three text-area attributes.
            | Cap::TextEditable
            | Cap::TextSelectable
            | Cap::TextSpellCheck
            // NSTableView's own drag pipeline, with the `.gap` placeholder (docs/list.md), in
            // lists and in the source-list sidebar itself (docs/navigation.md).
            | Cap::NavReorder | Cap::ListReorder
            // NSTableView's view-based reuse queue (`makeViewWithIdentifier`) hands Day's cells
            // back for new rows; `didRemoveRowView` recycles them (docs/list.md).
            | Cap::ListRecycling
            // NSTableView row actions: reveal-as-you-swipe buttons with the native full-slide
            // activation (docs/list.md).
            | Cap::ListSwipeActions
            // NSTableView group rows with `floatsGroupRows` (docs/list.md "Sections").
            | Cap::ListSections
            // NSOutlineView hosts Day-built rows natively, drag-reparent included
            // (docs/tree.md).
            | Cap::Tree
            | Cap::TreeSections
            | Cap::TreeMove
            // Real NSWindows with native tabbing + the Windows menu (docs/windows.md).
            | Cap::MultiWindow
            // `miniaturize:` / `zoom:` / `toggleFullScreen:`, reported back through the window
            // delegate's notifications (docs/windows.md "Window properties").
            | Cap::WindowStates
            | Cap::WindowFullscreen
            // `NSWindowSharingNone`: captures, recordings and screen sharing see an empty window.
            | Cap::ContentProtection
            // Per-window `tabbingIdentifier` / `tabbingMode`, with the "+" opening the group's
            // own builder.
            | Cap::WindowTabbing
            // `applicationDockMenu:` on the app delegate (docs/menus.md).
            | Cap::DockMenu
            // Borderless windows that still take key, a transparent title bar over the
            // content, a clear window background, and `NSVisualEffectView` materials behind the
            // content (docs/window-chrome.md).
            | Cap::FramelessWindow
            | Cap::OverlayTitleBar
            | Cap::TransparentWindow
            | Cap::WindowMaterial
            // `performWindowDragWithEvent:` from a press on the region's own background.
            | Cap::DragRegion
            // `NSStatusItem`s in the menu bar, a progress bar drawn on the Dock tile, and the
            // accessory activation policy (docs/status-item.md).
            | Cap::StatusItem
            | Cap::AppProgress
            | Cap::DockVisibility
            // Frame, limits, level, Spaces, style-mask controls, per-window appearance, Dock
            // bounces, and `NSScreen` (docs/windows.md "Window properties").
            | Cap::WindowGeometry
            | Cap::WindowPosition
            | Cap::WindowLevel
            | Cap::WindowAppearance
            | Cap::RequestAttention
            | Cap::Monitors
            // Run-time shortcuts appear in the Dock menu beside the declared ones.
            | Cap::DynamicShortcuts
            // A real NSToolbar in the title bar (docs/toolbars.md).
            | Cap::Toolbar
            // The bar holds a native search field (docs/search.md).
            | Cap::ToolbarSearch
            | Cap::AppMenu
            // NSDockTile.badgeLabel is an arbitrary String, so all three payloads render — the
            // only backend where Text is real (docs/badge.md).
            | Cap::AppBadgeCount
            | Cap::AppBadgeText
            // NSUndoManager fronted by DayUndoManager: the stock Edit menu retitles and
            // enables itself, ⌘Z/⇧⌘Z land through the responder chain (docs/model.md).
            | Cap::UndoBridge
            | Cap::DragDrop | Cap::DragExternalImport | Cap::DragExternalExport | Cap::DragMultipleItems | Cap::DragFileReferences | Cap::EditBridge
            | Cap::AppBadgeDot
            | Cap::Appearance
            // firstBaselineOffsetFromTop — the platform's own answer (docs/baseline.md).
            | Cap::BaselineAlignment
            // A REAL inspector NSSplitViewItem (`inspectorWithViewController:`): the system
            // trailing-pane material and full-height layout (docs/inspector.md).
            | Cap::Inspector
            // A plain NSSplitView with two arranged panes (docs/split.md).
            | Cap::Split
            | Cap::TextRuns
            | Cap::TextLinks => Support::Native,
            // A topmost autoresizing child of the content view — not a system modal
            // (docs/cover.md's ArkUI tier).
            Cap::Cover => Support::Emulated,
            // `.sheet()` is a window sheet on the primary window (docs/cover.md "Modal sheet").
            Cap::CoverSheet => Support::Native,
            _ => Support::Unsupported,
        }
    }

    fn realize(&mut self, kind: PieceKind, props: &dyn Any, id: NodeId) -> Handle {
        let mtm = self.mtm;
        match Builtin::from_key(kind) {
            Some(Builtin::Container) => {
                let v = DayFlipped::new(mtm);
                if let Some(p) = props.downcast_ref::<ContainerProps>() {
                    if p.role == Some(day_spec::SurfaceRole::SectionCard) {
                        v.set_section_card(p.corner_radius);
                    } else if p.background.is_some() || p.corner_radius > 0.0 || p.clips {
                        v.set_surface(p.background, p.corner_radius, p.clips);
                    }
                }
                view_of(v)
            }
            Some(Builtin::Scroll) => {
                let horizontal = props
                    .downcast_ref::<day_spec::props::ScrollProps>()
                    .map(|p| p.horizontal)
                    .unwrap_or(false);
                let sv = unsafe { NSScrollView::new(mtm) };
                unsafe {
                    sv.setHasVerticalScroller(!horizontal);
                    sv.setHasHorizontalScroller(horizontal);
                    sv.setDrawsBackground(false);
                    // Overlay scrollers ALWAYS: day lays content out at the scroll's full frame
                    // width, and a legacy scroller (the "always show scroll bars" system
                    // setting, or a mouse attached) would reserve ~15pt and clip trailing
                    // content. Overlay floats above content instead — and matches the GTK/Qt
                    // backends.
                    sv.setScrollerStyle(objc2_app_kit::NSScrollerStyle::Overlay);
                }
                let doc = DayFlipped::new(mtm);
                unsafe { sv.setDocumentView(Some(doc.as_ref())) };
                view_of(sv)
            }
            Some(Builtin::Label) => {
                // `props_of`, not a panicking downcast, for every typed-props arm: a mismatch
                // (a piece registered under a builtin key, or a day-core regression) warns once
                // per kind and degrades to the placeholder — realize runs inside native
                // up-calls, where a panic is a process kill.
                let Some(p) = props_of::<LabelProps>(kind, "appkit", props) else {
                    return placeholder_view(mtm, kind);
                };
                let tf = DayLabel::new(mtm, id, &p.text);
                configure_label_cell(&tf);
                if !p.wraps || p.max_lines > 0 {
                    unsafe {
                        tf.setMaximumNumberOfLines(if p.wraps { p.max_lines as isize } else { 1 });
                        if !p.wraps || p.max_lines == 1 {
                            tf.setUsesSingleLineMode(true);
                            tf.setLineBreakMode(objc2_app_kit::NSLineBreakMode::ByTruncatingTail);
                        }
                    }
                }
                unsafe { tf.setFont(Some(&nsfont(p.font))) };
                // The PLAIN path needs the role as much as the attributed one below: a label
                // with no runs never reaches `attributed_label`, and reading the role only there
                // left every ordinary `.secondary()` label rendering in the primary color.
                match (p.color, p.role) {
                    (Some(c), _) => unsafe { tf.setTextColor(Some(&nscolor(c))) },
                    (None, day_spec::props::TextRole::Secondary) => unsafe {
                        tf.setTextColor(Some(&objc2_app_kit::NSColor::secondaryLabelColor()))
                    },
                    (None, day_spec::props::TextRole::Primary) => {}
                }
                if !p.runs.is_empty() {
                    let s = attributed_label(&p.text, &nsfont(p.font), p.color, p.role, &p.runs);
                    unsafe { tf.setAttributedStringValue(&s) };
                }
                tf.ivars().has_runs.set(!p.runs.is_empty());
                tf.set_links(p.runs.iter().any(|r| r.link.is_some()));
                // Alignment goes on last and, for a runs label, has to reach inside the
                // attributed string. `setAlignment:` writes the cell's paragraph style, which an
                // attributed string then overrides wholesale with its own — so a markdown label
                // set only through the cell comes out leading-aligned no matter what was asked.
                if p.align != day_spec::props::TextAlign::Leading {
                    unsafe { tf.setAlignment(nstextalign(p.align)) };
                    if !p.runs.is_empty() {
                        set_paragraph_alignment(&tf, nstextalign(p.align));
                    }
                }
                view_of(Retained::into_super(tf))
            }
            Some(Builtin::Button) => {
                let Some(p) = props_of::<ButtonProps>(kind, "appkit", props) else {
                    return placeholder_view(mtm, kind);
                };
                let target = DayTarget::new(mtm, id);
                let btn = unsafe {
                    NSButton::buttonWithTitle_target_action(
                        &NSString::from_str(&p.title),
                        Some(&*target),
                        Some(sel!(action:)),
                        mtm,
                    )
                };
                apply_button_style(&btn, p.style);
                if p.icon.is_some() {
                    apply_button_content(&btn, &p.title, p.icon.as_ref(), p.icon_only);
                }
                unsafe { btn.setEnabled(p.enabled) };
                set_button_selected(&btn, p.selected);
                let view = view_of(btn);
                TARGETS.with(|m| m.borrow_mut().insert(ptr_of(&view), target));
                view
            }
            Some(Builtin::Toggle) => {
                let Some(p) = props_of::<ToggleProps>(kind, "appkit", props) else {
                    return placeholder_view(mtm, kind);
                };
                let target = DayTarget::new(mtm, id);
                let sw = unsafe { NSSwitch::new(mtm) };
                unsafe {
                    sw.setState(if p.on { 1 } else { 0 });
                    sw.setEnabled(p.enabled);
                    sw.setTarget(Some(&*target));
                    sw.setAction(Some(sel!(action:)));
                }
                let view = view_of(sw);
                TARGETS.with(|m| m.borrow_mut().insert(ptr_of(&view), target));
                view
            }
            Some(Builtin::Slider) => {
                let Some(p) = props_of::<SliderProps>(kind, "appkit", props) else {
                    return placeholder_view(mtm, kind);
                };
                let target = DayTarget::new(mtm, id);
                let sl = unsafe {
                    NSSlider::sliderWithValue_minValue_maxValue_target_action(
                        p.value,
                        p.min,
                        p.max,
                        Some(&*target),
                        Some(sel!(action:)),
                        mtm,
                    )
                };
                unsafe { sl.setContinuous(true) };
                let view = view_of(sl);
                TARGETS.with(|m| m.borrow_mut().insert(ptr_of(&view), target));
                view
            }
            Some(Builtin::Picker) => picker::realize_any(self, props, id),
            Some(Builtin::TextArea) => textarea::realize_any(self, props, id),
            Some(Builtin::TextField) => {
                let Some(p) = props_of::<TextFieldProps>(kind, "appkit", props) else {
                    return placeholder_view(mtm, kind);
                };
                let tf = new_text_field(mtm, id, false);
                unsafe {
                    tf.setStringValue(&NSString::from_str(&p.text));
                    tf.setPlaceholderString(Some(&NSString::from_str(&p.placeholder)));
                }
                view_of(tf)
            }
            Some(Builtin::Divider) => {
                let b = unsafe { NSBox::new(mtm) };
                unsafe { b.setBoxType(NSBoxType::Separator) };
                view_of(b)
            }
            Some(Builtin::Progress) => {
                let Some(p) = props_of::<ProgressProps>(kind, "appkit", props) else {
                    return placeholder_view(mtm, kind);
                };
                if p.value.is_none() {
                    return crate::controls::spinner::make(self, p, id);
                }
                let pi = unsafe { NSProgressIndicator::new(mtm) };
                unsafe {
                    match p.value {
                        Some(v) => {
                            pi.setStyle(NSProgressIndicatorStyle::Bar);
                            pi.setIndeterminate(false);
                            pi.setMinValue(0.0);
                            pi.setMaxValue(1.0);
                            pi.setDoubleValue(v);
                        }
                        None => {
                            pi.setStyle(NSProgressIndicatorStyle::Spinning);
                            pi.setIndeterminate(true);
                            pi.startAnimation(None);
                        }
                    }
                }
                view_of(pi)
            }
            Some(Builtin::Canvas) => {
                let canvas = DayCanvas::new(mtm);
                KEY_NODES.with(|t| t.insert(Retained::as_ptr(&canvas) as usize, id));
                view_of(canvas)
            }
            Some(Builtin::Inspector) => {
                let (visible, width, leading) = props
                    .downcast_ref::<InspectorProps>()
                    .map(|p| {
                        (
                            p.visible,
                            p.width,
                            p.edge == day_spec::props::PaneEdge::Leading,
                        )
                    })
                    .unwrap_or((false, 280.0, false));
                let content_wrap = view_of(DayFlipped::new(mtm));
                let panel_flipped = DayFlipped::new(mtm);
                // The panel draws an opaque window-background backdrop over the item's
                // vibrancy material — without it the section cards' thin quaternary fill
                // composites into near-black in dark mode (see `FlippedIvars`).
                panel_flipped.set_pane_backdrop();
                let panel_wrap = view_of(panel_flipped);
                let split_vc = unsafe { objc2_app_kit::NSSplitViewController::new(mtm) };
                // Force loadView before the items go in — the same lifecycle rule the nav
                // host below documents.
                let _ = unsafe { split_vc.view() };
                let content_vc = unsafe { objc2_app_kit::NSViewController::new(mtm) };
                let panel_vc = unsafe { objc2_app_kit::NSViewController::new(mtm) };
                unsafe {
                    content_vc.setView(&content_wrap);
                    panel_vc.setView(&panel_wrap);
                }
                let content_item = unsafe {
                    objc2_app_kit::NSSplitViewItem::splitViewItemWithViewController(&content_vc)
                };
                // A TRAILING pane is a real inspector item (the system treatment). A LEADING
                // one is a plain item placed first: `sidebarWithViewController:` would bring
                // sidebar material, which captures black offscreen (docs/navigation.md), and
                // the panel wrap already paints its own backdrop.
                let panel_item = unsafe {
                    if leading {
                        objc2_app_kit::NSSplitViewItem::splitViewItemWithViewController(&panel_vc)
                    } else {
                        objc2_app_kit::NSSplitViewItem::inspectorWithViewController(&panel_vc)
                    }
                };
                unsafe {
                    // Day's signal is the only visibility driver: with the pinned width the
                    // divider has nothing to drag and the pane cannot be user-collapsed, so
                    // there is no native-initiated change to report back.
                    panel_item.setCanCollapse(false);
                    panel_item.setCollapsed(!visible);
                    panel_item.setMinimumThickness(width);
                    panel_item.setMaximumThickness(width);
                    panel_item.setAllowsFullHeightLayout(true);
                    if leading {
                        split_vc.addSplitViewItem(&panel_item);
                        split_vc.addSplitViewItem(&content_item);
                    } else {
                        split_vc.addSplitViewItem(&content_item);
                        split_vc.addSplitViewItem(&panel_item);
                    }
                }
                let split = unsafe { split_vc.splitView() };
                unsafe {
                    split.setVertical(true);
                    split.setDividerStyle(objc2_app_kit::NSSplitViewDividerStyle::Thin);
                    // The same Auto Layout hand-back as the nav host below: Day owns this
                    // view's frame outside the split; the controller's own constraints keep
                    // doing the pane sizing inside it.
                    split.setTranslatesAutoresizingMaskIntoConstraints(true);
                }
                let view = view_of(split);
                INSPECTOR_STATE.with(|m| {
                    m.borrow_mut().insert(
                        ptr_of(&view),
                        InspectorState {
                            content_wrap,
                            panel_wrap,
                            _split_vc: split_vc,
                            panel_item,
                        },
                    )
                });
                view
            }
            Some(Builtin::InspectorPane) => {
                // A DayNavPage for its `setFrameSize:` → `FrameChanged` report: the pane's
                // frame is native-owned (the split sizes it), exactly like a nav page —
                // NAV_PAGES membership is what makes `set_frame` skip it.
                let pane = view_of(DayNavPage::new(mtm, id));
                NAV_PAGES.with(|set| set.borrow_mut().insert(ptr_of(&pane)));
                let panel = props
                    .downcast_ref::<InspectorPaneProps>()
                    .map(|p| p.panel)
                    .unwrap_or(false);
                INSPECTOR_PANES.with(|t| t.insert(ptr_of(&pane), panel));
                pane
            }
            Some(Builtin::Split) => {
                let (axis, fraction, min_pane) = props
                    .downcast_ref::<SplitProps>()
                    .map(|p| (p.axis, p.fraction, p.min_pane))
                    .unwrap_or((day_spec::props::SplitAxis::Horizontal, 0.5, 80.0));
                let wrap = view_of(DayFlipped::new(mtm));
                let split = unsafe { objc2_app_kit::NSSplitView::new(mtm) };
                let first_wrap = view_of(DayFlipped::new(mtm));
                let second_wrap = view_of(DayFlipped::new(mtm));
                unsafe {
                    // AppKit's "vertical" is the divider's orientation: panes side by side.
                    split.setVertical(axis == day_spec::props::SplitAxis::Horizontal);
                    split.setDividerStyle(objc2_app_kit::NSSplitViewDividerStyle::Thin);
                    split.addArrangedSubview(&first_wrap);
                    split.addArrangedSubview(&second_wrap);
                    split.setFrame(wrap.bounds());
                    split.setAutoresizingMask(
                        objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable
                            | objc2_app_kit::NSAutoresizingMaskOptions::ViewHeightSizable,
                    );
                    wrap.addSubview(&split);
                }
                let delegate = DaySplitDelegate::new(mtm, id, min_pane, fraction);
                split.setDelegate(Some(ProtocolObject::from_ref(&*delegate)));
                SPLIT_STATE.with(|m| {
                    m.borrow_mut().insert(
                        ptr_of(&wrap),
                        SplitState {
                            split,
                            first_wrap,
                            second_wrap,
                            delegate,
                        },
                    )
                });
                wrap
            }
            Some(Builtin::SplitPane) => {
                // A DayNavPage, as an inspector pane: the splitter owns its frame, and its
                // `setFrameSize:` reports `FrameChanged`.
                let pane = view_of(DayNavPage::new(mtm, id));
                NAV_PAGES.with(|set| set.borrow_mut().insert(ptr_of(&pane)));
                let second = props
                    .downcast_ref::<SplitPaneProps>()
                    .map(|p| p.second)
                    .unwrap_or(false);
                SPLIT_PANES.with(|t| t.insert(ptr_of(&pane), second));
                pane
            }
            Some(Builtin::Nav) => {
                let presentation = props
                    .downcast_ref::<NavProps>()
                    .map(|p| p.presentation)
                    .unwrap_or(NavPresentation::Split);
                let is_split = presentation.is_split();
                // The host is an NSSplitViewController, not a bare NSSplitView. Handing the
                // sidebar pane to `NSSplitViewItem::sidebarWithViewController:` is what buys
                // the system treatment: AppKit installs its own backing material and vibrancy
                // (so no hand-rolled NSVisualEffectView), pins the thickness with a sidebar
                // holding priority, animates collapse/expand, and drives the window's titlebar
                // separator. Day still owns the CONTENT of each pane — the two wraps below are
                // the item view controllers' views, so `insert`/`remove`/the NAV patches are
                // unchanged.
                let sidebar_wrap = view_of(DayFlipped::new(mtm));
                let detail_wrap = view_of(DayFlipped::new(mtm));
                let split_vc = unsafe { objc2_app_kit::NSSplitViewController::new(mtm) };
                // Force loadView/viewDidLoad before the items go in. NSSplitViewController
                // installs an item's view into the split as the item is added, which it can
                // only do once its own view exists — and reading `splitView` does not trigger
                // the lifecycle the way reading `view` does. Skipping this leaves a split view
                // with zero subviews: correct frame, nothing in it.
                let _ = unsafe { split_vc.view() };
                // Plain NSViewControllers with their view set explicitly: setting `view` up
                // front is what stops NSViewController looking for a nib named after itself.
                let sidebar_vc = unsafe { objc2_app_kit::NSViewController::new(mtm) };
                let detail_vc = unsafe { objc2_app_kit::NSViewController::new(mtm) };
                unsafe {
                    sidebar_vc.setView(&pane_under_title_bar(mtm, &sidebar_wrap));
                    detail_vc.setView(&pane_under_title_bar(mtm, &detail_wrap));
                }
                let sidebar_item = unsafe {
                    objc2_app_kit::NSSplitViewItem::sidebarWithViewController(&sidebar_vc)
                };
                let detail_item = unsafe {
                    objc2_app_kit::NSSplitViewItem::splitViewItemWithViewController(&detail_vc)
                };
                // The content-list pane (docs/navigation.md): a REAL `contentList`
                // NSSplitViewItem between the sidebar and the detail — Mail's own machinery,
                // holding priorities included. Its `Pane::List` page fills `list_wrap` exactly
                // as the sidebar page fills its own wrap, and the pane persists through every
                // presentation (only `NavPatch::ListVisible` collapses it).
                let list_width = props.downcast_ref::<NavProps>().and_then(|p| p.list_width);
                // Set before the item joins the split, exactly as the sidebar's is below. A
                // collapsed state applied afterwards — by `NavPatch::ListVisible`, on a window
                // that has not been displayed — reports as collapsed and is then laid back out
                // from the item's holding priorities, which is how an app whose first
                // destination has no list opened with one beside it anyway.
                let list_visible = props
                    .downcast_ref::<NavProps>()
                    .is_none_or(|p| p.list_visible);
                let (list_wrap, list_item) = match list_width {
                    Some(w) => {
                        let wrap = view_of(DayFlipped::new(mtm));
                        let vc = unsafe { objc2_app_kit::NSViewController::new(mtm) };
                        unsafe { vc.setView(&pane_under_title_bar(mtm, &wrap)) };
                        let item = unsafe {
                            objc2_app_kit::NSSplitViewItem::contentListWithViewController(&vc)
                        };
                        unsafe {
                            item.setCanCollapse(true);
                            item.setMinimumThickness(NAV_LIST_MIN_W.min(w));
                            item.setMaximumThickness(NAV_LIST_MAX_W.max(w));
                            item.setCollapsed(!list_visible);
                        }
                        (Some(wrap), Some(item))
                    }
                    None => (None, None),
                };
                unsafe {
                    // A stack presentation has no sidebar to show: collapse the (empty) pane
                    // and refuse the drag, so the detail owns the full width.
                    sidebar_item.setCanCollapse(is_split);
                    sidebar_item.setCollapsed(!is_split);
                    if is_split {
                        // Run the sidebar's material to the top of the window, under the
                        // titlebar, the way Mail and Finder do. Pairs with the unified toolbar
                        // style the window already uses (toolbar.rs).
                        sidebar_item.setAllowsFullHeightLayout(true);
                        sidebar_item.setMinimumThickness(NAV_SIDEBAR_MIN_W);
                        sidebar_item.setMaximumThickness(NAV_SIDEBAR_MAX_W);
                    } else {
                        sidebar_item.setMinimumThickness(0.0);
                        sidebar_item.setMaximumThickness(0.0);
                    }
                    split_vc.addSplitViewItem(&sidebar_item);
                    if let Some(item) = list_item.as_ref() {
                        split_vc.addSplitViewItem(item);
                    }
                    split_vc.addSplitViewItem(&detail_item);
                }
                let split = unsafe { split_vc.splitView() };
                // NSToolbarToggleSidebarItem sends `toggleSidebar:` down the RESPONDER chain,
                // and NSSplitViewController implements it — but a view controller only patches
                // itself into that chain when it is parented (a window's contentViewController
                // or another controller's child), and Day's tree is view-based all the way to
                // the window. Insert it by hand, directly after the split view, so a first
                // responder anywhere inside either pane walks up through it.
                unsafe {
                    let after = split.nextResponder();
                    split.setNextResponder(Some(&split_vc));
                    // The controller must never end up aiming at itself or at its OWN view,
                    // or its dealloc aborts the process: `-[NSViewController dealloc]`
                    // splices itself out with `view.nextResponder = self.nextResponder`, and
                    // if that lands the view on itself AppKit raises "The next responder
                    // should never be yourself!" — an NSException that unwinds into Rust and
                    // aborts. Both shapes occur here naturally: before macOS 15 the freshly
                    // loaded split view's next IS the controller, and on 15+ `view` is a
                    // WRAPPER above `splitView` whose auto-wiring makes the split's next
                    // that wrapper. Neither is a real upstream hop, so drop them.
                    let own_view = split_vc.view();
                    let vc_resp: *const objc2_app_kit::NSResponder = {
                        let r: &objc2_app_kit::NSResponder = &split_vc;
                        r
                    };
                    let view_resp: *const objc2_app_kit::NSResponder = {
                        let r: &objc2_app_kit::NSResponder = &own_view;
                        r
                    };
                    let upstream = after.filter(|a| {
                        let p: *const objc2_app_kit::NSResponder = &**a;
                        p != vc_resp && p != view_resp
                    });
                    split_vc.setNextResponder(upstream.as_deref());
                }
                unsafe {
                    split.setVertical(true);
                    split.setDividerStyle(objc2_app_kit::NSSplitViewDividerStyle::Thin);
                    // Day owns this view's frame (`set_frame`). A split view vended by
                    // NSSplitViewController arrives switched over to Auto Layout, which
                    // ignores that frame and lays the split out at zero — a window with
                    // chrome and nothing under it. Hand it back to autoresizing translation
                    // so Day stays the layout owner outside the split; the constraints the
                    // controller installs BETWEEN the split and its panes are untouched and
                    // keep doing the pane sizing.
                    split.setTranslatesAutoresizingMaskIntoConstraints(true);
                }
                let root_title = props
                    .downcast_ref::<NavProps>()
                    .map(|p| p.title.clone())
                    .unwrap_or_default();
                // Stack presentation: a back header (hidden at root) — desktop has no system
                // back affordance, so a pushed page needs its own way out (docs/navigation.md).
                let header = if presentation == NavPresentation::Stack {
                    Some(build_nav_header(mtm, id, &detail_wrap, &root_title))
                } else {
                    None
                };
                // A tabs host: the Mac's own tab control fills the detail pane and takes the
                // detail pages as its items (`TabHost`).
                let tabs = (presentation == NavPresentation::Tabs).then(|| {
                    let tv = unsafe { objc2_app_kit::NSTabView::new(mtm) };
                    // Inset from the pane, the way a tab view sits in any Mac window: its
                    // tabs stand above the bezel, so flush to the top they run into the
                    // toolbar's edge, and flush to the sides the bezel hugs the sidebar. The
                    // autoresizing mask keeps the margins as the pane resizes.
                    let b = detail_wrap.bounds();
                    let frame = NSRect::new(
                        NSPoint::new(NAV_TABVIEW_INSET, NAV_TABVIEW_INSET_TOP),
                        NSSize::new(
                            (b.size.width - 2.0 * NAV_TABVIEW_INSET).max(0.0),
                            (b.size.height - NAV_TABVIEW_INSET_TOP - NAV_TABVIEW_INSET).max(0.0),
                        ),
                    );
                    unsafe {
                        tv.setTabViewType(
                            if props
                                .downcast_ref::<NavProps>()
                                .is_some_and(|p| p.documents.is_some())
                            {
                                objc2_app_kit::NSTabViewType::NoTabsNoBorder
                            } else {
                                objc2_app_kit::NSTabViewType::TopTabsBezelBorder
                            },
                        );
                        tv.setFrame(frame);
                        tv.setAutoresizingMask(
                            objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable
                                | objc2_app_kit::NSAutoresizingMaskOptions::ViewHeightSizable,
                        );
                        detail_wrap.addSubview(&tv);
                    }
                    TabHost {
                        view: tv,
                        target: None,
                    }
                });
                let view = view_of(split);
                NAV_STATE.with(|m| {
                    m.borrow_mut().insert(
                        ptr_of(&view),
                        NavState {
                            sidebar_wrap,
                            detail_wrap,
                            _split_vc: split_vc,
                            sidebar_item,
                            list_wrap,
                            list_item,
                            pages: Vec::new(),
                            list_page: None,
                            sidebar_page: None,
                            list_width,
                            list_visible,
                            list_positioned: false,
                            positioned: false,
                            presentation,
                            selected: 0,
                            tabs,
                            header,
                            root_title,
                            node: id,
                            title_strip: 0.0,
                        },
                    )
                });
                view
            }
            Some(Builtin::NavPage) => {
                let page = view_of(DayNavPage::new(mtm, id));
                NAV_PAGES.with(|set| set.borrow_mut().insert(ptr_of(&page)));
                if let Some(p) = props.downcast_ref::<day_spec::props::NavPageProps>() {
                    PAGE_PANE.with(|t| t.insert(ptr_of(&page), p.pane));
                }
                page
            }
            // Emulated fullscreen cover (docs/cover.md, the ArkUI tier): a DayNavPage — its
            // setFrameSize: override reports FrameChanged, so a window resize re-lays the cover
            // content for free — parked hidden until CoverPatch::Present re-homes it on top.
            Some(Builtin::Cover) => {
                let page = DayNavPage::new(mtm, id);
                let cover_props = props.downcast_ref::<CoverProps>();
                // A half sheet is a sheet here: macOS has no half-height presentation of its
                // own, so the window sheet stands in, at half the parent's height.
                page.ivars()
                    .sheet
                    .set(cover_props.is_some_and(|p| p.sheet || p.half));
                page.ivars().half.set(cover_props.is_some_and(|p| p.half));
                unsafe { page.setHidden(true) };
                view_of(page)
            }
            Some(Builtin::NavMenu) => {
                let Some(p) = props_of::<NavMenuProps>(kind, "appkit", props) else {
                    return placeholder_view(mtm, kind);
                };
                let data = DayNavMenuData::new(
                    mtm,
                    id,
                    &p.items,
                    &p.icons,
                    &p.badges,
                    &p.badge_icons,
                    &p.badge_tints,
                    &p.sections,
                    &p.tints,
                    &p.menus,
                );
                *data.ivars().movable.borrow_mut() = p.movable.clone();
                data.ivars().regroup.set(p.regroup);
                *data.ivars().sorted.borrow_mut() = p.sorted.clone();
                // The Day subclass serves per-row context menus via menuForEvent:.
                let outline: Retained<objc2_app_kit::NSOutlineView> = {
                    let o: Retained<DayNavOutlineView> =
                        unsafe { msg_send![DayNavOutlineView::alloc(mtm), init] };
                    NAV_OUTLINE_MENUS
                        .with(|t| t.insert(Retained::as_ptr(&o) as usize, data.clone()));
                    unsafe { msg_send![&*o, self] }
                };
                let col = unsafe {
                    objc2_app_kit::NSTableColumn::initWithIdentifier(
                        objc2_app_kit::NSTableColumn::alloc(mtm),
                        &NSString::from_str("item"),
                    )
                };
                unsafe {
                    outline.addTableColumn(&col);
                    outline.setOutlineTableColumn(Some(&col));
                    outline.setHeaderView(None);
                    // SourceList: the real sidebar treatment (Finder/Mail). The outline now
                    // lives inside a sidebar NSSplitViewItem, so AppKit supplies the backing
                    // material and the vibrancy the source-list selection composites through.
                    // This was Inset until 2026-08 because the earlier hand-rolled
                    // NSVisualEffectView blended behind the window, and an offscreen capture
                    // (`cacheDisplayInRect`) has no backdrop to sample — the selection came out
                    // a black pill that swallowed the row label. The material is AppKit's own
                    // now, and captures go through the window server (`snapshot_view`), which
                    // composites the material for real instead of guessing at it.
                    // `style = SourceList` is the whole switch: the matching
                    // `selectionHighlightStyle` constant is deprecated precisely because the
                    // style property now implies it.
                    outline.setStyle(objc2_app_kit::NSTableViewStyle::SourceList);
                    // The default row size style follows the system's Sidebar icon size
                    // (Small, Medium, Large), live, as Finder's and Mail's sidebars do: AppKit
                    // sets the row height, the label's font and the icon's size. A table made
                    // in code starts at Custom, which ignores the setting.
                    outline.setRowSizeStyle(objc2_app_kit::NSTableViewRowSizeStyle::Default);
                    // Section headers pin to the top of the scroll as their group passes under
                    // it, the way Finder's sidebar groups do.
                    outline.setFloatsGroupRows(true);
                    outline.setIndentationPerLevel(0.0);
                    // Drag-to-reorder within this sidebar only (docs/navigation.md): rows that
                    // cannot move offer no drag, so registering costs a plain sidebar nothing.
                    outline.registerForDraggedTypes(
                        &objc2_foundation::NSArray::from_retained_slice(&[NSString::from_str(
                            DAY_NAV_PASTEBOARD_TYPE,
                        )]),
                    );
                    outline.setDraggingSourceOperationMask_forLocal(
                        objc2_app_kit::NSDragOperation::Move,
                        true,
                    );
                    outline.setDraggingSourceOperationMask_forLocal(
                        objc2_app_kit::NSDragOperation::None,
                        false,
                    );
                    outline.setDraggingDestinationFeedbackStyle(
                        objc2_app_kit::NSTableViewDraggingDestinationFeedbackStyle::Gap,
                    );
                    outline.setDataSource(Some(ProtocolObject::from_ref(&*data)));
                    outline.setDelegate(Some(ProtocolObject::from_ref(&*data)));
                    outline.reloadData();
                }
                let scroll = unsafe { NSScrollView::new(mtm) };
                unsafe {
                    scroll.setDrawsBackground(false);
                    scroll.setHasVerticalScroller(true);
                    // Overlay scrollers always — a legacy scroller would reserve ~15pt and
                    // clip the trailing edge of rows laid out at the full frame width (see
                    // the SCROLL realize).
                    scroll.setScrollerStyle(objc2_app_kit::NSScrollerStyle::Overlay);
                    // One column, sized to the pane: a sidebar never scrolls sideways.
                    scroll.setHasHorizontalScroller(false);
                    outline.setAutoresizingMask(
                        objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable,
                    );
                    outline.setColumnAutoresizingStyle(
                        objc2_app_kit::NSTableViewColumnAutoresizingStyle::UniformColumnAutoresizingStyle,
                    );
                    scroll.setDocumentView(Some(&outline));
                }
                let view = view_of(scroll);
                // Day selects by ITEM index; section headers make that differ from the
                // outline's row index, so every programmatic selection maps through `rows`.
                if let Some(row) = p.selected.and_then(|sel| data.row_of_item(sel)) {
                    data.ivars().suppress.set(true);
                    unsafe {
                        outline.selectRowIndexes_byExtendingSelection(
                            &objc2_foundation::NSIndexSet::indexSetWithIndex(row),
                            false,
                        )
                    };
                    data.ivars().suppress.set(false);
                }
                NAV_MENUS.with(|m| m.borrow_mut().insert(ptr_of(&view), (outline, data)));
                view
            }
            Some(Builtin::List) => {
                let Some(p) = props_of::<ListProps>(kind, "appkit", props) else {
                    return placeholder_view(mtm, kind);
                };
                // Every list reports responder changes, even without an activation handler.
                let table: Retained<DayListView> =
                    unsafe { msg_send![DayListView::alloc(mtm), init] };
                let table = Retained::into_super(table);
                let col = unsafe {
                    NSTableColumn::initWithIdentifier(
                        NSTableColumn::alloc(mtm),
                        &NSString::from_str("day.list.col"),
                    )
                };
                let data = DayListData::new(
                    mtm,
                    id,
                    p.selectable,
                    p.multi_select,
                    p.row_height == RowHeight::Automatic,
                    p.sections,
                );
                unsafe {
                    if p.multi_select {
                        table.setAllowsMultipleSelection(true);
                    }
                    table.addTableColumn(&col);
                    table.setHeaderView(None);
                    // PLAIN, the classic edge-to-edge style: the macOS 11+ decorated styles
                    // (automatic ~14pt, FullWidth ~6pt) inset every cell view, clipping day
                    // row content laid out at the host's full frame width. This table ran
                    // FullWidth with a custom NSTableRowView pinning cells back to the row
                    // bounds until 2026-08 — and that pin also clobbered the cell-frame slide
                    // AppKit performs for row-action swipes, so the actions revealed behind a
                    // row whose CONTENT never moved. Plain has no inset to fight: standard
                    // row views, standard cell frames, and the swipe slide works untouched.
                    table.setStyle(objc2_app_kit::NSTableViewStyle::Plain);
                    // ...and the default intercell spacing (3pt × 2pt) shaves the column the
                    // same way — the last few points of a trailing control. Day rows own all
                    // of their spacing.
                    table.setIntercellSpacing(NSSize::new(0.0, 0.0));
                    // Host-drawn row separators (docs/list.md): the native horizontal grid
                    // line, which sits exactly at the row boundary — aligned with the
                    // selection, stationary under a row-action swipe, the Mail look.
                    if p.separators == Some(true) {
                        table.setGridStyleMask(
                            objc2_app_kit::NSTableViewGridLineStyle::SolidHorizontalGridLineMask,
                        );
                        table.setGridColor(&objc2_app_kit::NSColor::separatorColor());
                    }
                    table.setColumnAutoresizingStyle(
                        objc2_app_kit::NSTableViewColumnAutoresizingStyle::UniformColumnAutoresizingStyle,
                    );
                    // Section headers pin to the top while their section scrolls under them,
                    // the way Mail's and Finder's group rows do (docs/list.md "Sections").
                    table.setFloatsGroupRows(p.sections);
                    match p.row_height {
                        RowHeight::Uniform(h) => table.setRowHeight(h),
                        RowHeight::Automatic => table.setRowHeight(44.0),
                    }
                    if !p.selectable {
                        table.setSelectionHighlightStyle(
                            objc2_app_kit::NSTableViewSelectionHighlightStyle::None,
                        );
                    }
                    // Transparent: day panes own their backgrounds — the stock
                    // controlBackgroundColor would paint an appearance-colored slab that
                    // fights a themed app (visible whenever rows don't fill the viewport).
                    table.setBackgroundColor(&objc2_app_kit::NSColor::clearColor());
                    table.setDataSource(Some(ProtocolObject::from_ref(&*data)));
                    table.setDelegate(Some(ProtocolObject::from_ref(&*data)));
                    table.setTarget(Some(&*data));
                    if p.activatable {
                        table.setDoubleAction(Some(sel!(doubleClickRow:)));
                    }
                    if p.reorderable {
                        // Native drag-to-reorder (docs/list.md): rows drag within this table
                        // only (move locally, nothing leaves the app), and the drop target shows
                        // macOS's temporary placeholder GAP while the drag is over the table.
                        table.registerForDraggedTypes(
                            &objc2_foundation::NSArray::from_retained_slice(&[NSString::from_str(
                                DAY_ROW_PASTEBOARD_TYPE,
                            )]),
                        );
                        table.setDraggingSourceOperationMask_forLocal(
                            objc2_app_kit::NSDragOperation::Move,
                            true,
                        );
                        table.setDraggingSourceOperationMask_forLocal(
                            objc2_app_kit::NSDragOperation::None,
                            false,
                        );
                        table.setDraggingDestinationFeedbackStyle(
                            objc2_app_kit::NSTableViewDraggingDestinationFeedbackStyle::Gap,
                        );
                    }
                }
                let scroll = unsafe { NSScrollView::new(mtm) };
                unsafe {
                    scroll.setDrawsBackground(false);
                    scroll.setHasVerticalScroller(true);
                    // Overlay scrollers always — a legacy scroller would reserve ~15pt and
                    // clip the trailing edge of rows laid out at the full frame width (see
                    // the SCROLL realize).
                    scroll.setScrollerStyle(objc2_app_kit::NSScrollerStyle::Overlay);
                    scroll.setDocumentView(Some(&table));
                    let clip = scroll.contentView();
                    clip.setPostsBoundsChangedNotifications(true);
                    objc2_foundation::NSNotificationCenter::defaultCenter()
                        .addObserver_selector_name_object(
                            &data,
                            sel!(listViewportChanged:),
                            Some(objc2_app_kit::NSViewBoundsDidChangeNotification),
                            Some(&clip),
                        );
                }
                let view = view_of(scroll);
                LIST_STATE.with(|m| m.borrow_mut().insert(ptr_of(&view), (table, data)));
                view
            }
            Some(Builtin::Tree) => {
                let Some(p) = props_of::<TreeProps>(kind, "appkit", props) else {
                    return placeholder_view(mtm, kind);
                };
                // The width-pinning subclass (see DayOutlineView).
                let outline: Retained<objc2_app_kit::NSOutlineView> = {
                    let o: Retained<DayOutlineView> =
                        unsafe { msg_send![DayOutlineView::alloc(mtm), init] };
                    unsafe { msg_send![&*o, self] }
                };
                let col = unsafe {
                    NSTableColumn::initWithIdentifier(
                        NSTableColumn::alloc(mtm),
                        &NSString::from_str("day.tree.col"),
                    )
                };
                let data = DayTreeData::new(mtm, id, p.selectable);
                unsafe {
                    if p.multi_select {
                        outline.setAllowsMultipleSelection(true);
                    }
                    outline.addTableColumn(&col);
                    outline.setOutlineTableColumn(Some(&col));
                    outline.setHeaderView(None);
                    if p.section_headers {
                        // Real source-list groups use AppKit's trailing, hover-revealed
                        // show/hide button and float over their children while scrolling.
                        outline.setStyle(objc2_app_kit::NSTableViewStyle::SourceList);
                        outline.setFloatsGroupRows(true);
                    } else {
                        // Generic trees keep their existing full-width cells and rounded
                        // DayTreeRowView selection. Source lists use native row drawing.
                        outline.setStyle(objc2_app_kit::NSTableViewStyle::FullWidth);
                        outline.setIntercellSpacing(NSSize::new(0.0, 0.0));
                    }
                    outline.setColumnAutoresizingStyle(
                        objc2_app_kit::NSTableViewColumnAutoresizingStyle::UniformColumnAutoresizingStyle,
                    );
                    outline.setAutoresizesOutlineColumn(true);
                    if let Some(indent) = p.indent {
                        outline.setIndentationPerLevel(indent);
                    }
                    match p.row_height {
                        RowHeight::Uniform(h) => outline.setRowHeight(h),
                        RowHeight::Automatic if !p.section_headers => outline.setRowHeight(24.0),
                        RowHeight::Automatic => {}
                    }
                    if !p.selectable {
                        outline.setSelectionHighlightStyle(
                            objc2_app_kit::NSTableViewSelectionHighlightStyle::None,
                        );
                    }
                    outline.setBackgroundColor(&objc2_app_kit::NSColor::clearColor());
                    outline.setDataSource(Some(ProtocolObject::from_ref(&*data)));
                    outline.setDelegate(Some(ProtocolObject::from_ref(&*data)));
                    if p.movable {
                        // Native drag-to-move (docs/tree.md): nodes drag within this outline
                        // only. The REGULAR feedback style (not the list's Gap): a tree drop
                        // must distinguish "between rows" (insertion line) from "ONTO a row"
                        // (the highlighted-parent drop), and Gap has no onto affordance.
                        outline.registerForDraggedTypes(
                            &objc2_foundation::NSArray::from_retained_slice(&[NSString::from_str(
                                DAY_TREE_PASTEBOARD_TYPE,
                            )]),
                        );
                        outline.setDraggingSourceOperationMask_forLocal(
                            objc2_app_kit::NSDragOperation::Move,
                            true,
                        );
                        outline.setDraggingSourceOperationMask_forLocal(
                            objc2_app_kit::NSDragOperation::None,
                            false,
                        );
                    }
                }
                let scroll = unsafe { NSScrollView::new(mtm) };
                unsafe {
                    scroll.setDrawsBackground(false);
                    scroll.setHasVerticalScroller(true);
                    scroll.setHasHorizontalScroller(false);
                    scroll.setScrollerStyle(objc2_app_kit::NSScrollerStyle::Overlay);
                    outline.setAutoresizingMask(
                        objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable,
                    );
                    scroll.setDocumentView(Some(&outline));
                }
                let view = view_of(scroll);
                TREE_STATE.with(|m| m.borrow_mut().insert(ptr_of(&view), (outline, data)));
                view
            }
            Some(Builtin::Image) => {
                let Some(p) = props_of::<ImageProps>(kind, "appkit", props) else {
                    return placeholder_view(mtm, kind);
                };
                let iv: Retained<objc2_app_kit::NSImageView> =
                    if p.content_mode == ContentMode::Fill {
                        let view: Retained<FillImageView> =
                            unsafe { msg_send![FillImageView::alloc(mtm), init] };
                        Retained::from(
                            <FillImageView as AsRef<objc2_app_kit::NSImageView>>::as_ref(&view),
                        )
                    } else {
                        unsafe { objc2_app_kit::NSImageView::new(mtm) }
                    };
                // Fill expands the native aspect-fit drawing in FillImageView; Stretch
                // scales each axis independently, and Fit keeps the stock image view.
                let scaling = match p.content_mode {
                    ContentMode::Stretch => objc2_app_kit::NSImageScaling::ScaleAxesIndependently,
                    _ => objc2_app_kit::NSImageScaling::ScaleProportionallyUpOrDown,
                };
                unsafe { iv.setImageScaling(scaling) };
                if let Some(img) = appkit_image_for(&p.source) {
                    // Vector-glyph tint (docs/vectors.md): template rendering + the view's
                    // content tint — AppKit recolors the alpha mask natively. A template with
                    // no tint keeps the view's nil tint: the neutral template color the nav
                    // menu's own rows draw with, light in dark mode, dark in light.
                    if p.tint.is_some() || p.template {
                        unsafe { img.setTemplate(true) };
                    }
                    unsafe { iv.setImage(Some(&img)) };
                }
                if let Some(t) = p.tint {
                    unsafe { iv.setContentTintColor(Some(&nscolor(t))) };
                }
                IMAGE_MODES.with(|t| {
                    t.insert(
                        ptr_of(&iv),
                        ImageMode {
                            template: p.template,
                            tinted: p.tint.is_some(),
                        },
                    )
                });
                view_of(iv)
            }
            Some(Builtin::ListItem) => {
                let Some(p) = props_of::<day_spec::props::ListItemProps>(kind, "appkit", props)
                else {
                    return placeholder_view(mtm, kind);
                };
                make_list_item(p, mtm)
            }
            // A recycled list cell is ADOPTED from the native list, never realized
            // through this path; anything else is an extension piece.
            Some(Builtin::ListCell) | None => {
                if let Some(make) = self.registry.get(kind).map(|r| r.make) {
                    return make(self, props, id);
                }
                // Unregistered kind: LOUD once-per-kind warning, then a visible-but-harmless
                // placeholder (§8.2's debug check will panic first in debug builds once the
                // required-kinds set lands).
                warn_missing_renderer(kind);
                placeholder_view(mtm, kind)
            }
        }
    }

    fn update(&mut self, h: &Handle, kind: PieceKind, patch: &dyn Any, _anim: Option<&AnimSpec>) {
        match kind {
            kinds::LIST_ITEM => {
                let Some(p) = patch.downcast_ref::<day_spec::props::ListItemPatch>() else {
                    return;
                };
                let props = LIST_ITEMS.with(|m| {
                    let mut m = m.borrow_mut();
                    let props = m.get_mut(&ptr_of(h))?;
                    use day_spec::props::ListItemPatch as P;
                    match p {
                        P::Title(t) => props.title = t.clone(),
                        P::Subtitle(t) => props.subtitle = t.clone(),
                        P::Detail(t) => props.detail = t.clone(),
                        P::Icon(i) => props.icon = i.clone(),
                        P::IconTint(c) => props.icon_tint = *c,
                        P::Checked(on) => props.checked = *on,
                    }
                    Some(props.clone())
                });
                if let Some(props) = props {
                    dress_list_item(h, &props, self.mtm());
                }
            }
            kinds::IMAGE => {
                if let Some(p) = patch.downcast_ref::<day_spec::props::ImagePatch>() {
                    match p {
                        day_spec::props::ImagePatch::Tint(c) => {
                            // Template rendering + the view's content tint, exactly as at realize
                            // — the glyph repaints in place rather than being rebuilt
                            // (docs/vectors.md). A template glyph stays one when the tint goes.
                            if let Ok(iv) = h.clone().downcast::<objc2_app_kit::NSImageView>() {
                                let key = ptr_of(&iv);
                                let template = IMAGE_MODES
                                    .with(|t| {
                                        t.with(key, |m| {
                                            m.tinted = c.is_some();
                                            m.renders_template()
                                        })
                                    })
                                    .unwrap_or(c.is_some());
                                if let Some(img) = unsafe { iv.image() } {
                                    unsafe { img.setTemplate(template) };
                                }
                                unsafe { iv.setContentTintColor(c.map(nscolor).as_deref()) };
                            }
                        }
                        // A source swap repaints the same view (docs/images.md), so an `image()`
                        // bound to a signal shows new pixels without rebuilding its subtree —
                        // which is what makes a decode-then-show flow a patch and not a rebuild.
                        day_spec::props::ImagePatch::Source(source) => {
                            if let Ok(iv) = h.clone().downcast::<objc2_app_kit::NSImageView>() {
                                // A source that will not load leaves the view showing what it
                                // was — the patch's contract, and what GTK, Qt and Android do.
                                // The new image renders the way the view does: a tinted or
                                // template glyph stays one, so a recycled sidebar row shows the
                                // icon it was rebound to in the same color.
                                if let Some(img) = appkit_image_for(source) {
                                    let template = IMAGE_MODES
                                        .with(|t| t.get(ptr_of(&iv)))
                                        .is_some_and(|m| m.renders_template());
                                    unsafe {
                                        img.setTemplate(template);
                                        iv.setImage(Some(&img));
                                    }
                                }
                            }
                        }
                    }
                }
            }
            kinds::CONTAINER => {
                if let (Some(ContainerPatch::Background(c)), Ok(v)) = (
                    patch.downcast_ref::<ContainerPatch>(),
                    h.clone().downcast::<DayFlipped>(),
                ) {
                    // A background patch only targets a background container (corner radius 0).
                    // The AnimSpec is not honored: the fill is drawRect content
                    // (rasterized by our own drawing code so dynamic system colors re-resolve
                    // per appearance), not a CALayer property, and Core Animation only
                    // interpolates layer properties, so there is nothing for the render server
                    // to tween. Day animates only what the toolkit's animator can execute
                    // (§8.4), so an animated background change applies at commit here.
                    v.set_surface(*c, 0.0, false);
                }
            }
            kinds::LABEL => {
                if let (Some(p), Ok(tf)) = (
                    patch.downcast_ref::<LabelPatch>(),
                    h.clone().downcast::<NSTextField>(),
                ) {
                    match p {
                        LabelPatch::Text(t) => {
                            unsafe { tf.setStringValue(&NSString::from_str(t)) };
                            if let Some(label) = h.downcast_ref::<DayLabel>() {
                                label.ivars().has_runs.set(false);
                                label.set_links(false);
                            }
                        }
                        LabelPatch::Color(c) => unsafe {
                            tf.setTextColor(c.map(nscolor).as_deref())
                        },
                        LabelPatch::Font(f) => unsafe { tf.setFont(Some(&nsfont(*f))) },
                        LabelPatch::Runs(text, runs) => {
                            // The field's current font is the base the runs sit on, taken as the
                            // live object rather than rebuilt from a `FontSpec`, which would lose
                            // the semantic style behind the resolved size.
                            let base = unsafe { tf.font() };
                            let s = match base.as_deref() {
                                Some(f) => {
                                    attributed_label(text, f, None, Default::default(), runs)
                                }
                                None => attributed_label(
                                    text,
                                    &nsfont(day_spec::FontSpec::default()),
                                    None,
                                    Default::default(),
                                    runs,
                                ),
                            };
                            unsafe { tf.setAttributedStringValue(&s) };
                            // Preserve paragraph alignment and activate links introduced by a
                            // reactive markdown update without replacing the native label.
                            set_paragraph_alignment(&tf, unsafe { tf.alignment() });
                            if let Some(label) = h.downcast_ref::<DayLabel>() {
                                label.ivars().has_runs.set(!runs.is_empty());
                                label.set_links(runs.iter().any(|r| r.link.is_some()));
                            }
                        }
                    }
                }
            }
            kinds::BUTTON => {
                if let (Some(p), Ok(btn)) = (
                    patch.downcast_ref::<ButtonPatch>(),
                    h.clone().downcast::<NSButton>(),
                ) {
                    match p {
                        ButtonPatch::Content(c) => {
                            apply_button_content(&btn, &c.title, c.icon.as_ref(), c.icon_only)
                        }
                        ButtonPatch::Title(t) => {
                            let style = BUTTON_STYLES
                                .with(|m| m.borrow().get(&ptr_of(&btn)).copied())
                                .unwrap_or_default();
                            set_button_title(&btn, t, style);
                        }
                        ButtonPatch::Enabled(e) => unsafe { btn.setEnabled(*e) },
                        ButtonPatch::Selected(on) => set_button_selected(&btn, *on),
                        ButtonPatch::Style(s) => apply_button_style(&btn, *s),
                    }
                }
            }
            kinds::TOGGLE => {
                if let (Some(p), Ok(sw)) = (
                    patch.downcast_ref::<TogglePatch>(),
                    h.clone().downcast::<NSSwitch>(),
                ) {
                    match p {
                        TogglePatch::On(on) => {
                            let want = if *on { 1 } else { 0 };
                            if unsafe { sw.state() } != want {
                                unsafe { sw.setState(want) };
                            }
                        }
                        TogglePatch::Enabled(e) => unsafe { sw.setEnabled(*e) },
                    }
                }
            }
            kinds::SLIDER => {
                if let (Some(p), Ok(sl)) = (
                    patch.downcast_ref::<SliderPatch>(),
                    h.clone().downcast::<NSSlider>(),
                ) {
                    match p {
                        SliderPatch::Value(v) => {
                            if (unsafe { sl.doubleValue() } - v).abs() > 0.001 {
                                unsafe { sl.setDoubleValue(*v) };
                            }
                        }
                        SliderPatch::Enabled(e) => unsafe { sl.setEnabled(*e) },
                    }
                }
            }
            kinds::PROGRESS => {
                if let Some(p @ ProgressPatch::Animating(_)) = patch.downcast_ref::<ProgressPatch>()
                {
                    crate::controls::spinner::update(self, h, p);
                    return;
                }

                if let (Some(ProgressPatch::Value(v)), Ok(pi)) = (
                    patch.downcast_ref::<ProgressPatch>(),
                    h.clone().downcast::<NSProgressIndicator>(),
                ) {
                    unsafe {
                        match v {
                            Some(val) => {
                                if pi.isIndeterminate() {
                                    pi.stopAnimation(None);
                                    pi.setIndeterminate(false);
                                    pi.setStyle(NSProgressIndicatorStyle::Bar);
                                    pi.setMinValue(0.0);
                                    pi.setMaxValue(1.0);
                                }
                                if (pi.doubleValue() - val).abs() > 0.0001 {
                                    pi.setDoubleValue(*val);
                                }
                            }
                            None => {
                                pi.setIndeterminate(true);
                                pi.setStyle(NSProgressIndicatorStyle::Spinning);
                                pi.startAnimation(None);
                            }
                        }
                    }
                }
            }
            kinds::NAV_MENU => {
                if let Some(NavMenuPatch::Items {
                    items,
                    icons,
                    badges,
                    badge_icons,
                    badge_tints,
                    sections,
                    tints,
                    menus,
                    movable,
                    sorted,
                    selected,
                    rows_changed,
                    ..
                }) = patch.downcast_ref::<NavMenuPatch>()
                {
                    NAV_MENUS.with(|m| {
                        let m = m.borrow();
                        let Some((outline, data)) = m.get(&ptr_of(h)) else {
                            return;
                        };
                        *data.ivars().movable.borrow_mut() = movable.clone();
                        *data.ivars().sorted.borrow_mut() = sorted.clone();
                        data.set_items(
                            items,
                            icons,
                            badges,
                            badge_icons,
                            badge_tints,
                            sections,
                            tints,
                            menus,
                        );
                        data.ivars().suppress.set(true);
                        // The same rows with new words or counts: reload just those rows, which
                        // keeps the selection and every other row's view.
                        if let Some(rows) = rows_changed {
                            let set = objc2_foundation::NSMutableIndexSet::new();
                            for row in rows.iter().filter_map(|i| data.row_of_item(*i)) {
                                unsafe { set.addIndex(row) };
                            }
                            unsafe {
                                outline.reloadDataForRowIndexes_columnIndexes(
                                    &set,
                                    &objc2_foundation::NSIndexSet::indexSetWithIndex(0),
                                )
                            };
                            data.ivars().suppress.set(false);
                            return;
                        }
                        unsafe {
                            outline.reloadData();
                            match selected.and_then(|i| data.row_of_item(i)) {
                                Some(row) => outline.selectRowIndexes_byExtendingSelection(
                                    &objc2_foundation::NSIndexSet::indexSetWithIndex(row),
                                    false,
                                ),
                                None => outline.deselectAll(None),
                            }
                        }
                        data.ivars().suppress.set(false);
                    });
                    // The rows are a tabs host's labels where the menu sits in one.
                    adopt_menu_for_tabs(self.mtm(), h);
                } else if let Some(NavMenuPatch::IconProgress(progress)) =
                    patch.downcast_ref::<NavMenuPatch>()
                {
                    NAV_MENUS.with(|menus| {
                        let menus = menus.borrow();
                        let Some((outline, data)) = menus.get(&ptr_of(h)) else {
                            return;
                        };
                        let previous = data.ivars().icon_progress.replace(progress.clone());
                        for (row, item) in data.ivars().rows.borrow().iter().enumerate() {
                            let Some(index) = item else {
                                continue;
                            };
                            let value = progress.iter().find(|(i, _)| i == index).map(|(_, v)| *v);
                            if previous.iter().find(|(i, _)| i == index).map(|(_, v)| *v) == value {
                                continue;
                            }
                            if let Some(view) = unsafe {
                                outline.viewAtColumn_row_makeIfNecessary(0, row as isize, false)
                            } && let Some(cell) =
                                view.downcast_ref::<objc2_app_kit::NSTableCellView>()
                                && let Some(icon) = unsafe { cell.imageView() }
                            {
                                nav_progress::update(&icon, value);
                            }
                        }
                    });
                } else if let Some(NavMenuPatch::Selected(sel)) =
                    patch.downcast_ref::<NavMenuPatch>()
                {
                    NAV_MENUS.with(|m| {
                        let m = m.borrow();
                        let Some((outline, data)) = m.get(&ptr_of(h)) else {
                            return;
                        };
                        data.ivars().suppress.set(true);
                        unsafe {
                            match sel.and_then(|i| data.row_of_item(i)) {
                                Some(row) => outline.selectRowIndexes_byExtendingSelection(
                                    &objc2_foundation::NSIndexSet::indexSetWithIndex(row),
                                    false,
                                ),
                                None => outline.deselectAll(None),
                            }
                        }
                        data.ivars().suppress.set(false);
                    });
                }
            }
            kinds::INSPECTOR => {
                if let Some(InspectorPatch::Visible(v)) = patch.downcast_ref::<InspectorPatch>() {
                    INSPECTOR_STATE.with(|m| {
                        if let Some(state) = m.borrow().get(&ptr_of(h)) {
                            // Directly, not through the animator proxy: a screenshot must not
                            // catch a mid-animation pane (the sidebar-toggle rule).
                            state.panel_item.setCollapsed(!*v);
                        }
                    });
                }
            }
            kinds::SPLIT => {
                if let Some(p) = patch.downcast_ref::<SplitPatch>() {
                    SPLIT_STATE.with(|m| {
                        let m = m.borrow();
                        let Some(state) = m.get(&ptr_of(h)) else {
                            return;
                        };
                        let iv = state.delegate.ivars();
                        match p {
                            SplitPatch::Fraction(f) => {
                                iv.share.set(f.clamp(0.0, 1.0));
                                if iv.positioned.get() {
                                    split_place(&state.split, iv);
                                }
                            }
                            SplitPatch::Axis(axis) => unsafe {
                                state
                                    .split
                                    .setVertical(*axis == day_spec::props::SplitAxis::Horizontal);
                                state.split.adjustSubviews();
                                if iv.positioned.get() {
                                    split_place(&state.split, iv);
                                }
                            },
                        }
                    });
                }
            }
            kinds::NAV => {
                if let Some(NavPatch::Presentation(next)) = patch.downcast_ref::<NavPatch>() {
                    nav_present(self.mtm(), h, *next);
                    return;
                }
                if let Some(p) = patch.downcast_ref::<NavPatch>() {
                    NAV_STATE.with(|m| {
                        let mut m = m.borrow_mut();
                        let Some(state) = m.get_mut(&ptr_of(h)) else {
                            return;
                        };
                        match p {
                            NavPatch::Pushed { title, .. } => {
                                // Only the new top detail page stays visible.
                                let last = state.pages.len().saturating_sub(1);
                                state.selected = last;
                                for (i, page) in state.pages.iter().enumerate() {
                                    page.setHidden(i != last);
                                }
                                if let Some(hdr) = state.header.as_mut() {
                                    hdr.titles.push(title.clone());
                                    sync_nav_header(hdr, &state.detail_wrap, &state.pages);
                                }
                            }
                            NavPatch::Popped => {
                                // Hide the outgoing top; reveal its predecessor (Day
                                // removes the popped page right after this patch).
                                let n = state.pages.len();
                                if let Some(top) = state.pages.last() {
                                    top.setHidden(true);
                                }
                                if n >= 2 {
                                    state.pages[n - 2].setHidden(false);
                                }
                                state.selected = n.saturating_sub(2);
                                if let Some(hdr) = state.header.as_mut() {
                                    if hdr.titles.len() > 1 {
                                        hdr.titles.pop();
                                    }
                                    // The popped page is still in `pages` here (Day removes
                                    // it right after this patch), so frame for depth-after-pop.
                                    let after: Vec<Retained<NSView>> = state
                                        .pages
                                        .iter()
                                        .take(n.saturating_sub(1))
                                        .cloned()
                                        .collect();
                                    sync_nav_header(hdr, &state.detail_wrap, &after);
                                }
                            }
                            NavPatch::Title(t) => {
                                if let Some(hdr) = state.header.as_mut() {
                                    if let Some(last) = hdr.titles.last_mut() {
                                        *last = t.clone();
                                    }
                                    unsafe {
                                        hdr.title.setStringValue(&NSString::from_str(t));
                                    }
                                }
                            }
                            // The custom back header always routes back through Day
                            // (NavBack{already_popped:false}), so there is no native auto-pop to
                            // suppress; the guard runs in the pieces layer (docs/navigation.md).
                            NavPatch::GuardTop(_) => {}
                            NavPatch::Reorder(order) => {
                                let old = state.pages.clone();
                                state.pages =
                                    order.iter().filter_map(|i| old.get(*i).cloned()).collect();
                                if let Some(tabs) = &state.tabs {
                                    TAB_PICK_SUPPRESS.with(|s| s.set(true));
                                    unsafe {
                                        let items = tabs.view.tabViewItems();
                                        for item in items.iter() {
                                            tabs.view.removeTabViewItem(&item);
                                        }
                                        for i in order {
                                            if let Some(item) = items.iter().nth(*i) {
                                                tabs.view.addTabViewItem(&item);
                                            }
                                        }
                                    }
                                    TAB_PICK_SUPPRESS.with(|s| s.set(false));
                                }
                            }
                            // Handled outside this borrow (it re-homes views and builds chrome).
                            NavPatch::Presentation(_) => {}
                            // Resident-page switch (docs/navigation.md): every page stays in the
                            // view hierarchy and only one is unhidden, so switching tabs keeps
                            // each page's scroll position and first responder exactly as left.
                            NavPatch::Select(i) => {
                                state.selected = *i;
                                match state.tabs.as_ref() {
                                    // The tab view shows exactly its selected item's page.
                                    Some(tabs) => {
                                        let n = unsafe { tabs.view.numberOfTabViewItems() };
                                        if (*i as isize) < n {
                                            TAB_PICK_SUPPRESS.with(|s| s.set(true));
                                            unsafe {
                                                tabs.view.selectTabViewItemAtIndex(*i as isize)
                                            };
                                            TAB_PICK_SUPPRESS.with(|s| s.set(false));
                                        }
                                    }
                                    None => {
                                        for (n, page) in state.pages.iter().enumerate() {
                                            page.setHidden(n != *i);
                                        }
                                    }
                                }
                            }
                            // Per-destination pane visibility (docs/navigation.md). Directly,
                            // not through the animator proxy: a screenshot must not catch a
                            // mid-animation pane (the sidebar-toggle rule), and settled now,
                            // like a re-present, so the detail's frame is right the instant
                            // the patch returns rather than one layout pass later.
                            NavPatch::ListVisible(v) => {
                                state.list_visible = *v;
                                if let Some(item) = state.list_item.as_ref() {
                                    item.setCollapsed(!*v);
                                    let split = unsafe { state._split_vc.splitView() };
                                    unsafe { split.layoutSubtreeIfNeeded() };
                                    // First time this pane is actually on screen: give it the
                                    // width the app asked for. The frame pass that would
                                    // otherwise do it has already run, back when there was no
                                    // pane to size.
                                    if let Some(w) = take_list_placement(state) {
                                        unsafe {
                                            split.setPosition_ofDividerAtIndex(
                                                day_spec::NAV_SIDEBAR_WIDTH + w,
                                                1,
                                            );
                                        }
                                    }
                                    // Re-frame the pane's page to the wrap it fills. A page
                                    // inserted while the pane was collapsed got a zero-width
                                    // frame, and `ViewWidthSizable` scales zero to zero however
                                    // wide the wrap becomes, so the list stayed invisible while
                                    // its rows were still there to click. An app opening on a
                                    // full-page section hits this on the first reveal.
                                    if *v
                                        && let Some(wrap) = state.list_wrap.as_ref()
                                        && let Some(page) = state.list_page.as_ref()
                                    {
                                        unsafe {
                                            wrap.layoutSubtreeIfNeeded();
                                            page.setFrame(wrap.bounds());
                                        }
                                    }
                                }
                            }
                            // Never arrives here: the pane persists through every presentation
                            // (`Cap::NavContentList` = Native), so the pieces layer never asks
                            // for the merged-stack shape.
                            NavPatch::ListInStack(_) => {}
                        }
                    });
                }
            }
            // Emulated cover (docs/cover.md): present = re-home onto the window's content view
            // at full bounds, topmost, autoresized with the window (the DayNavPage handle
            // reports FrameChanged on every resize). Dismiss = hide + report `CoverHidden`
            // immediately (no transition on this tier). Interactive dismissal doesn't exist on
            // this backend, so DismissDisabled has nothing to disable.
            kinds::COVER => {
                if let (Some(p), Ok(page)) = (
                    patch.downcast_ref::<CoverPatch>(),
                    h.clone().downcast::<DayNavPage>(),
                ) {
                    let node = page.ivars().node;
                    match p {
                        CoverPatch::Present { background, .. } => {
                            if page.ivars().sheet.get() {
                                if let Some(parent) =
                                    primary_content().and_then(|v| unsafe { v.window() })
                                {
                                    let bounds = parent.frame().size;
                                    let height = if page.ivars().half.get() {
                                        (bounds.height * 0.5).clamp(160.0, 620.0)
                                    } else {
                                        (bounds.height - 80.0).clamp(300.0, 620.0)
                                    };
                                    let size = NSSize::new(
                                        (bounds.width - 40.0).clamp(320.0, 640.0),
                                        height,
                                    );
                                    let window = unsafe {
                                        NSWindow::initWithContentRect_styleMask_backing_defer(
                                            NSWindow::alloc(MainThreadMarker::new().unwrap()),
                                            NSRect::new(NSPoint::new(0.0, 0.0), size),
                                            NSWindowStyleMask::Titled,
                                            NSBackingStoreType::Buffered,
                                            false,
                                        )
                                    };
                                    unsafe {
                                        window.setReleasedWhenClosed(false);
                                        page.removeFromSuperview();
                                        page.setHidden(false);
                                        page.setFrame(NSRect::new(NSPoint::new(0.0, 0.0), size));
                                        window.setContentView(Some(&page));
                                    }
                                    let key = ptr_of(h);
                                    COVER_SHEETS.with(|t| t.insert(key, CoverSheet(window)));
                                    dispatch2::DispatchQueue::main().exec_async(move || {
                                        ffi_guard::contain((), || {
                                            let window =
                                                COVER_SHEETS.with(|t| t.with(key, |s| s.0.clone()));
                                            if let (Some(window), Some(parent)) = (
                                                window,
                                                primary_content()
                                                    .and_then(|v| unsafe { v.window() }),
                                            ) {
                                                unsafe {
                                                    parent.beginSheet_completionHandler(
                                                        &window, None,
                                                    );
                                                }
                                            }
                                        });
                                    });
                                    emit(
                                        node,
                                        Event::FrameChanged(Size::new(size.width, size.height)),
                                    );
                                }
                                return;
                            }
                            // A cover must occlude the window (the native tiers' modal surfaces
                            // are opaque): default to the window background when the app sets
                            // no explicit color.
                            unsafe {
                                page.setWantsLayer(true);
                                if let Some(layer) = page.layer() {
                                    let color = match background {
                                        Some(bg) => nscolor(*bg),
                                        None => NSColor::windowBackgroundColor(),
                                    };
                                    layer.setBackgroundColor(Some(&color.CGColor()));
                                }
                            }
                            // The primary window's content, specifically: firstObject()
                            // is arbitrary once secondary windows exist (docs/windows.md).
                            if let Some(content) = primary_content() {
                                if let Some(window) = unsafe { content.window() } {
                                    toolbar::cover_presented(ptr_of(h), &window);
                                }
                                // Edge to edge like the root's own background, laid out below
                                // the title bar like the root's content: the page starts at the
                                // top of the window (above the pinned content origin) and
                                // keeps the same strip above its own layout origin.
                                let top = title_bar_inset(&content);
                                let full = content.frame().size;
                                page.ivars().top_inset.set(top);
                                unsafe {
                                    page.removeFromSuperview();
                                    content.addSubview(&page);
                                    page.setFrame(NSRect::new(
                                        NSPoint::new(0.0, -top),
                                        NSSize::new(full.width, full.height),
                                    ));
                                    page.setBoundsOrigin(NSPoint::new(0.0, -top));
                                    page.setAutoresizingMask(
                                        objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable
                                            | objc2_app_kit::NSAutoresizingMaskOptions::ViewHeightSizable,
                                    );
                                    page.setHidden(false);
                                }
                                emit(
                                    node,
                                    Event::FrameChanged(Size::new(
                                        full.width,
                                        (full.height - top).max(0.0),
                                    )),
                                );
                            }
                        }
                        CoverPatch::DismissDisabled(_) => {}
                        CoverPatch::Dismiss => {
                            COVER_SHEETS.with(|t| drop(t.remove(ptr_of(h))));
                            toolbar::cover_dismissed(ptr_of(h));
                            unsafe {
                                page.setHidden(true);
                                page.removeFromSuperview();
                            }
                            emit(node, Event::CoverHidden);
                        }
                    }
                }
            }
            kinds::PICKER => picker::update_any(self, h, patch),
            kinds::TEXT_AREA => textarea::update_any(self, h, patch),
            kinds::TEXT_FIELD => {
                if let (Some(p), Ok(tf)) = (
                    patch.downcast_ref::<TextFieldPatch>(),
                    h.clone().downcast::<NSTextField>(),
                ) {
                    match p {
                        TextFieldPatch::Text { text, from_native } => {
                            // Origin-tagged echo suppression (§4.4).
                            if !*from_native && unsafe { tf.stringValue() }.to_string() != *text {
                                unsafe { tf.setStringValue(&NSString::from_str(text)) };
                            }
                        }
                        TextFieldPatch::Placeholder(t) => unsafe {
                            tf.setPlaceholderString(Some(&NSString::from_str(t)))
                        },
                        TextFieldPatch::Enabled(e) => unsafe { tf.setEnabled(*e) },
                    }
                }
            }
            kinds::LIST => match patch.downcast_ref::<ListPatch>() {
                Some(ListPatch::Splice(deltas)) => {
                    // The set changed by exactly these deltas: animate each row in, out, or
                    // across, the thing a reload cannot express. Indexes are sequential, so
                    // each delta gets its own begin/endUpdates batch (NSTableView's combined
                    // batch semantics re-interpret indexes; one-at-a-time stays literal).
                    // Row realization stays deferred, as with Reload.
                    if let Some((table, data)) = list_entry(ptr_of(h)) {
                        use objc2_app_kit::NSTableViewAnimationOptions;
                        for d in deltas {
                            unsafe {
                                table.beginUpdates();
                                match d {
                                    day_spec::props::RowDelta::Insert(i) => table
                                        .insertRowsAtIndexes_withAnimation(
                                            &objc2_foundation::NSIndexSet::indexSetWithIndex(*i),
                                            NSTableViewAnimationOptions::SlideDown,
                                        ),
                                    day_spec::props::RowDelta::Remove(i) => table
                                        .removeRowsAtIndexes_withAnimation(
                                            &objc2_foundation::NSIndexSet::indexSetWithIndex(*i),
                                            NSTableViewAnimationOptions::SlideUp,
                                        ),
                                    day_spec::props::RowDelta::Move(from, to) => {
                                        table.moveRowAtIndex_toIndex(*from as isize, *to as isize)
                                    }
                                }
                                table.endUpdates();
                            }
                        }
                        // The displayed order matches the source again: refresh the cache a
                        // committed drag keeps in step and `permutation_moves` compares, or the
                        // next Reload finds a stale length and reloads flat instead of animating.
                        if let Some(source) = data.ivars().source.borrow().as_ref() {
                            let n = (source.len)();
                            *data.ivars().tokens.borrow_mut() =
                                (0..n).map(|i| (source.token_at)(i)).collect();
                        }
                    }
                    post_realize_visible_rows(ptr_of(h));
                }
                Some(ListPatch::Reload) => {
                    if let Some((table, data)) = list_entry(ptr_of(h)) {
                        // NSTableView reloadData clears selection for this view-based source.
                        // Preserve identities, not indexes, across refreshes/reorders; removed
                        // items disappear from the selection without selecting their successor.
                        let selected = unsafe { table.selectedRowIndexes() };
                        let tokens: Vec<u64> = data
                            .ivars()
                            .tokens
                            .borrow()
                            .iter()
                            .enumerate()
                            .filter(|(row, _)| selected.containsIndex(*row))
                            .map(|(_, token)| *token)
                            .collect();
                        data.ivars().suppress.set(true);
                        // A reload whose rows are the same set in a new order (a shuffle,
                        // a programmatic sort) animates as native row moves instead of a
                        // blink: a `moveRowAtIndex` batch, the same animation a drag commit
                        // gets. Anything else (insert/remove/content change) reloads flat.
                        // reloadData queries numberOfRows synchronously (snapshot only, no
                        // tree) and defers viewForRow, so both paths are safe in with_tree.
                        if let Some(moves) = data.permutation_moves(&table) {
                            unsafe {
                                table.beginUpdates();
                                for (from, to) in moves {
                                    table.moveRowAtIndex_toIndex(from as isize, to as isize);
                                }
                                table.endUpdates();
                            }
                        } else {
                            unsafe { table.reloadData() };
                        }
                        let restored = objc2_foundation::NSMutableIndexSet::new();
                        for (row, token) in data.ivars().tokens.borrow().iter().enumerate() {
                            if tokens.contains(token) {
                                restored.addIndex(row);
                            }
                        }
                        unsafe { table.selectRowIndexes_byExtendingSelection(&restored, false) };
                        data.ivars().suppress.set(false);
                    }
                    // Realize the visible rows on the next main-loop turn, outside this borrow.
                    // An occluded window (locked screen, covered, headless CI) gets no normal
                    // draw pass; NSTableView would first realize these rows inside a snapshot's
                    // `cacheDisplayInRect`, where `bind_row` must skip the held borrow and the
                    // table would cache permanently blank cells.
                    post_realize_visible_rows(ptr_of(h));
                }
                Some(ListPatch::ScrollToRow(row)) => {
                    // Same deferral discipline as ScrollToEnd: the scroll tiles target rows
                    // synchronously, which must happen outside this `with_tree` borrow.
                    let (key, row) = (ptr_of(h), *row);
                    <AppKit as Platform>::post(Box::new(move || {
                        if let Some((table, _)) = list_entry(key) {
                            let rows = unsafe { table.numberOfRows() };
                            if rows > 0 {
                                unsafe { table.scrollRowToVisible((row as isize).min(rows - 1)) };
                            }
                        }
                    }));
                    post_realize_visible_rows(ptr_of(h));
                }
                Some(ListPatch::ScrollToEnd) => {
                    // Deferred to the next main-loop turn: an actual scroll forces NSTableView
                    // to tile (realize) the target rows synchronously, and this patch arrives
                    // inside a `with_tree` borrow where `bind_row` must skip; the table would
                    // cache blank cells for every newly exposed row (see Reload above).
                    let key = ptr_of(h);
                    <AppKit as Platform>::post(Box::new(move || {
                        if let Some((table, _)) = list_entry(key) {
                            let rows = unsafe { table.numberOfRows() };
                            if rows > 0 {
                                unsafe { table.scrollRowToVisible(rows - 1) };
                            }
                        }
                    }));
                    // ...and realize whatever the scroll exposed, still outside the borrow.
                    post_realize_visible_rows(ptr_of(h));
                }
                Some(ListPatch::Selected(rows)) => {
                    // Programmatic selection sync (empty = clear), suppressed so the
                    // delegate does not echo it back as a selection event.
                    if let Some((table, data)) = list_entry(ptr_of(h)) {
                        data.ivars().suppress.set(true);
                        unsafe {
                            if rows.is_empty() {
                                table.deselectAll(None);
                            } else {
                                let set = objc2_foundation::NSMutableIndexSet::new();
                                let count = table.numberOfRows().max(0) as usize;
                                for r in rows.iter().copied().filter(|r| *r < count) {
                                    set.addIndex(r);
                                }
                                table.selectRowIndexes_byExtendingSelection(&set, false);
                            }
                        }
                        data.ivars().suppress.set(false);
                    }
                }
                Some(ListPatch::RowSizeInvalidated { cell, height }) => {
                    if let Some((table, data)) = list_entry(ptr_of(h)) {
                        data.row_resized(&table, *cell, *height);
                    }
                }
                // `None` = a patch for another kind's enum. A desktop table has no editing mode
                // (Cap::ListEditing is Unsupported).
                Some(ListPatch::Editing(_)) | None => {}
            },
            kinds::TREE => match patch.downcast_ref::<TreePatch>() {
                Some(TreePatch::Reload) => {
                    // Interned items keep their identity across reloadData, so NSOutlineView
                    // itself preserves expansion; the piece re-asserts it (and the selection)
                    // by token right after, belt and braces. reloadData queries the child
                    // counts synchronously (snapshot only, no tree) and defers viewForItem.
                    if let Some((outline, _)) = tree_entry(ptr_of(h)) {
                        unsafe { outline.reloadData() };
                    }
                    post_realize_visible_tree_rows(ptr_of(h));
                }
                Some(TreePatch::Expand(token, on)) => {
                    // Deferred: expandItem/collapseItem realize (or remove) the disclosed
                    // rows synchronously, and this patch arrives inside a `with_tree` borrow
                    // where `bind_row` must skip; the outline would cache permanently blank,
                    // id-less rows (the ScrollToEnd rule, one arm over).
                    let (key, token, on) = (ptr_of(h), *token, *on);
                    <AppKit as Platform>::post(Box::new(move || {
                        if let Some((outline, data)) = tree_entry(key) {
                            let item = data.intern(token);
                            // Suppressed: a programmatic disclosure must not echo back as
                            // `Event::TreeExpanded`. Redundant applications are AppKit no-ops.
                            data.ivars().suppress.set(true);
                            unsafe {
                                if on {
                                    outline.expandItem(Some(&item));
                                } else {
                                    outline.collapseItem(Some(&item));
                                }
                            }
                            data.ivars().suppress.set(false);
                        }
                        day_core::pump_events();
                    }));
                    post_realize_visible_tree_rows(ptr_of(h));
                }
                Some(TreePatch::Selected(tokens)) => {
                    if let Some((outline, data)) = tree_entry(ptr_of(h)) {
                        data.ivars().suppress.set(true);
                        unsafe {
                            if tokens.is_empty() {
                                outline.deselectAll(None);
                            } else {
                                let set = objc2_foundation::NSMutableIndexSet::new();
                                for t in tokens {
                                    // A token under a collapsed ancestor has no row, so it is
                                    // skipped; the piece re-applies after expansion changes.
                                    let row = outline.rowForItem(Some(&data.intern(*t)));
                                    if row >= 0 {
                                        set.addIndex(row as usize);
                                    }
                                }
                                outline.selectRowIndexes_byExtendingSelection(&set, false);
                            }
                        }
                        data.ivars().suppress.set(false);
                    }
                }
                Some(TreePatch::Reveal(token)) => {
                    // Deferred: the scroll tiles target rows synchronously, which must
                    // happen outside this `with_tree` borrow (the ScrollToRow rule).
                    let (key, token) = (ptr_of(h), *token);
                    <AppKit as Platform>::post(Box::new(move || {
                        if let Some((outline, data)) = tree_entry(key) {
                            let row = unsafe { outline.rowForItem(Some(&data.intern(token))) };
                            if row >= 0 {
                                unsafe { outline.scrollRowToVisible(row) };
                            }
                        }
                    }));
                    post_realize_visible_tree_rows(ptr_of(h));
                }
                None => {}
            },
            _ => {
                if let Some(update) = self.registry.get(kind).map(|r| r.update) {
                    update(self, h, patch);
                }
            }
        }
    }

    /// Offer a satellite piece its teardown hook before `release` frees the handle (§15.2).
    fn release_piece(&mut self, kind: day_spec::PieceKind, h: &Self::Handle) {
        // Copy the fn pointer out first: the registry lookup borrows `self` immutably and
        // the hook needs it mutably.
        let f = self.registry.get(kind).and_then(|r| r.release);
        if let Some(f) = f {
            f(self, h);
        }
    }
    fn release(&mut self, h: Handle) {
        LIST_ITEMS.with(|m| m.borrow_mut().remove(&ptr_of(&h)));
        // A released window content = that window is gone (docs/windows.md teardown):
        // drop the SecondaryWin (closing a straggler NSWindow) and its delegate with it.
        // (A re-fired windowWillClose emits to a torn-down node: dropped, harmless.)
        self.secondary.retain(|w| {
            if ptr_of(&w.content) == ptr_of(&h) {
                w.window.close();
                // The window's keyed state goes with it: its toolbar (toolbar.rs BARS,
                // keyed by the window pointer) used to survive a secondary close, and its
                // items, targets, retained NSToolbar and delegate all leaked.
                day_spec::sidetable::sweep(Retained::as_ptr(&w.window) as usize);
                false
            } else {
                true
            }
        });
        TARGETS.with(|m| {
            m.borrow_mut().remove(&ptr_of(&h));
        });
        LIST_STATE.with(|m| {
            m.borrow_mut().remove(&ptr_of(&h));
        });
        TREE_STATE.with(|m| {
            m.borrow_mut().remove(&ptr_of(&h));
        });
        GESTURES.with(|m| {
            m.borrow_mut().remove(&ptr_of(&h));
        });
        NAV_STATE.with(|m| {
            if let Some(nav) = m.borrow_mut().remove(&ptr_of(&h)) {
                // Unhook the split view controller from the responder chain before the drop
                // deallocs it. AppKit rewires these pointers behind day's back (mounting the
                // split resets its next to the superview; the controller's own view keeps
                // aiming at the controller), and a controller whose next responder is its own
                // view dies in dealloc's chain splice with the "next responder should never
                // be yourself" NSException, foreign to Rust, so it aborts the process
                // instead of unwinding (the Stack-page teardown crash, 2026-08).
                unsafe {
                    nav._split_vc.setNextResponder(None);
                    let split = nav._split_vc.splitView();
                    if split.nextResponder().is_some_and(|r| {
                        core::ptr::eq::<objc2::runtime::AnyObject>(
                            r.as_ref(),
                            nav._split_vc.as_ref(),
                        )
                    }) {
                        split.setNextResponder(None);
                    }
                }
            }
        });
        NAV_PAGES.with(|set| {
            set.borrow_mut().remove(&ptr_of(&h));
        });
        SPLIT_STATE.with(|m| {
            if let Some(state) = m.borrow_mut().remove(&ptr_of(&h)) {
                state.split.setDelegate(None);
            }
        });
        INSPECTOR_STATE.with(|m| {
            if let Some(insp) = m.borrow_mut().remove(&ptr_of(&h)) {
                // The same dealloc-splice guard as the nav host above: never let the
                // controller (or its split) dealloc aiming at itself.
                unsafe {
                    insp._split_vc.setNextResponder(None);
                    let split = insp._split_vc.splitView();
                    if split.nextResponder().is_some_and(|r| {
                        core::ptr::eq::<objc2::runtime::AnyObject>(
                            r.as_ref(),
                            insp._split_vc.as_ref(),
                        )
                    }) {
                        split.setNextResponder(None);
                    }
                }
            }
        });
        NAV_MENUS.with(|m| {
            if let Some((outline, _)) = m.borrow_mut().remove(&ptr_of(&h)) {
                // The outline registers under its pointer (`menuForEvent:` resolves by
                // outline, not by this scroll handle): sweep that auxiliary key too, so
                // NAV_OUTLINE_MENUS, and any future outline-keyed table, drops it. A
                // surviving entry served the dead menu's rows once the address was recycled.
                day_spec::sidetable::sweep(Retained::as_ptr(&outline) as usize);
            }
        });
        // One call reclaims this handle's entry from every SideTable on this thread (canvas
        // OPS, PAGE_PANE, the picker/textarea state, and whatever lands later), running each
        // table's teardown hook (day-spec sidetable). The explicit removals above are the
        // older per-map checklist; new per-view maps should be SideTables so this sweep covers
        // them without another line here.
        day_spec::sidetable::sweep(ptr_of(&h));
        unsafe { h.removeFromSuperview() };
    }

    fn insert(&mut self, parent: &Handle, child: &Handle, _index: usize) {
        // A nav menu that has just gained ancestors: if one of them is a tabs host, its rows
        // Are that host's tab labels (`adopt_menu_for_tabs`). The menu is built after its rows
        // page joined the host, so this is the first moment the host can see its rows.
        if NAV_MENUS.with(|m| m.borrow().contains_key(&ptr_of(child))) {
            unsafe { content_of(parent).addSubview(child) };
            adopt_menu_for_tabs(self.mtm(), child);
            return;
        }
        // Nav host: pages land by their pane, not their position (docs/size-classes.md). Pages
        // fill their pane via autoresizing; the pane, not Day, owns their frames.
        let page_pane = PAGE_PANE.with(|t| t.get(ptr_of(child)));
        let is_sidebar_page = page_pane == Some(day_spec::props::Pane::Sidebar);
        let handled = NAV_STATE.with(|m| {
            let mut m = m.borrow_mut();
            let Some(state) = m.get_mut(&ptr_of(parent)) else {
                return false;
            };
            // The content-list page fills its pane at every presentation
            // (docs/navigation.md), never a member of the detail stack.
            if page_pane == Some(day_spec::props::Pane::List)
                && let Some(wrap) = state.list_wrap.as_ref()
            {
                state.list_page = Some(child.clone());
                unsafe {
                    child.setFrame(wrap.bounds());
                    child.setAutoresizingMask(
                        objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable
                            | objc2_app_kit::NSAutoresizingMaskOptions::ViewHeightSizable,
                    );
                    wrap.addSubview(child);
                }
                return true;
            }
            if is_sidebar_page {
                state.sidebar_page = Some(child.clone());
            }
            // Split (nav host Sidebar): the sidebar pane's page goes in the sidebar; the rest are
            // detail pages. Stack: every page, including the sidebar's, which is the stack's
            // root, lives in the detail pane so push/pop visibility covers them all.
            // The rows page goes to the sidebar pane in every presentation but `Stack`, where
            // it is the stack root and joins the detail pages instead.
            let to_pane = is_sidebar_page && state.presentation != NavPresentation::Stack;
            // A tabs host's detail page becomes an item of its tab view, which frames it (the
            // page's `setFrameSize:` reports the size to Day). Its label comes with the
            // menu's rows: already here when a page joins a live host, otherwise when the
            // menu is inserted (`adopt_menu_for_tabs`).
            if !to_pane && let Some(tabs) = state.tabs.as_ref() {
                state.pages.push(child.clone());
                let item = unsafe { objc2_app_kit::NSTabViewItem::new() };
                unsafe {
                    child.setAutoresizingMask(
                        objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable
                            | objc2_app_kit::NSAutoresizingMaskOptions::ViewHeightSizable,
                    );
                    item.setView(Some(child));
                    tabs.view.addTabViewItem(&item);
                }
                if let Some((titles, _)) = state.sidebar_page.as_deref().and_then(nav_menu_rows) {
                    sync_tab_labels(tabs, &titles, state.selected);
                }
                return true;
            }
            let (wrap, frame) = if to_pane {
                (&state.sidebar_wrap, state.sidebar_wrap.bounds())
            } else {
                state.pages.push(child.clone());
                let visible = state.header.as_ref().is_some_and(|h| !h.bar.isHidden());
                (
                    &state.detail_wrap,
                    nav_page_frame(&state.detail_wrap, visible),
                )
            };
            unsafe {
                child.setFrame(frame);
                child.setAutoresizingMask(
                    objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable
                        | objc2_app_kit::NSAutoresizingMaskOptions::ViewHeightSizable,
                );
                wrap.addSubview(child);
            }
            true
        });
        if handled {
            return;
        }
        // Split host (docs/split.md): each pane fills its wrap, an arranged subview the
        // splitter sizes; the pane's own `setFrameSize:` reports the size to Day.
        let split_pane = SPLIT_STATE.with(|m| {
            let m = m.borrow();
            let Some(state) = m.get(&ptr_of(parent)) else {
                return false;
            };
            let second = SPLIT_PANES.with(|t| t.get(ptr_of(child))).unwrap_or(false);
            let wrap = if second {
                &state.second_wrap
            } else {
                &state.first_wrap
            };
            unsafe {
                child.setFrame(wrap.bounds());
                child.setAutoresizingMask(
                    objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable
                        | objc2_app_kit::NSAutoresizingMaskOptions::ViewHeightSizable,
                );
                wrap.addSubview(child);
            }
            true
        });
        if split_pane {
            return;
        }
        // Inspector host: each pane fills its wrap via autoresizing, the nav-page contract;
        // the split, not Day, owns the pane frames (docs/inspector.md).
        let inspected = INSPECTOR_STATE.with(|m| {
            let m = m.borrow();
            let Some(state) = m.get(&ptr_of(parent)) else {
                return false;
            };
            let panel = INSPECTOR_PANES
                .with(|t| t.get(ptr_of(child)))
                .unwrap_or(false);
            let wrap = if panel {
                &state.panel_wrap
            } else {
                &state.content_wrap
            };
            unsafe {
                child.setFrame(wrap.bounds());
                child.setAutoresizingMask(
                    objc2_app_kit::NSAutoresizingMaskOptions::ViewWidthSizable
                        | objc2_app_kit::NSAutoresizingMaskOptions::ViewHeightSizable,
                );
                wrap.addSubview(child);
            }
            true
        });
        if !inspected {
            // Absolute positioning: z-order is build order; index is irrelevant for
            // non-overlapping frames (stack_z will need ordered insertion later).
            unsafe { content_of(parent).addSubview(child) };
        }
    }

    fn remove(&mut self, parent: &Handle, child: &Handle) {
        PAGE_PANE.with(|t| t.remove(ptr_of(child)));
        let mtm = self.mtm();
        NAV_STATE.with(|m| {
            if let Some(state) = m.borrow_mut().get_mut(&ptr_of(parent)) {
                // A tabs host: the page leaves with its tab item.
                if let Some(tabs) = state.tabs.as_ref() {
                    unsafe {
                        let n = tabs.view.numberOfTabViewItems();
                        for i in 0..n {
                            let item = tabs.view.tabViewItemAtIndex(i);
                            if item.view(mtm).is_some_and(|v| ptr_of(&v) == ptr_of(child)) {
                                tabs.view.removeTabViewItem(&item);
                                break;
                            }
                        }
                    }
                }
                state.pages.retain(|p| ptr_of(p) != ptr_of(child));
                if state.sidebar_page.as_deref().map(ptr_of) == Some(ptr_of(child)) {
                    state.sidebar_page = None;
                }
            }
        });
        unsafe { child.removeFromSuperview() };
    }

    fn move_child(&mut self, parent: &Handle, child: &Handle, _to: usize) {
        unsafe { content_of(parent).addSubview(child) };
    }

    fn measure(&mut self, h: &Handle, kind: PieceKind, p: Proposal) -> Size {
        match kind {
            kinds::LABEL => {
                if let Some(tf) = h.downcast_ref::<NSTextField>() {
                    let w = p.width.unwrap_or(1.0e6);
                    // The field owns maximumNumberOfLines; measuring its cell bypasses it.
                    let s = tf.sizeThatFits(NSSize::new(w, 1.0e6));
                    let mut height = s.height.ceil();
                    // AppKit's truncating single-line mode still measures explicit newlines
                    // as multiple lines. Bound that case using AppKit's own font metrics.
                    if tf.maximumNumberOfLines() == 1 {
                        thread_local! {
                            static METRICS: Retained<objc2_app_kit::NSLayoutManager> = objc2_app_kit::NSLayoutManager::new();
                        }
                        if let Some(font) = unsafe { tf.font() } {
                            height = height.min(
                                METRICS
                                    .with(|metrics| metrics.defaultLineHeightForFont(&font))
                                    .ceil(),
                            );
                        }
                    }
                    return Size::new(s.width.ceil().min(w), height);
                }
                Size::ZERO
            }
            kinds::BUTTON | kinds::TOGGLE => {
                let s = unsafe { h.fittingSize() };
                Size::new(s.width.ceil(), s.height.ceil())
            }
            kinds::SLIDER => {
                let s = unsafe { h.fittingSize() };
                Size::new(p.width.unwrap_or(180.0), s.height.max(21.0).ceil())
            }
            kinds::PICKER => picker::measure_any(self, h, p),
            kinds::TEXT_AREA => textarea::measure_any(self, h, p),
            kinds::TEXT_FIELD => {
                let s = unsafe { h.fittingSize() };
                Size::new(
                    p.width.unwrap_or(s.width.max(160.0)),
                    s.height.max(22.0).ceil(),
                )
            }
            kinds::DIVIDER => Size::new(p.width.unwrap_or(0.0), 5.0),
            // The stack's own fitting size, at least a table row's 28pt; the words truncate to
            // the row's width.
            kinds::LIST_ITEM => {
                let s = h.fittingSize();
                Size::new(p.width.unwrap_or(s.width.ceil()), s.height.ceil().max(28.0))
            }
            kinds::PROGRESS => {
                // Indeterminate spinner is a fixed square; determinate bar fills width.
                let indeterminate = h
                    .clone()
                    .downcast::<NSProgressIndicator>()
                    .map(|pi| unsafe { pi.isIndeterminate() })
                    .unwrap_or(false);
                if indeterminate {
                    let large = h
                        .downcast_ref::<NSProgressIndicator>()
                        .is_some_and(|pi| pi.controlSize() == objc2_app_kit::NSControlSize::Large);
                    let side = if large { 32.0 } else { 20.0 };
                    Size::new(side, side)
                } else {
                    Size::new(p.width.unwrap_or(180.0), 20.0)
                }
            }
            kinds::NAV_MENU => {
                let rows = NAV_MENUS.with(|m| {
                    m.borrow()
                        .get(&ptr_of(h))
                        .map(|(_, d)| d.ivars().items.borrow().len())
                        .unwrap_or(0)
                });
                Size::new(
                    p.width.unwrap_or(220.0),
                    p.height.unwrap_or(rows as f64 * 32.0 + 12.0),
                )
            }
            // The recycling list fills the space it is offered (its native scroll owns overflow).
            kinds::LIST | kinds::TREE => Size::new(p.width.unwrap_or(0.0), p.height.unwrap_or(0.0)),
            _ => {
                if let Some(measure) = self.registry.get(kind).and_then(|r| r.measure) {
                    measure(self, h, p)
                } else {
                    let s = unsafe { h.fittingSize() };
                    Size::new(p.width.unwrap_or(s.width), p.height.unwrap_or(s.height))
                }
            }
        }
    }

    fn set_opacity(&mut self, h: &Handle, opacity: f64, anim: Option<&AnimSpec>) {
        unsafe {
            h.setWantsLayer(true);
        }
        let v = h.clone();
        with_appkit_anim(anim, move || unsafe { v.setAlphaValue(opacity) });
    }

    fn set_transform(&mut self, h: &Handle, t: Transform, _size: Size, anim: Option<&AnimSpec>) {
        // Expressed in the view's own geometry (see `TRANSFORMS`), so hit-testing follows the
        // drawing, as UIKit's does. Without a laid-out frame yet, `set_frame` applies it.
        TRANSFORMS.with(|m| m.insert(ptr_of(h), t));
        let base = BASE_FRAMES.with(|m| m.get(ptr_of(h)));
        let v = h.clone();
        with_appkit_anim(anim, move || {
            if let Some(base) = base {
                apply_geometry(&v, base, t);
            }
        });
    }

    fn set_selectable(&mut self, h: &Handle, selectable: bool) -> Option<Handle> {
        if let Some(label) = h.downcast_ref::<DayLabel>() {
            label.ivars().selectable.set(selectable);
            label.set_links(label.ivars().has_links.get());
        } else if let Some(tf) = h.downcast_ref::<NSTextField>() {
            unsafe { tf.setSelectable(selectable) };
        }
        None
    }

    fn set_input_traits(&mut self, h: &Handle, traits: &InputTraits) -> Option<Handle> {
        let node = text_field_node(h)?;
        let old = h.downcast_ref::<NSTextField>()?;
        // Hidden characters are a class on AppKit. A field already of the right class is
        // dressed in place; otherwise its replacement is, and the node moves to it.
        let swapped = (h.downcast_ref::<DaySecureTextField>().is_some() != traits.secure)
            .then(|| self.swap_text_field(h, old, node, traits.secure));
        let tf = swapped.as_deref().unwrap_or(old);
        unsafe {
            // Read-only keeps the bezel and the ordinary text color; the text stays
            // selectable, so it can still be copied.
            tf.setEditable(!traits.read_only);
            tf.setSelectable(true);
        }
        // The purpose is AutoFill's hint on the desktop: which saved credential or contact
        // detail the system offers. `Number` and `Decimal` have no content type. A constant
        // newer than the running system leaves the field untyped.
        let content_type = match traits.purpose {
            InputPurpose::Text | InputPurpose::Number | InputPurpose::Decimal => None,
            InputPurpose::Name => text_content_type(c"NSTextContentTypeName"),
            InputPurpose::Email => text_content_type(c"NSTextContentTypeEmailAddress"),
            InputPurpose::Url => text_content_type(c"NSTextContentTypeURL"),
            InputPurpose::Phone => text_content_type(c"NSTextContentTypeTelephoneNumber"),
            InputPurpose::Username => text_content_type(c"NSTextContentTypeUsername"),
            InputPurpose::Password => text_content_type(c"NSTextContentTypePassword"),
            InputPurpose::NewPassword => text_content_type(c"NSTextContentTypeNewPassword"),
            InputPurpose::OneTimeCode => text_content_type(c"NSTextContentTypeOneTimeCode"),
        };
        unsafe {
            tf.setContentType(content_type);
            // Only free text wants the system finishing words; a name, an address or a code
            // is typed exactly.
            tf.setAutomaticTextCompletionEnabled(traits.purpose == InputPurpose::Text);
        }
        // No on-screen keyboard, so no action key to label; and no native length limit:
        // day-pieces holds `max_length`.
        swapped.map(view_of)
    }

    fn set_cursor(&mut self, h: &Handle, cursor: Cursor) {
        let key = Retained::as_ptr(h) as usize;
        if cursor == Cursor::Default {
            // Release: drop the tracking area, and the hide if this owner holds one.
            if let Some((owner, area)) = self.cursors.remove(&key) {
                unsafe { h.removeTrackingArea(&area) };
                if owner.ivars().hiding.replace(false) {
                    NSCursor::unhide();
                }
            }
            return;
        }
        let hidden = cursor == Cursor::None;
        let shape = if hidden { None } else { ns_cursor(&cursor) };
        let mtm = self.mtm;
        let (owner, _) = self.cursors.entry(key).or_insert_with(|| {
            let owner = DayCursorOwner::new(mtm);
            // InVisibleRect: the area follows the view's bounds, so no rect to keep in step
            // with layout. ActiveInKeyWindow: the shape belongs to the window taking input.
            let opts = NSTrackingAreaOptions::CursorUpdate
                | NSTrackingAreaOptions::MouseEnteredAndExited
                | NSTrackingAreaOptions::ActiveInKeyWindow
                | NSTrackingAreaOptions::InVisibleRect;
            let any: &objc2::runtime::AnyObject = &owner;
            let area = unsafe {
                NSTrackingArea::initWithRect_options_owner_userInfo(
                    NSTrackingArea::alloc(),
                    NSRect::ZERO,
                    opts,
                    Some(any),
                    None,
                )
            };
            unsafe { h.addTrackingArea(&area) };
            (owner, area)
        });
        let changed = {
            let iv = owner.ivars();
            let same = match (iv.cursor.borrow().as_ref(), shape.as_ref()) {
                (Some(a), Some(b)) => Retained::as_ptr(a) == Retained::as_ptr(b),
                (None, None) => true,
                _ => false,
            };
            *iv.cursor.borrow_mut() = shape;
            let was_hidden = iv.hidden.replace(hidden);
            !same || was_hidden != hidden
        };
        // A reactive change while the pointer is already inside: AppKit only asks on entry,
        // so ask it to re-evaluate now.
        if changed && let Some(w) = h.window() {
            unsafe { w.invalidateCursorRectsForView(h) };
        }
    }

    /// Where the control actually draws its first line of text (docs/baseline.md).
    ///
    /// AppKit publishes `firstBaselineOffsetFromTop`, but it is measured from the top of the
    /// view's alignment rect and it is rounded to whole points, and that rounding is visible.
    /// An `NSDatePicker` in a 26pt frame insets its alignment rect 4pt and answers 15, i.e. 19
    /// in frame terms, while it paints at 19.9; a label beside it then sits a point high, which
    /// is exactly the drift baseline alignment exists to remove.
    ///
    /// So derive it from the metrics AppKit rounded: a single line of the control's own font,
    /// centered in its alignment rect, with the baseline an ascender below the line's top. That
    /// reproduces AppKit's own numbers for a plain label and a bezeled field (12.91 → its 13,
    /// 19.91 → its 20) while keeping the fractional part that makes a picker land on the line.
    /// Controls with no font of their own keep AppKit's answer.
    fn first_baseline(&mut self, h: &Handle, kind: PieceKind, size: Size) -> Option<f64> {
        if !day_spec::kind_has_baseline(kind) {
            return None;
        }
        // The view has to be at the height the row settled on before it answers: a control
        // that centers its text vertically moves its baseline with its box.
        let current = unsafe { h.frame() };
        if (current.size.height - size.height).abs() > 0.5 {
            unsafe { h.setFrameSize(NSSize::new(current.size.width.max(size.width), size.height)) };
        }
        let insets = unsafe { h.alignmentRectInsets() };
        let reported = unsafe { h.firstBaselineOffsetFromTop() } + insets.top;
        let font = h
            .downcast_ref::<NSControl>()
            .and_then(|c| unsafe { c.font() });
        let offset = match font {
            // A multi-line editor's first line sits at the top of its text container, not
            // centered in it, so the centering model would put its baseline half a box too low.
            Some(_) if kind == kinds::TEXT_AREA => reported,
            Some(f) => {
                let (ascender, descender) = unsafe { (f.ascender(), f.descender()) };
                let line = ascender - descender;
                let align_h = (size.height - insets.top - insets.bottom).max(0.0);
                insets.top + ((align_h - line) / 2.0).max(0.0) + ascender
            }
            None => reported,
        };
        // AppKit's documented "no baseline" answer is the view's own height.
        (offset > 0.0 && offset < size.height).then_some(offset)
    }

    fn set_frame(&mut self, h: &Handle, frame: Rect, _anim: Option<&AnimSpec>) {
        // Nav pages: the splitter pane / nav container owns the frame (autoresized).
        if NAV_PAGES.with(|set| set.borrow().contains(&ptr_of(h))) {
            return;
        }
        // Every Day parent is flipped (DayFlipped containers, flipped scroll document views),
        // so top-left frames apply directly.
        let r = NSRect::new(
            NSPoint::new(frame.origin.x, frame.origin.y),
            NSSize::new(frame.size.width, frame.size.height),
        );
        // Nav host: the sidebar holds its width when the window resizes and the detail pane
        // absorbs the change. That is now the sidebar NSSplitViewItem's behavior, so the
        // only thing left to do here is give the split its frame and place the divider once;
        // re-placing it on every resize would fight the item and undo a user's drag.
        if let Some(split) = h.downcast_ref::<objc2_app_kit::NSSplitView>() {
            // A host at the top of a window's pinned content reaches up under the title bar,
            // where its controller expects to be (see `pane_under_title_bar`); its panes keep
            // their content below the strip, so nothing Day laid out moves.
            let strip = unsafe { split.superview() }
                .and_then(|sup| {
                    let content = unsafe { sup.window() }?.contentView()?;
                    // Layout wrappers (for example zstack with a reader cover) may sit
                    // between the window root and its navigation host. A direct-parent
                    // check misses them and puts AppKit's frosted pocket over page text.
                    let mut ancestor = Some(sup.clone());
                    while let Some(view) = ancestor {
                        if std::ptr::eq(&*view, &*content) {
                            break;
                        }
                        if view.downcast_ref::<objc2_app_kit::NSSplitView>().is_some() {
                            return None; // nested navigation belongs to the outer pane
                        }
                        ancestor = unsafe { view.superview() };
                    }
                    let point = unsafe {
                        sup.convertPoint_toView(
                            NSPoint::new(frame.origin.x, frame.origin.y),
                            Some(&content),
                        )
                    };
                    (point.y.abs() <= 0.5).then(|| title_bar_inset(&content))
                })
                .unwrap_or(0.0);
            let r = NSRect::new(
                NSPoint::new(r.origin.x, r.origin.y - strip),
                NSSize::new(r.size.width, r.size.height + strip),
            );
            let wraps = NAV_STATE.with(|m| {
                m.borrow_mut().get_mut(&ptr_of(h)).and_then(|s| {
                    (s.title_strip != strip).then(|| {
                        s.title_strip = strip;
                        let mut w = vec![s.sidebar_wrap.clone(), s.detail_wrap.clone()];
                        w.extend(s.list_wrap.clone());
                        w
                    })
                })
            });
            let first = NAV_STATE.with(|m| {
                m.borrow_mut()
                    .get_mut(&ptr_of(h))
                    .map(|s| {
                        if !s.presentation.is_split() {
                            return (false, None);
                        }
                        let sidebar = !std::mem::replace(&mut s.positioned, true);
                        // The list's divider waits for the pane to be showing. Placing it while
                        // the pane is collapsed re-opens it (which is how an app whose first
                        // destination has no list opened with one beside it) and spends the one
                        // placement the pane gets, leaving it at the solver's width later on.
                        (sidebar, take_list_placement(s))
                    })
                    .unwrap_or((false, None))
            });
            unsafe {
                split.setFrame(r);
                split.layoutSubtreeIfNeeded();
            }
            // After the panes have their new size, so each wrap is placed in the final pane;
            // autoresizing keeps the strip from then on.
            for wrap in wraps.iter().flatten() {
                place_below_strip(wrap, strip);
            }
            unsafe {
                if first.0 {
                    split.setPosition_ofDividerAtIndex(day_spec::NAV_SIDEBAR_WIDTH, 0);
                }
                // A triple split has a second divider, and nothing else places it: left alone,
                // the controller's initial constraint pass lands it wherever the solver liked, so
                // the content list opens at an arbitrary width and the detail pane gets the
                // leftovers until the first manual drag re-settles them.
                if let Some(w) = first.1 {
                    split.setPosition_ofDividerAtIndex(day_spec::NAV_SIDEBAR_WIDTH + w, 1);
                }
            }
        } else {
            BASE_FRAMES.with(|m| {
                m.insert(
                    ptr_of(h),
                    [
                        frame.origin.x,
                        frame.origin.y,
                        frame.size.width,
                        frame.size.height,
                    ],
                )
            });
            // A transform (`set_transform`) is applied to the frame Day laid out.
            match TRANSFORMS.with(|m| m.get(ptr_of(h))) {
                Some(t) => apply_geometry(
                    h,
                    [
                        frame.origin.x,
                        frame.origin.y,
                        frame.size.width,
                        frame.size.height,
                    ],
                    t,
                ),
                None => unsafe { h.setFrame(r) },
            }
        }
    }

    fn set_scroll_content(&mut self, h: &Handle, content: Size) {
        if let Some(sv) = h.downcast_ref::<NSScrollView>()
            && let Some(doc) = unsafe { sv.documentView() }
        {
            unsafe { doc.setFrameSize(NSSize::new(content.width, content.height)) };
        }
    }

    /// A macOS table row: the dense rows of a Finder or Mail list, 28pt for an icon and a line of body text.
    fn list_row_metrics(&mut self, _h: &Handle) -> day_spec::RowMetrics {
        day_spec::RowMetrics {
            insets: day_spec::Insets {
                top: 4.0,
                leading: 8.0,
                bottom: 4.0,
                trailing: 8.0,
            },
            min_height: 28.0,
        }
    }

    fn scroll_to(&mut self, h: &Handle, target: Rect, _animated: bool) {
        if let Some(sv) = h.downcast_ref::<NSScrollView>()
            && let Some(doc) = unsafe { sv.documentView() }
        {
            unsafe {
                doc.scrollRectToVisible(NSRect::new(
                    NSPoint::new(target.origin.x, target.origin.y),
                    NSSize::new(target.size.width, target.size.height),
                ))
            };
        }
    }

    fn focus(&mut self, h: &Handle, _node: NodeId, focused: bool) {
        let Some(window) = h.window() else { return };
        // A list's public handle is its scroll view; keyboard focus belongs to the table.
        let list = list_entry(ptr_of(h));
        let responder: &NSResponder = match &list {
            Some((table, _)) => table,
            None => h,
        };
        let responder_ptr = responder as *const NSResponder as usize;
        if focused {
            window.makeFirstResponder(Some(responder));
            return;
        }
        // Resign only while this view still owns focus, so a stale release can't blur a
        // sibling.
        let owns = window
            .firstResponder()
            .is_some_and(|fr| Retained::as_ptr(&fr) as usize == responder_ptr)
            || owns_first_responder(&window, h);
        if owns {
            window.makeFirstResponder(None);
        }
    }

    fn set_focusable(&mut self, h: &Handle, node: NodeId, focusable: bool) {
        // The overrides live on `DayFlipped` (the container view); registering any other
        // view is harmless but inert, the graceful silence the duty documents.
        if focusable {
            FOCUSABLE_NODES.with(|t| t.insert(ptr_of(h), node));
        } else {
            FOCUSABLE_NODES.with(|t| t.remove(ptr_of(h)));
        }
    }

    fn set_event_sink(&mut self, sink: EventSink) {
        SINK.with(|s| *s.borrow_mut() = Some(Rc::from(sink)));
    }

    fn set_edit_state(&mut self, state: &day_spec::EditState) {
        EDIT_STATE.with(|s| s.set(*state));
    }

    fn modifiers(&mut self) -> day_spec::Modifiers {
        let f = NSEvent::modifierFlags_class();
        day_spec::Modifiers {
            shift: f.contains(NSEventModifierFlags::Shift),
            primary: f.contains(NSEventModifierFlags::Command),
            alt: f.contains(NSEventModifierFlags::Option),
        }
    }

    fn set_undo_state(&mut self, state: &day_spec::UndoState) {
        let front = undo_front(self.mtm);
        *front.ivars().state.borrow_mut() = state.clone();
    }

    fn attach_list(&mut self, host: &Handle, source: ListSource) {
        let key = ptr_of(host);
        if let Some((table, data)) = list_entry(key) {
            data.ivars().source.replace(Some(source));
            // Initial fill: numberOfRows reads the snapshot only; viewForRow is deferred.
            unsafe { table.reloadData() };
        }
        // Force the table to realize its visible row views on the next main-loop turn, outside
        // any `with_tree` borrow, so `viewForRow`/`bind_row` build the cells then. Otherwise a
        // headless CI window never lays the table out until a snapshot's `cacheDisplayInRect`
        // forces it *inside* the snapshot borrow, where `bind_row` must skip (blank rows).
        post_realize_visible_rows(key);
    }

    fn attach_tree(&mut self, host: &Handle, source: TreeSource) {
        let key = ptr_of(host);
        if let Some((outline, data)) = tree_entry(key) {
            data.ivars().source.replace(Some(source));
            // Initial fill: child counts read the snapshot only; viewForItem is deferred.
            unsafe { outline.reloadData() };
        }
        // Realize visible rows on the next main-loop turn, outside any borrow (the
        // attach_list comment has the occluded-window story).
        <AppKit as Platform>::post(Box::new(move || {
            if let Some((outline, _)) = tree_entry(key) {
                unsafe { outline.layoutSubtreeIfNeeded() };
            }
        }));
    }

    fn adopt(&mut self, raw: RawHandle) -> Handle {
        // A recycling NSTableView cell view; Day builds/rebinds its row content in place.
        // Invariant, not app input: day-core only passes back the cell pointer this backend
        // itself vended through `bind_row`, so a null here is a framework bug worth stopping on.
        let ptr = raw as *mut NSView;
        unsafe { Retained::retain(ptr) }.expect("adopt: null list cell handle")
    }

    fn edit_toolbar(&mut self, h: &Handle, ops: &[day_spec::ToolbarOp]) -> bool {
        self.edit_toolbar(h, ops)
    }

    fn update_toolbar(&mut self, h: &Handle, patch: &day_spec::ToolbarPatch) {
        self.patch_toolbar(h, patch);
    }

    fn set_app_menu(&mut self, items: &[day_spec::MenuItem]) {
        let mtm = self.mtm;
        if self.menu_escape_monitor.is_none() {
            let block = block2::RcBlock::new(move |event: std::ptr::NonNull<NSEvent>| {
                ffi_guard::contain(event.as_ptr(), || {
                    let event_ref = unsafe { event.as_ref() };
                    let app = NSApplication::sharedApplication(mtm);
                    // Native dialogs retain their cancellation behavior. Only an enabled
                    // menu key equivalent can consume Escape, never the general key stream.
                    if app.modalWindow().is_none()
                        && app.keyWindow().is_some_and(|w| w.attachedSheet().is_none())
                        && unsafe { event_ref.charactersIgnoringModifiers() }
                            .is_some_and(|s| s.to_string() == "\u{1b}")
                        && app
                            .mainMenu()
                            .is_some_and(|menu| menu.performKeyEquivalent(event_ref))
                    {
                        std::ptr::null_mut()
                    } else {
                        event.as_ptr()
                    }
                })
            });
            self.menu_escape_monitor = unsafe {
                NSEvent::addLocalMonitorForEventsMatchingMask_handler(
                    objc2_app_kit::NSEventMask::KeyDown,
                    &block,
                )
            }
            .map(MenuEscapeMonitor);
        }
        let app = NSApplication::sharedApplication(mtm);
        let menubar = NSMenu::new(mtm);
        // macOS owns the application menu; relocate app-level roles while preserving
        // their callbacks, shortcuts, and enabled state.
        let mut items = items.to_vec();
        let about = extract_app_role(&mut items, day_spec::MenuRole::About);
        let updates = extract_app_role(&mut items, day_spec::MenuRole::CheckForUpdates);
        let prefs = extract_app_role(&mut items, day_spec::MenuRole::Preferences);
        let quit = extract_app_role(&mut items, day_spec::MenuRole::Quit);
        let services =
            install_application_menu(mtm, &menubar, &self.app_name, about, updates, prefs, quit);
        // Fill the standard slots the app did not claim, in the platform's bar order
        // (day-core owns that policy so every backend arranges its bar the same way).
        // Fill the standard slots the app left open, in macOS's bar order. The Window menu is
        // installed natively below, so the style deliberately supplies none.
        let items =
            day_core::menu::standard_menu_bar_for(day_core::menu::MenuBarStyle::Macos, items);
        let mut help_menu: Option<(String, Retained<NSMenu>)> = None;
        // Each top-level entry becomes a menu-bar menu.
        for item in &items {
            match item {
                day_spec::MenuItem::Submenu { label, items, role } => {
                    let sub = build_ns_menu(mtm, label, items);
                    let it = NSMenuItem::new(mtm);
                    // Help is held back: the Window menu is installed natively after this loop
                    // (AppKit owns it so it can append the live window list), and Help sits
                    // last on every Mac menu bar.
                    if *role == Some(day_spec::MenuBarRole::Help)
                        || *label == day_localization::t(day_localization::key::day_help)
                    {
                        help_menu = Some((label.clone(), sub));
                        continue;
                    }
                    it.setTitle(&NSString::from_str(label));
                    it.setSubmenu(Some(&sub));
                    menubar.addItem(&it);
                }
                other => {
                    // A bare top-level action → wrap in a one-item menu so it has a submenu.
                    let sub = build_ns_menu(mtm, "", std::slice::from_ref(other));
                    let it = NSMenuItem::new(mtm);
                    it.setSubmenu(Some(&sub));
                    menubar.addItem(&it);
                }
            }
        }
        // The Window menu (docs/windows.md): auto-installed unless the app's model owns
        // `MenuRole::Minimize` (then the app is composing its own window management).
        if !model_has_role(&items, day_spec::MenuRole::Minimize) {
            install_windows_menu(mtm, &app, &menubar);
        }
        if let Some((label, help)) = help_menu {
            let it = NSMenuItem::new(mtm);
            it.setTitle(&NSString::from_str(&label));
            it.setSubmenu(Some(&help));
            menubar.addItem(&it);
            // Registering it makes AppKit add the Help search field and index the help book —
            // behavior no hand-built menu reproduces.
            unsafe { app.setHelpMenu(Some(&help)) };
        }
        app.setMainMenu(Some(&menubar));
        unsafe { app.setServicesMenu(Some(&services)) };
    }

    fn set_context_menu(&mut self, h: &Handle, _node: NodeId, items: &[day_spec::MenuItem]) {
        let Some(view) = h.downcast_ref::<NSView>() else {
            return;
        };
        if items.is_empty() {
            unsafe { view.setMenu(None) };
            return;
        }
        let menu = build_ns_menu(self.mtm, "", items);
        // Attach to the view AND its current subviews: a right-click that hit-tests a child
        // control (the label inside a padded target) must find the menu on the view it hit —
        // AppKit does not walk ancestors for `.menu`, and controls swallow the event.
        // DayFlipped's `rightMouseDown:` pops the menu explicitly; native controls (labels)
        // show their `.menu` through their own default path.
        unsafe { view.setMenu(Some(&menu)) };
        fn apply_to_subviews(v: &NSView, menu: &NSMenu) {
            for sub in v.subviews() {
                unsafe { sub.setMenu(Some(menu)) };
                apply_to_subviews(&sub, menu);
            }
        }
        apply_to_subviews(view, &menu);
    }

    fn set_drag_source(&mut self, h: &Handle, source: day_spec::transfer::Source) {
        transfer::source(h, source);
    }
    fn set_drop_target(&mut self, h: &Handle, target: day_spec::transfer::Target) {
        transfer::target(h, target);
    }
    fn set_context_menu_fn(&mut self, h: &Handle, _node: NodeId, f: day_spec::ContextMenuFn) {
        // Consulted by the classes that override `menuForEvent:` (the canvas; docs/menus.md
        // "Dynamic context menus" lists the covered surfaces per backend).
        CTX_MENU_FNS.with(|t| t.insert(ptr_of(h), f));
    }

    fn enable_gesture(&mut self, h: &Handle, node: NodeId, kind: day_spec::GestureKind) {
        let key = ptr_of(h);
        // Pan is not a recognizer on macOS: the two-finger idiom is the trackpad SCROLL, so
        // the canvas view's own `scrollWheel:` override reports it for registered nodes.
        // Containers use a horizontal-only monitor so nested vertical scrolling still works.
        if kind == day_spec::GestureKind::Pan {
            PAN_NODES.with(|t| t.insert(key, node));
            install_container_pan_monitor();
            return;
        }
        // Nor is hover: it is a tracking area plus `mouseEntered:`/`mouseMoved:`/`mouseExited:`,
        // which only `DayCanvas` overrides — a hover enabled on another view emits nothing, the
        // same limitation Pan has.
        if kind == day_spec::GestureKind::Hover {
            // Idempotent, and it has to be checked here rather than falling through to the
            // recognizer guard below: day-core re-enables a gesture on rebuild, and a second
            // tracking area on the same view means a second copy of every hover event.
            let first = HOVER_NODES.with(|t| t.get(key)).is_none();
            HOVER_NODES.with(|t| t.insert(key, node));
            if first {
                install_tracking_area(h);
            }
            return;
        }
        // Idempotent: attach each kind at most once per view.
        let already = GESTURES.with(|m| {
            m.borrow()
                .get(&key)
                .is_some_and(|v| v.iter().any(|t| t.ivars().kind == kind))
        });
        if already {
            return;
        }
        let mtm = self.mtm;
        let target = DayGesture::new(mtm, node, kind);
        let recognizer: Retained<NSGestureRecognizer> = unsafe {
            match kind {
                day_spec::GestureKind::Drag => {
                    Retained::into_super(NSPanGestureRecognizer::initWithTarget_action(
                        NSPanGestureRecognizer::alloc(mtm),
                        Some(&target),
                        Some(sel!(fire:)),
                    ))
                }
                day_spec::GestureKind::Pinch => Retained::into_super(
                    objc2_app_kit::NSMagnificationGestureRecognizer::initWithTarget_action(
                        objc2_app_kit::NSMagnificationGestureRecognizer::alloc(mtm),
                        Some(&target),
                        Some(sel!(fire:)),
                    ),
                ),
                _ => Retained::into_super(NSClickGestureRecognizer::initWithTarget_action(
                    NSClickGestureRecognizer::alloc(mtm),
                    Some(&target),
                    Some(sel!(fire:)),
                )),
            }
        };
        unsafe { h.addGestureRecognizer(&recognizer) };
        GESTURES.with(|m| m.borrow_mut().entry(key).or_default().push(target));
    }

    fn set_a11y(&mut self, h: &Handle, a11y: &A11yProps) {
        unsafe {
            if let Some(id) = &a11y.identifier {
                h.setAccessibilityIdentifier(Some(&NSString::from_str(id)));
            }
            if let Some(label) = &a11y.label {
                h.setAccessibilityLabel(Some(&NSString::from_str(label)));
                APP_LABELED.with(|t| t.insert(ptr_of(h), ()));
            } else {
                APP_LABELED.with(|t| t.remove(ptr_of(h)));
            }
            if let Some(hint) = &a11y.hint {
                h.setAccessibilityHelp(Some(&NSString::from_str(hint)));
            }
            if let Some(value) = &a11y.value {
                let ns = NSString::from_str(value);
                h.setAccessibilityValue(Some(ns.as_ref() as &objc2::runtime::AnyObject));
            }
            // Only apply an EXPLICIT role (canvas/custom pieces, e.g. a Meter): native controls
            // already report the right role, so Day records but doesn't override theirs (§13).
            if let Some(role) = ns_role(a11y.role) {
                h.setAccessibilityRole(Some(role));
            }
            if a11y.role == day_spec::Role::Tab {
                h.setAccessibilitySubrole(Some(objc2_app_kit::NSAccessibilityTabButtonSubrole));
            }
            if let Some(on) = a11y.selected {
                h.setAccessibilitySelected(on);
            }
            // Decorative / hidden: drop from the AX tree entirely. An ignored view alone is
            // not enough — AppKit promotes an ignored element's children into its parent's
            // list — so the subtree is cut off too, which also covers subviews added later
            // (list rows, re-created children). Hidden never flips back, so the override is
            // never lifted.
            if a11y.hidden {
                h.setAccessibilityElement(false);
                h.setAccessibilityChildren(Some(&NSArray::new()));
            }
        }
    }

    /// The announcement request goes out from the primary window (any live element will
    /// do; the app object stands in before the window exists). Without VoiceOver nothing
    /// observes the notification, so posting is free.
    fn announce(&mut self, text: &str, urgent: bool) {
        use objc2_app_kit::{
            NSAccessibilityAnnouncementKey, NSAccessibilityAnnouncementRequestedNotification,
            NSAccessibilityPostNotificationWithUserInfo, NSAccessibilityPriorityKey,
            NSAccessibilityPriorityLevel,
        };
        let app = NSApplication::sharedApplication(self.mtm());
        let window = primary_content().and_then(|content| content.window());
        let element: &objc2::runtime::AnyObject = match &window {
            Some(window) => window,
            None => &app,
        };
        // High priority interrupts the current sentence; medium waits its turn.
        let priority = if urgent {
            NSAccessibilityPriorityLevel::High
        } else {
            NSAccessibilityPriorityLevel::Medium
        };
        let announcement = NSString::from_str(text);
        let priority = NSNumber::new_isize(priority.0);
        let values: [&objc2::runtime::AnyObject; 2] = [&announcement, &priority];
        // SAFETY: the keys are AppKit's constants and both values are the types the
        // announcement notification documents (an NSString and an NSNumber).
        unsafe {
            let user_info = NSDictionary::from_slices::<NSString>(
                &[NSAccessibilityAnnouncementKey, NSAccessibilityPriorityKey],
                &values,
            );
            NSAccessibilityPostNotificationWithUserInfo(
                element,
                NSAccessibilityAnnouncementRequestedNotification,
                Some(&user_info),
            );
        }
    }

    fn read_native(&self, h: &Handle) -> day_spec::NativeSnapshot {
        unsafe {
            let role = h
                .accessibilityRole()
                .map(|r| day_role_from_ns(&r.to_string()))
                .unwrap_or(day_spec::Role::None);
            // A picker answers its displayed selection and its enabled state itself: the
            // inline style is a stack of radios, not one control.
            let picker = picker::read_native(h);
            day_spec::NativeSnapshot {
                found: true,
                role,
                label: h.accessibilityLabel().map(|s| s.to_string()),
                value: h
                    .accessibilityValue()
                    .and_then(|v| v.downcast_ref::<NSString>().map(|s| s.to_string())),
                identifier: h
                    .accessibilityIdentifier()
                    .map(|s| s.to_string())
                    .filter(|s| !s.is_empty()),
                text: match &picker {
                    Some((text, _)) => text.clone(),
                    None => native_text(h),
                },
                number: native_number(h),
                checked: if let Some(sw) = h.downcast_ref::<NSSwitch>() {
                    match sw.state() {
                        s if s == NSControlStateValueOn => Some(true),
                        s if s == NSControlStateValueOff => Some(false),
                        // Mixed is neither on nor off.
                        _ => None,
                    }
                } else if let Some(btn) = h.downcast_ref::<NSButton>() {
                    // A Day button's selected state (`ButtonProps::selected`): its own
                    // `state`, which a momentary button holds off at rest.
                    BUTTON_SELECTED
                        .with(|m| m.borrow().contains_key(&ptr_of(h)))
                        .then(|| btn.state() == NSControlStateValueOn)
                } else {
                    None
                },
                // A label is a non-editable NSTextField whose `isEnabled` says nothing about
                // input; every other control answers for itself.
                enabled: match (&picker, h.downcast_ref::<NSControl>()) {
                    (Some((_, on)), _) => *on,
                    (None, Some(_)) if h.downcast_ref::<DayLabel>().is_some() => None,
                    (None, Some(c)) => Some(c.isEnabled()),
                    (None, None) => None,
                },
                // Off-window counts as not shown: nothing of it reaches the screen.
                visible: Some(h.window().is_some() && !h.isHiddenOrHasHiddenAncestor()),
                frame: native_frame(h),
            }
        }
    }

    fn request_frame(
        &mut self,
        host: &Handle,
        cb: day_spec::FrameCallback,
    ) -> day_spec::CancelFrame {
        frame::request(host, cb)
    }

    fn replay(&mut self, h: &Handle, ops: &[DrawOp], _size: Size) {
        OPS.with(|t| t.insert(ptr_of(h), ops.to_vec()));
        unsafe { h.setNeedsDisplay(true) };
    }
    fn toggle_sidebar(&mut self, host: &Self::Handle) -> bool {
        NAV_STATE.with(|m| {
            let m = m.borrow();
            let Some(st) = m.get(&ptr_of(host)) else {
                return false;
            };
            // A pane to toggle exists in `Split` and `Rail`; a stack has none and a tab bar
            // keeps its rows in the chrome, where hiding them would strand the user.
            if !matches!(
                st.presentation,
                NavPresentation::Split | NavPresentation::Rail
            ) {
                return false;
            }
            let item = &st.sidebar_item;
            // Set directly, not through the `animator` proxy. The proxy defers the change to
            // an animation the dayscript screenshot step does not wait on, so a scripted
            // toggle captured a sidebar that had not moved yet. AppKit's own
            // NSToolbarToggleSidebarItem still animates — it runs `toggleSidebar:` on the
            // controller and never comes through here.
            let collapsed = unsafe { item.isCollapsed() };
            unsafe { item.setCollapsed(!collapsed) };
            true
        })
    }

    fn snapshot_window(&mut self) -> Result<Vec<u8>, String> {
        let content = self.content.as_ref().ok_or("no window content")?;
        snapshot_view(content)
    }

    /// Decode bytes into an `NSImage` (docs/images.md).
    ///
    /// `NSBitmapImageRep` is asked first and kept: it is what actually reads the container, it
    /// answers in PIXELS (`NSImage.size` is in points and reports a 144-DPI photo at
    /// two-thirds its real width), and it is the only thing here that can re-encode later.
    fn decode_image(&mut self, req: u64, id: day_spec::BitmapId, bytes: &[u8]) {
        use objc2::AllocAnyThread as _;
        let data = NSData::with_bytes(bytes);
        let Some(rep) = (unsafe { objc2_app_kit::NSBitmapImageRep::imageRepWithData(&data) })
        else {
            emit(
                WINDOW_NODE,
                Event::ImageDecoded {
                    req,
                    result: Err(day_spec::ImageError::Decode),
                },
            );
            return;
        };
        let (w, h) = unsafe { (rep.pixelsWide() as f64, rep.pixelsHigh() as f64) };
        let info = day_spec::BitmapInfo {
            pixels: Size::new(w, h),
            // Decoded bytes carry no density — a PNG is simply its pixels. Only a staged @2x
            // asset has a scale, and that arrives through the named path instead.
            scale: 1.0,
            format: day_spec::ImageFormat::sniff(bytes),
            has_alpha: unsafe { rep.hasAlpha() },
        };
        // Built AT the rep's pixel size so it draws 1:1 by default: an NSImage otherwise adopts
        // the rep's own `size`, which ImageIO derives from the file's DPI — that is what shrinks
        // a 144-DPI photo for no reason the app asked for.
        let image = unsafe {
            objc2_app_kit::NSImage::initWithSize(objc2_app_kit::NSImage::alloc(), NSSize::new(w, h))
        };
        unsafe { image.addRepresentation(&rep) };
        BITMAPS.with(|m| {
            m.borrow_mut().insert(
                id.0,
                AppKitBitmap {
                    image,
                    rep: Some(rep),
                    info,
                },
            )
        });
        emit(
            WINDOW_NODE,
            Event::ImageDecoded {
                req,
                result: Ok(info),
            },
        );
    }

    fn image_info(&mut self, id: day_spec::BitmapId) -> Option<day_spec::BitmapInfo> {
        BITMAPS.with(|m| m.borrow().get(&id.0).map(|b| b.info))
    }

    /// The container's own metadata (docs/images.md).
    ///
    /// DPI is DERIVED rather than read from a tag: AppKit has already resolved the file's
    /// resolution into the rep's point size, so pixels-per-point × 72 is the number the platform
    /// itself believes — and it is right for containers that record resolution in ways EXIF
    /// does not.
    fn image_properties(&mut self, id: day_spec::BitmapId) -> Option<day_spec::ImageProperties> {
        let rep = BITMAPS.with(|m| m.borrow().get(&id.0).and_then(|b| b.rep.clone()))?;
        let mut out = day_spec::ImageProperties::default();
        let size = unsafe { rep.size() };
        if size.width > 0.0 {
            let dpi = unsafe { rep.pixelsWide() } as f64 / size.width * 72.0;
            // 72 is "no resolution recorded" wearing a number; reporting it would read as a fact
            // the file never stated.
            if (dpi - 72.0).abs() > 0.5 {
                out.dpi = Some(dpi);
            }
        }
        // EXIF arrives as a dictionary of the format's own keys. It is walked through
        // `msg_send!` rather than a downcast because a generic `NSDictionary` is not a
        // `DowncastTarget`.
        if let Some(exif) = rep.valueForProperty(unsafe { objc2_app_kit::NSImageEXIFData }) {
            let keys: Retained<NSArray<NSString>> = unsafe { msg_send![&*exif, allKeys] };
            for key in keys.iter() {
                let value: Option<Retained<objc2::runtime::AnyObject>> =
                    unsafe { msg_send![&*exif, objectForKey: &*key] };
                let Some(value) = value else { continue };
                let text: Retained<NSString> = unsafe { msg_send![&*value, description] };
                let (k, v) = (key.to_string(), text.to_string());
                match k.as_str() {
                    "Orientation" => out.orientation = v.parse().ok(),
                    "DateTimeOriginal" => out.created = Some(v.clone()),
                    _ => {}
                }
                // Keys stay in EXIF's own vocabulary, passed through rather than translated —
                // the doc for `extra` promises exactly that.
                out.extra.push((k, v));
            }
        }
        Some(out)
    }

    /// What `NSBitmapImageRep` WRITES. It reads more than this — WebP and HEIF among them — and
    /// the asymmetry is the platform's own, which is exactly why this duty exists instead of
    /// letting `Cap::ImageEncode` imply every format round-trips.
    fn encode_formats(&mut self) -> Vec<day_spec::ImageFormat> {
        use day_spec::ImageFormat::{Bmp, Gif, Jpeg, Png, Tiff};
        vec![Png, Jpeg, Tiff, Bmp, Gif]
    }

    fn encode_image(&mut self, req: u64, id: day_spec::BitmapId, spec: &day_spec::EncodeSpec) {
        let result = encode_bitmap(id, spec);
        emit(WINDOW_NODE, Event::ImageEncoded { req, result });
    }

    fn release_image(&mut self, id: day_spec::BitmapId) {
        release_bitmap(id);
    }

    /// Replay `ops` offscreen through the canvas's own painter (docs/canvas.md "Exporting") and
    /// keep the result in the decode table, so `image`, `encode_image` and `DrawOp::Image` take
    /// it like any decoded bitmap.
    fn render_bitmap(
        &mut self,
        req: u64,
        id: day_spec::BitmapId,
        ops: &[DrawOp],
        size: Size,
        scale: f64,
    ) {
        let result = render_bitmap_image(ops, size, scale).map(|bitmap| {
            let info = bitmap.info;
            BITMAPS.with(|m| m.borrow_mut().insert(id.0, bitmap));
            info
        });
        emit(WINDOW_NODE, Event::BitmapRendered { req, result });
    }

    fn render_pdf(&mut self, req: u64, pages: &[day_spec::PdfPage], info: &day_spec::PdfInfo) {
        let result = render_pdf_bytes(pages, info);
        emit(WINDOW_NODE, Event::PdfRendered { req, result });
    }

    /// `NSFontManager.availableFontFamilies` + `availableMembersOfFontFamily:`, whose members
    /// are `[postscriptName, styleName, weight 0 … 15, traits]` (docs/fonts.md). The `.`-prefixed
    /// families are the system's private UI faces and are skipped, as Font Book skips them.
    fn font_families(&mut self) -> Vec<day_spec::FontFamilyInfo> {
        use day_spec::FontWeight as W;
        let mtm =
            objc2::MainThreadMarker::new().expect("day-toolkit-appkit runs on the main thread");
        let manager = unsafe { objc2_app_kit::NSFontManager::sharedFontManager(mtm) };
        let mut out = Vec::new();
        for family in unsafe { manager.availableFontFamilies() }.iter() {
            let name = family.to_string();
            if name.starts_with('.') {
                continue;
            }
            let mut faces = Vec::new();
            if let Some(members) = unsafe { manager.availableMembersOfFontFamily(&family) } {
                for member in members.iter() {
                    if member.count() < 4 {
                        continue;
                    }
                    let style = member
                        .objectAtIndex(1)
                        .downcast_ref::<NSString>()
                        .map(|s| s.to_string())
                        .unwrap_or_default();
                    let weight = member
                        .objectAtIndex(2)
                        .downcast_ref::<objc2_foundation::NSNumber>()
                        .map(|n| n.integerValue())
                        .unwrap_or(5);
                    let traits = member
                        .objectAtIndex(3)
                        .downcast_ref::<objc2_foundation::NSNumber>()
                        .map(|n| n.integerValue())
                        .unwrap_or(0);
                    let weight = match weight {
                        ..=2 => W::UltraLight,
                        3 => W::Thin,
                        4 => W::Light,
                        5 => W::Regular,
                        6 => W::Medium,
                        7 | 8 => W::Semibold,
                        9 => W::Bold,
                        10 | 11 => W::Heavy,
                        _ => W::Black,
                    };
                    let italic = traits & 0x1 != 0; // NSItalicFontMask
                    faces.push(day_spec::FontFace {
                        name: if style.is_empty() {
                            day_spec::FontFace::synthesized_name(weight, italic)
                        } else {
                            style
                        },
                        weight,
                        italic,
                    });
                }
            }
            out.push(day_spec::FontFamilyInfo {
                family: name,
                faces,
            });
        }
        out
    }

    /// `sizeWithAttributes:` with the attributes `replay` draws with; the ascent is the
    /// font's own, so `at.y + ascent` is where the glyphs' baseline lands.
    fn measure_text(
        &mut self,
        text: &str,
        size: f64,
        font: &day_spec::CanvasFont,
    ) -> Option<day_spec::TextMetrics> {
        let nsfont = canvas_nsfont(size, font);
        let attrs = canvas_text_attrs(&nsfont, day_spec::Color::BLACK);
        let ns = NSString::from_str(text);
        let sz: NSSize = unsafe { msg_send![&ns, sizeWithAttributes: &*attrs] };
        // The INK box: `NSStringDrawingUsesDeviceMetrics` is what turns `boundingRectWithSize:`
        // from the layout box into the glyphs' own bounds, and it comes back baseline-relative
        // with y up — hence the flip. An unbounded size so nothing wraps: this measures one line.
        let unbounded = NSSize::new(f64::MAX, f64::MAX);
        let ink: NSRect = unsafe {
            msg_send![
                &ns,
                boundingRectWithSize: unbounded,
                options: objc2_app_kit::NSStringDrawingOptions::UsesDeviceMetrics,
                attributes: &*attrs,
            ]
        };
        Some(day_spec::TextMetrics::from_baseline(
            sz.width,
            nsfont.ascender(),
            sz.height - nsfont.ascender(),
            nsfont.capHeight(),
            day_spec::Rect::new(
                ink.origin.x,
                -(ink.origin.y + ink.size.height),
                ink.size.width,
                ink.size.height,
            ),
        ))
    }

    fn snapshot_window_chrome(&mut self) -> Result<Vec<u8>, String> {
        let content = self.content.as_ref().ok_or("no window content")?;
        snapshot_view_chrome(content)
    }

    fn snapshot_window_of(&mut self, host: &Handle) -> Result<Vec<u8>, String> {
        snapshot_view(host)
    }

    fn open_window(
        &mut self,
        id: NodeId,
        options: &WindowOptions,
        kind: day_spec::WindowKind,
    ) -> day_spec::WindowOpenReply<Handle> {
        let prefs = kind.is_panel();
        let (window, delegate, content) = self.make_window(options, prefs, Some(id));
        if prefs {
            // A settings panel is one-of-a-kind and centered, and it stays OUT of the Window
            // menu — the macOS convention every stock app follows (docs/windows.md).
            window.center();
            unsafe { window.setExcludedFromWindowsMenu(true) };
        } else {
            // Stagger, don't stack. Without this every window opens at the same centered frame
            // and the one underneath is invisible — which is exactly what two Day windows did.
            //
            // `cascadeTopLeftFromPoint:` puts the window AT the point it is given and answers
            // the point for the one after, so the series has to be primed from the primary
            // rather than seeded with its corner — seeding lands the first new window exactly
            // on top of the primary, which is the bug this replaces.
            let from = match self.cascade {
                Some(p) => p,
                None => self
                    .window
                    .as_ref()
                    .map(|w| {
                        let f = w.frame();
                        let top_left = NSPoint::new(f.origin.x, f.origin.y + f.size.height);
                        // Asking the primary to cascade from where it already is leaves it
                        // there and answers the next slot — the offset the first new window wants.
                        unsafe { w.cascadeTopLeftFromPoint(top_left) }
                    })
                    .unwrap_or(NSPoint::new(0.0, 0.0)),
            };
            self.cascade = Some(unsafe { window.cascadeTopLeftFromPoint(from) });
        }
        window_chrome::place(&window, options.placement);
        // Secondary windows need the same initial client-coordinate pinning as the
        // primary. Native document pages may move here before any resize notification.
        let _ = pin_below_title_bar(&window);
        if !options.start_hidden {
            window.makeKeyAndOrderFront(None);
        }
        // Same macOS 26 quirk as the primary (`run`): a window ordered front before its
        // first turn drops pre-run layer displays — nudge every layer once.
        mark_tree_needs_display(&content);
        self.secondary.push(SecondaryWin {
            window,
            delegate,
            content: content.clone(),
        });
        day_spec::WindowOpenReply::Open(content)
    }

    fn native_window_tabs(&self) -> bool {
        true
    }
    fn group_windows(&mut self, hosts: &[Handle]) {
        let windows: Vec<_> = hosts.iter().filter_map(|h| self.ns_window_for(h)).collect();
        let Some(first) = windows.first() else {
            return;
        };
        unsafe {
            NSWindow::setAllowsAutomaticWindowTabbing(true, self.mtm);
        }
        // Explicit insertion respects the model even when system automatic tabbing is off.
        for window in windows.iter().skip(1) {
            unsafe {
                first.addTabbedWindow_ordered(window, objc2_app_kit::NSWindowOrderingMode::Above);
            }
        }
        if let Some(group) = first.tabGroup() {
            if !group.isTabBarVisible() {
                unsafe {
                    first.toggleTabBar(None);
                }
            }
            for (i, window) in windows.iter().enumerate() {
                group.insertWindow_atIndex(window, i as isize);
            }
        }
        // Adding/showing a native tab strip changes contentLayoutRect without necessarily
        // resizing the window. Re-pin every member and tell the layout tree its usable size.
        for window in &windows {
            if let Some(size) = pin_below_title_bar(window) {
                let node = window
                    .delegate()
                    .and_then(|d| d.downcast::<DayWinDelegate>().ok())
                    .and_then(|d| d.ivars().node)
                    .unwrap_or(WINDOW_NODE);
                emit(node, Event::WindowResized(size));
            }
        }
    }
    fn window_tab_order(&self, host: &Handle) -> Vec<NodeId> {
        let Some(window) = self.ns_window_for(host) else {
            return Vec::new();
        };
        let windows = window.tabGroup().map(|g| g.windows());
        let Some(windows) = windows else {
            return Vec::new();
        };
        windows
            .iter()
            .filter_map(|window| {
                self.secondary
                    .iter()
                    .find(|w| std::ptr::eq(&*w.window, &*window))
                    .and_then(|w| w.delegate.ivars().node)
            })
            .collect()
    }

    fn close_window(&mut self, host: &Handle) {
        // `close()` runs the full native path — windowWillClose → `WindowClosed` →
        // day-core teardown — so programmatic and title-bar closes are one code path.
        if let Some(w) = self
            .secondary
            .iter()
            .find(|w| ptr_of(&w.content) == ptr_of(host))
        {
            w.window.close();
        }
    }

    fn focus_window(&mut self, host: &Handle) {
        if let Some(w) = self
            .secondary
            .iter()
            .find(|w| ptr_of(&w.content) == ptr_of(host))
        {
            w.window.makeKeyAndOrderFront(None);
        }
    }

    fn fit_window(&mut self, host: &Handle, size: Size) {
        let Some(w) = self
            .secondary
            .iter()
            .find(|w| ptr_of(&w.content) == ptr_of(host))
        else {
            return;
        };
        unsafe {
            // `setContentSize:` rather than `setFrame:`: Day measured the CONTENT, and AppKit
            // adds the title bar itself. Sizing the frame instead would eat the bar's height out
            // of the panel and clip the last row by exactly that much.
            w.window
                .setContentSize(NSSize::new(size.width, size.height));
            // A settings panel that fits its content has no reason to be resizable, and macOS
            // panels are not — dropping the mask also stops the user dragging it back to a size
            // the content does not fill.
            let mask = w.window.styleMask();
            w.window
                .setStyleMask(mask & !objc2_app_kit::NSWindowStyleMask::Resizable);
            w.window.center();
        }
    }

    fn set_window_title(&mut self, host: &Handle, title: &str) {
        if let Some(w) = self
            .secondary
            .iter()
            .find(|w| ptr_of(&w.content) == ptr_of(host))
        {
            w.window.setTitle(&NSString::from_str(title));
            return;
        }
        // The PRIMARY window is retitlable too. It is an ordinary window (docs/windows.md), so
        // `window_title` in the first window's shell and `set_title` on `initial_window()` both
        // arrive here — and searching only the secondary list silently dropped them.
        if self
            .content
            .as_ref()
            .is_some_and(|c| ptr_of(c) == ptr_of(host))
            && let Some(w) = self.window.as_ref()
        {
            w.setTitle(&NSString::from_str(title));
        }
    }

    fn apply_window(&mut self, host: &Handle, change: &day_spec::WindowChange) {
        use day_spec::WindowChange as C;
        let Some(window) = self.ns_window_for(host) else {
            return;
        };
        match change {
            C::State(state) => set_ns_window_state(&window, *state),
            // Screen capture, recording and sharing see an empty window; the user still does.
            C::ContentProtected(on) => window.setSharingType(if *on {
                objc2_app_kit::NSWindowSharingType::None
            } else {
                objc2_app_kit::NSWindowSharingType::ReadOnly
            }),
            other => window_chrome::apply_property(&window, other),
        }
    }

    fn window_frame(&self, host: &Handle) -> Option<day_spec::Rect> {
        self.ns_window_for(host)
            .map(|w| window_chrome::frame_of(&w))
    }

    fn monitors(&self) -> Vec<day_spec::Monitor> {
        window_chrome::monitors(self.mtm)
    }

    /// The Dock menu lists them: day-core folds the run-time shortcuts into the model it sends
    /// through `set_dock_menu`, so there is nothing more to install here.
    fn set_launcher_shortcuts(&mut self, _shortcuts: &[day_spec::LauncherShortcut]) {}

    fn set_dock_menu(&mut self, items: &[day_spec::MenuItem]) {
        dock::set_app_items(self.mtm, items);
    }

    fn set_drag_region(&mut self, h: &Handle, drag: bool) {
        window_chrome::set_drag_region(h, drag);
    }

    fn set_status_items(&mut self, items: &[day_spec::StatusItemSpec]) {
        status_item::set_items(self.mtm, items);
    }

    fn set_app_progress(&mut self, progress: day_spec::AppProgress) {
        status_item::set_progress(self.mtm, progress);
    }

    fn set_dock_visible(&mut self, visible: bool) {
        status_item::set_dock_visible(self.mtm, visible);
    }

    fn set_keep_running(&mut self, keep: bool) {
        status_item::set_keep_running(keep);
    }

    fn quit_app(&mut self) {
        let app = NSApplication::sharedApplication(self.mtm);
        unsafe { app.terminate(None) };
    }

    fn present(&mut self, req: u64, spec: &present::PresentSpec) {
        use present::PresentSpec;
        let mtm = self.mtm;
        // Sheets attach to the KEY window at present time (docs/windows.md) — a dialog
        // raised from a secondary/preferences window belongs on it; primary is the
        // fallback when no DAY window is key (a system panel may hold key status).
        let app = NSApplication::sharedApplication(mtm);
        let key = app.keyWindow().filter(|k| {
            let mut owner = k.clone();
            while let Some(parent) = owner.sheetParent() {
                owner = parent;
            }
            self.window
                .as_deref()
                .is_some_and(|w| std::ptr::eq(w, &*owner))
                || self
                    .secondary
                    .iter()
                    .any(|s| std::ptr::eq(&*s.window, &*owner))
        });
        let Some(mut window) = key.or_else(|| self.window.clone()) else {
            emit(
                WINDOW_NODE,
                Event::PresentResult {
                    req,
                    result: present::PresentResult::Dismissed,
                },
            );
            return;
        };
        // A dialog opened from a modal cover belongs on the active sheet, not behind it.
        while let Some(sheet) = window.attachedSheet() {
            window = sheet;
        }
        // File pickers use a different native object (NSOpen/NSSavePanel), not an NSAlert.
        match spec {
            PresentSpec::OpenFile {
                filters, multiple, ..
            } => {
                let panel = unsafe { objc2_app_kit::NSOpenPanel::openPanel(mtm) };
                unsafe {
                    panel.setCanChooseFiles(true);
                    panel.setCanChooseDirectories(false);
                    panel.setAllowsMultipleSelection(*multiple);
                    panel.setMessage(Some(&NSString::from_str(spec.title())));
                }
                apply_allowed_file_types(&panel, filters);
                let p = panel.clone();
                // Completion blocks run inside a C ABI frame, so their bodies are contained
                // like every other trampoline (§8.5) — this one and the four below.
                let handler: block2::RcBlock<dyn Fn(isize)> =
                    block2::RcBlock::new(move |resp: isize| {
                        ffi_guard::contain((), || emit_open_panel_result(req, resp, &p));
                    });
                unsafe { panel.beginSheetModalForWindow_completionHandler(&window, &handler) };
                PRESENT_PANELS.with(|m| m.borrow_mut().insert(req, Retained::into_super(panel)));
                return;
            }
            // The folder chooser is the same NSOpenPanel with files and directories swapped.
            PresentSpec::OpenFolder { .. } => {
                let panel = unsafe { objc2_app_kit::NSOpenPanel::openPanel(mtm) };
                unsafe {
                    panel.setCanChooseFiles(false);
                    panel.setCanChooseDirectories(true);
                    panel.setCanCreateDirectories(true);
                    panel.setAllowsMultipleSelection(false);
                    panel.setMessage(Some(&NSString::from_str(spec.title())));
                }
                let p = panel.clone();
                let handler: block2::RcBlock<dyn Fn(isize)> =
                    block2::RcBlock::new(move |resp: isize| {
                        ffi_guard::contain((), || emit_open_panel_result(req, resp, &p));
                    });
                unsafe { panel.beginSheetModalForWindow_completionHandler(&window, &handler) };
                PRESENT_PANELS.with(|m| m.borrow_mut().insert(req, Retained::into_super(panel)));
                return;
            }
            PresentSpec::SaveFile { suggested_name, .. } => {
                let panel = unsafe { objc2_app_kit::NSSavePanel::savePanel(mtm) };
                unsafe {
                    panel.setMessage(Some(&NSString::from_str(spec.title())));
                    panel.setNameFieldStringValue(&NSString::from_str(suggested_name));
                }
                apply_allowed_file_types(&panel, spec.filters());
                let p = panel.clone();
                let handler: block2::RcBlock<dyn Fn(isize)> =
                    block2::RcBlock::new(move |resp: isize| {
                        // The pieces layer copies the staged bytes to the chosen local path.
                        ffi_guard::contain((), || emit_panel_result(req, resp, &p));
                    });
                unsafe { panel.beginSheetModalForWindow_completionHandler(&window, &handler) };
                PRESENT_PANELS.with(|m| m.borrow_mut().insert(req, panel));
                return;
            }
            _ => {}
        }
        let alert = unsafe { objc2_app_kit::NSAlert::new(mtm) };
        unsafe { alert.setMessageText(&NSString::from_str(spec.title())) };
        if let Some(msg) = spec.message() {
            unsafe { alert.setInformativeText(&NSString::from_str(msg)) };
        }
        // The completion handler must outlive this call, so it's a heap (Rc) block.
        let handler: block2::RcBlock<dyn Fn(isize)> = match spec {
            PresentSpec::Dialog { buttons, .. } => {
                if buttons
                    .iter()
                    .any(|b| b.role == present::ButtonRole::Destructive)
                {
                    unsafe { alert.setAlertStyle(objc2_app_kit::NSAlertStyle::Warning) };
                }
                for b in buttons {
                    unsafe { alert.addButtonWithTitle(&NSString::from_str(&b.label)) };
                }
                block2::RcBlock::new(move |resp: isize| {
                    ffi_guard::contain((), || {
                        // NSAlertFirstButtonReturn = 1000; add order == spec order.
                        let idx = resp - 1000;
                        emit(
                            WINDOW_NODE,
                            Event::PresentResult {
                                req,
                                result: present::PresentResult::Button(idx as i64),
                            },
                        );
                        PRESENT_ALERTS.with(|m| {
                            m.borrow_mut().remove(&req);
                        });
                    })
                })
            }
            PresentSpec::Prompt {
                placeholder,
                initial,
                ok,
                cancel,
                ..
            } => {
                let tf = unsafe { NSTextField::new(mtm) };
                unsafe {
                    tf.setFrame(NSRect::new(
                        NSPoint::new(0.0, 0.0),
                        NSSize::new(260.0, 24.0),
                    ));
                    tf.setEditable(true);
                    tf.setBezeled(true);
                    tf.setStringValue(&NSString::from_str(initial));
                    tf.setPlaceholderString(Some(&NSString::from_str(placeholder)));
                    alert.setAccessoryView(Some(&tf));
                    alert.addButtonWithTitle(&NSString::from_str(ok)); // resp 1000
                    alert.addButtonWithTitle(&NSString::from_str(cancel)); // resp 1001
                }
                block2::RcBlock::new(move |resp: isize| {
                    ffi_guard::contain((), || {
                        let result = if resp == 1000 {
                            present::PresentResult::Text(unsafe { tf.stringValue() }.to_string())
                        } else {
                            present::PresentResult::Dismissed
                        };
                        emit(WINDOW_NODE, Event::PresentResult { req, result });
                        PRESENT_ALERTS.with(|m| {
                            m.borrow_mut().remove(&req);
                        });
                    })
                })
            }
            // File pickers returned early above.
            PresentSpec::OpenFile { .. }
            | PresentSpec::OpenFolder { .. }
            | PresentSpec::SaveFile { .. } => unreachable!(),
        };
        unsafe {
            alert.beginSheetModalForWindow_completionHandler(&window, Some(&handler));
        }
        PRESENT_ALERTS.with(|m| m.borrow_mut().insert(req, alert));
    }

    fn dismiss(&mut self, req: u64) {
        // Close the sheet; its completion handler fires but its (native) result is dropped
        // because day-core already removed the pending request when it resolved.
        let alert = PRESENT_ALERTS.with(|m| m.borrow_mut().remove(&req));
        if let Some(alert) = alert {
            let sheet = alert.window();
            if let Some(parent) = sheet.sheetParent() {
                unsafe { parent.endSheet(&sheet) };
            }
        }
        // File-picker sheets are their own NSWindow.
        let panel = PRESENT_PANELS.with(|m| m.borrow_mut().remove(&req));
        if let Some(panel) = panel
            && let Some(parent) = panel.sheetParent()
        {
            unsafe { parent.endSheet(&panel) };
        }
    }

    fn application_handlers(
        &mut self,
        query: &day_spec::applications::HandlerQuery,
    ) -> Result<day_spec::applications::ApplicationHandlers, day_spec::applications::ApplicationError>
    {
        applications::handlers(query)
    }

    fn open_url_with_application(
        &mut self,
        url: &str,
        application: &str,
        completion: day_spec::applications::OpenApplicationCompletion,
    ) {
        applications::open(url, application, completion);
    }

    fn share_support(&self) -> day_spec::Support {
        day_spec::Support::Native
    }
    fn share_url(&mut self, url: &str, _title: &str) -> bool {
        use objc2::{msg_send, runtime::AnyObject};
        use objc2_foundation::{NSArray, NSPoint, NSRect, NSSize, NSString, NSURL};
        let Some(mtm) = objc2::MainThreadMarker::new() else {
            return false;
        };
        let Some(url) = NSURL::URLWithString(&NSString::from_str(url)) else {
            return false;
        };
        let app = objc2_app_kit::NSApplication::sharedApplication(mtm);
        let Some(view) = app.keyWindow().and_then(|w| w.contentView()) else {
            return false;
        };
        unsafe {
            let items = NSArray::from_retained_slice(&[url]);
            let picker: objc2::rc::Allocated<AnyObject> =
                msg_send![objc2::class!(NSSharingServicePicker), alloc];
            let picker: objc2::rc::Retained<AnyObject> = msg_send![picker, initWithItems: &*items];
            let bounds = view.bounds();
            let y = if view.isFlipped() {
                30.0
            } else {
                bounds.size.height - 30.0
            };
            let rect = NSRect::new(
                NSPoint::new(bounds.size.width - 30.0, y),
                NSSize::new(1.0, 1.0),
            );
            let _: () = msg_send![&*picker, showRelativeToRect: rect, ofView: &*view, preferredEdge: 3usize];
            self.sharing = Some(picker);
        }
        true
    }
    fn open_url(&mut self, url: &str) {
        // NSWorkspace opens the URL in the user's default handler (Safari for http(s), Mail for
        // mailto:, …). An unparseable string yields no NSURL and is silently ignored.
        let nsurl = unsafe { objc2_foundation::NSURL::URLWithString(&NSString::from_str(url)) };
        if let Some(nsurl) = nsurl {
            unsafe { objc2_app_kit::NSWorkspace::sharedWorkspace().openURL(&nsurl) };
        }
    }
}

/// Apply a file dialog's extension filters (`allowedFileTypes` — deprecated but still the simplest
/// extension-based API; `UTType` would pull in another framework crate for no benefit here).
#[allow(deprecated)]
fn apply_allowed_file_types(
    panel: &objc2_app_kit::NSSavePanel,
    filters: &[day_spec::present::FileFilter],
) {
    let exts: Vec<Retained<NSString>> = filters
        .iter()
        .flat_map(|f| f.extensions.iter())
        .map(|e| NSString::from_str(e))
        .collect();
    if !exts.is_empty() {
        let refs: Vec<&NSString> = exts.iter().map(|r| &**r).collect();
        let arr = objc2_foundation::NSArray::from_slice(&refs);
        unsafe { panel.setAllowedFileTypes(Some(&arr)) };
    }
}

/// Turn an open panel completion into a `PresentResult` and enqueue it (NSModalResponseOK = 1):
/// every chosen URL, so a multiple-selection pick reports all of its files (and a folder
/// chooser its one directory).
fn emit_open_panel_result(req: u64, resp: isize, panel: &objc2_app_kit::NSOpenPanel) {
    let mut paths = Vec::new();
    if resp == 1 {
        for url in unsafe { panel.URLs() }.iter() {
            if let Some(p) = unsafe { url.path() } {
                paths.push(p.to_string());
            }
        }
    }
    let result = if paths.is_empty() {
        present::PresentResult::Dismissed
    } else {
        present::PresentResult::Files(paths)
    };
    emit(WINDOW_NODE, Event::PresentResult { req, result });
    PRESENT_PANELS.with(|m| {
        m.borrow_mut().remove(&req);
    });
}

/// Turn a save panel completion into a `PresentResult` and enqueue it (NSModalResponseOK = 1).
fn emit_panel_result(req: u64, resp: isize, panel: &objc2_app_kit::NSSavePanel) {
    let result = if resp == 1 {
        unsafe { panel.URL() }
            .and_then(|url| unsafe { url.path() })
            .map(|p| present::PresentResult::Files(vec![p.to_string()]))
            .unwrap_or(present::PresentResult::Dismissed)
    } else {
        present::PresentResult::Dismissed
    };
    emit(WINDOW_NODE, Event::PresentResult { req, result });
    PRESENT_PANELS.with(|m| {
        m.borrow_mut().remove(&req);
    });
}

impl Platform for AppKit {
    const TARGET: &'static str = "macos-appkit";
    const TOOLKIT: &'static str = "appkit";

    fn run(mut self, options: WindowOptions, ready: Box<dyn FnOnce(Self, Handle, Size)>) {
        let mtm = self.mtm;
        // The App menu / About use the app's display name. `app_name` overrides the (possibly
        // decorated) window title; setting the process name also makes the standard About panel and
        // the bold App-menu title show it (an unbundled binary otherwise shows the exe name).
        self.app_name = options
            .app_name
            .clone()
            .unwrap_or_else(|| options.title.clone());
        // The bold App-menu title, the About panel and Quit all show the app's NAME. Always set
        // it, not just when `app_name` was given explicitly — an app that only set `title` was
        // showing its kebab-case cargo target ("day-sheets") where its name belongs.
        //
        // Two sources, because AppKit consults them in order: the main bundle's CFBundleName
        // wins when there is one, and `day launch` runs the binary UNBUNDLED during development,
        // where the name falls back to the executable's file name. Writing the info dictionary
        // covers the bundled case; the process name covers the unbundled one.
        unsafe {
            objc2_foundation::NSProcessInfo::processInfo()
                .setProcessName(&NSString::from_str(&self.app_name));
            let bundle = objc2_foundation::NSBundle::mainBundle();
            let info: Option<Retained<objc2_foundation::NSDictionary>> =
                msg_send![&bundle, infoDictionary];
            if let Some(info) = info {
                let key = NSString::from_str("CFBundleName");
                let value = NSString::from_str(&self.app_name);
                // `infoDictionary` is documented immutable, but the instance backing an
                // unbundled process is a mutable dictionary; guard the send so a genuinely
                // immutable one is left alone instead of raising.
                if info.respondsToSelector(objc2::sel!(setObject:forKey:)) {
                    let _: () = msg_send![&info, setObject: &*value, forKey: &*key];
                }
            }
        }
        // RTL locales (docs/localization): AppleTextDirection flips AppKit's app-wide
        // userInterfaceLayoutDirection (label alignment, slider fill, control mirroring) —
        // read at NSApplication init, so register before sharedApplication. Registration
        // domain only: volatile, never persisted to the app's defaults.
        if day_core::layout_direction() == day_spec::LayoutDirection::Rtl {
            unsafe {
                use objc2_foundation::{NSDictionary, NSNumber, NSUserDefaults};
                let yes: objc2::rc::Retained<objc2::runtime::AnyObject> = NSNumber::new_bool(true)
                    .into_super()
                    .into_super()
                    .into_super();
                let dict = NSDictionary::from_retained_objects(
                    &[
                        &*NSString::from_str("AppleTextDirection"),
                        &*NSString::from_str("NSForceRightToLeftWritingDirection"),
                    ],
                    &[yes.clone(), yes],
                );
                NSUserDefaults::standardUserDefaults().registerDefaults(&dict);
            }
        }
        let app = NSApplication::sharedApplication(mtm);
        // A menu-bar app keeps out of the Dock from the first frame (docs/status-item.md): its
        // bundle carries LSUIElement, and an unbundled `day launch` run hears DAY_MACOS_DOCK=0.
        let menu_bar_app = std::env::var("DAY_MACOS_DOCK").is_ok_and(|v| v == "0")
            || unsafe {
                let bundle = objc2_foundation::NSBundle::mainBundle();
                let value: Option<Retained<objc2::runtime::AnyObject>> = msg_send![
                    &bundle,
                    objectForInfoDictionaryKey: &*NSString::from_str("LSUIElement")
                ];
                value.is_some_and(|v| {
                    let on: bool = msg_send![&v, boolValue];
                    on
                })
            };
        app.setActivationPolicy(if menu_bar_app {
            NSApplicationActivationPolicy::Accessory
        } else {
            NSApplicationActivationPolicy::Regular
        });
        let document_delegate = documents::delegate(mtm);
        app.setDelegate(Some(ProtocolObject::from_ref(&*document_delegate)));
        // DAY_THEME=light|dark forces the appearance app-wide (themed CI screenshot runs and
        // local theme checks); unset ⇒ follow the system.
        if let Ok(theme) = std::env::var("DAY_THEME") {
            let name = match theme.as_str() {
                "dark" => Some(unsafe { objc2_app_kit::NSAppearanceNameDarkAqua }),
                "light" => Some(unsafe { objc2_app_kit::NSAppearanceNameAqua }),
                _ => None,
            };
            if let Some(name) = name {
                let appearance = objc2_app_kit::NSAppearance::appearanceNamed(name);
                unsafe { app.setAppearance(appearance.as_deref()) };
            }
        }
        // Bundled custom fonts (§18.4) must be registered before the first label realizes.
        register_bundled_fonts();

        // Default menu bar (standard app menu + Edit) so ⌘Q / Cut-Copy-Paste work before the app
        // installs its own via `app_menu(...)`. Rebuilt after `ready` for the items that depend
        // on the app's registrations — see there.
        let app_name = self.app_name.clone();
        install_main_menu(mtm, &app, &app_name);
        // App activation / termination → day lifecycle events (docs/lifecycle.md).
        install_lifecycle_observers();
        install_appearance_observer();
        install_reduce_motion_observer();

        let (window, delegate, content) = self.make_window(&options, false, None);
        // Optional window-appearance override (opt-in via env). An app with a fixed light/dark
        // palette sets `DAY_APPEARANCE=light|dark` so native controls (list, fields, editor) match
        // its own colors instead of following the system appearance. Unset = follow the system.
        let appearance_name = match std::env::var("DAY_APPEARANCE").ok().as_deref() {
            Some("light") => Some(unsafe { objc2_app_kit::NSAppearanceNameAqua }),
            Some("dark") => Some(unsafe { objc2_app_kit::NSAppearanceNameDarkAqua }),
            _ => None,
        };
        if let Some(name) = appearance_name
            && let Some(appearance) = unsafe { objc2_app_kit::NSAppearance::appearanceNamed(name) }
        {
            window.setAppearance(Some(&appearance));
        }
        // The primary delegate lives for the process (this frame never returns); secondary
        // delegates are retained in `self.secondary`.
        std::mem::forget(delegate);

        self.window = Some(window.clone());
        self.content = Some(content.clone());
        PRIMARY_CONTENT.with(|c| *c.borrow_mut() = Some(content.clone()));

        // The root lays out below the title bar, not under it (§7.7).
        let layout = pin_below_title_bar(&window)
            .unwrap_or(Size::new(options.size.width, options.size.height));
        ready(self, content, layout);

        // `ready` ran the app's root() — registrations are in. Without a new-window
        // builder only one Normal window can ever exist: turn automatic tabbing off so no
        // tab bar, "+" button, or dead tab menu items appear (docs/windows.md).
        if day_core::windows::new_window_action_id() == 0
            && options.tabbing == day_spec::WindowTabbing::Automatic
        {
            unsafe { NSWindow::setAllowsAutomaticWindowTabbing(false, mtm) };
        }
        // The DEFAULT menu bar was built before `root()` ran, so its registration-dependent
        // items — Settings…/⌘, and File ▸ New Window — could not exist yet. Rebuild it now that
        // they can. An app with its own `app_menu` model already replaced the whole bar and
        // gets its items through the injection path instead.
        if !day_core::has_app_menu() {
            install_main_menu(mtm, &app, &app_name);
        }

        // Reopen where the user left it (docs/windows.md). AppKit persists the frame under an
        // autosave name and hands it back on request; `setFrameUsingName` answers false the
        // first time, which is when centering is the right answer.
        //
        // NOT while a dayscript is driving or `DAY_WINDOW` has forced a size: a restored frame
        // would make every captured screenshot's dimensions depend on where the developer last
        // dragged the window, and the capture suites compare those across machines.
        let deterministic =
            std::env::var_os("DAY_SCRIPT").is_some() || std::env::var_os("DAY_WINDOW").is_some();
        let autosave = NSString::from_str("day.main");
        if deterministic || !unsafe { window.setFrameUsingName(&autosave) } {
            window.center();
            // An explicit placement wins over centering, but not over the frame the user left.
            window_chrome::place(&window, options.placement);
        }
        // A scripted run whose capture needs a display scale this host's displays lack opens on
        // the one `day launch` made for it (`DAY_WINDOW_SCREEN`, a CGDirectDisplayID): a
        // capture is the window server's pixels, so it has the scale of the display under it.
        if let Some(screen) = capture_screen(mtm) {
            let (visible, frame) = (screen.visibleFrame(), window.frame());
            window.setFrameOrigin(NSPoint::new(
                visible.origin.x + ((visible.size.width - frame.size.width) / 2.0).max(0.0),
                visible.origin.y + ((visible.size.height - frame.size.height) / 2.0).max(0.0),
            ));
        }
        if !deterministic {
            unsafe { window.setFrameAutosaveName(&autosave) };
        }
        if !options.start_hidden {
            window.makeKeyAndOrderFront(None);
            app.activate();
        }
        // The root was mounted before the window was shown (ready() runs first), and on
        // macOS 26 layer displays requested pre-run are dropped for a window ordered front
        // before the app finishes launching — the window stays blank until the next real
        // event. Re-mark the whole tree so the first run-loop turn commits a full frame.
        if let Some(content) = window.contentView() {
            mark_tree_needs_display(&content);
        }
        if std::env::var_os("DAY_DUMP").is_some() {
            std::thread::spawn(|| {
                std::thread::sleep(std::time::Duration::from_millis(2000));
                Self::post(Box::new(|| {
                    // The primary's content specifically (docs/windows.md).
                    if let Some(content) = primary_content() {
                        let desc: Retained<NSString> =
                            unsafe { msg_send![&*content, _subtreeDescription] };
                        log::warn!("{desc}");
                    }
                }));
            });
        }
        app.run();
    }

    fn post(f: Box<dyn FnOnce() + Send>) {
        // Posted-closure trampoline (§8.5): the closure runs inside dispatch's C frame, so a
        // panic is contained here rather than unwinding into libdispatch.
        dispatch2::DispatchQueue::main().exec_async(move || ffi_guard::contain((), f));
    }

    fn post_delayed(ms: u32, f: Box<dyn FnOnce() + Send>) {
        // The timer door behind `day::sleep` (docs/async.md): `dispatch_after` on the main
        // queue, so a sleep is a dispatch timer rather than a parked helper thread. Contained
        // like `post`. A delay too large for dispatch's clock runs at the far horizon instead.
        let when =
            dispatch2::DispatchTime::try_from(std::time::Duration::from_millis(u64::from(ms)))
                .unwrap_or(dispatch2::DispatchTime::FOREVER);
        if let Err(e) = dispatch2::DispatchQueue::main().after(when, move || {
            ffi_guard::contain((), f);
        }) {
            log::error!("day-toolkit-appkit: dispatch_after refused a timer: {e:?}");
        }
    }

    fn locale_hints(&self) -> Vec<String> {
        // The user's ordered language preference from Settings ("fr-FR", "en-US", …), which is
        // the ambient locale Day negotiates its catalogs against (§12.2, docs/localization.md).
        objc2_foundation::NSLocale::preferredLanguages()
            .iter()
            .map(|s| s.to_string())
            .collect()
    }
}

// `CGWindowListCreateImage` is obsoleted as of the macOS 15 SDK (ScreenCaptureKit is the
// sanctioned replacement) but still resolves and answers on macOS 26. It is declared here rather
// than taken from a binding because the availability attribute would refuse the call outright,
// and every use below treats a NULL return as "ask the offscreen path instead".
unsafe extern "C" {
    fn CGWindowListCreateImage(
        bounds: objc2_core_foundation::CGRect,
        list_option: u32,
        window_id: u32,
        image_option: u32,
    ) -> *mut objc2_core_graphics::CGImage;
}

/// kCGWindowListOptionIncludingWindow — composite only this window, so whatever is stacked over
/// it (another app, a CI runner's stray window) cannot appear in the capture.
const CG_WINDOW_LIST_INCLUDING_WINDOW: u32 = 1 << 3;
/// kCGWindowImageBoundsIgnoreFraming — the window's own frame, without its drop shadow, which
/// makes the returned image exactly `window.frame()` at the backing scale.
const CG_WINDOW_IMAGE_IGNORE_FRAMING: u32 = 1 << 0;

/// Encode a captured rep as PNG, in sRGB.
///
/// A capture arrives in the color space of the display it was composited for, and a PNG of it
/// embeds that display's ICC profile: the same color then has different sample values on every
/// machine, and on every other Day target, which all capture sRGB. Converting first makes a
/// macOS capture's samples comparable with theirs and independent of the capturing display.
fn png_of_rep(rep: &objc2_app_kit::NSBitmapImageRep) -> Result<Vec<u8>, String> {
    let srgb = rep.bitmapImageRepByConvertingToColorSpace_renderingIntent(
        &objc2_app_kit::NSColorSpace::sRGBColorSpace(),
        objc2_app_kit::NSColorRenderingIntent::Default,
    );
    let rep = srgb.as_deref().unwrap_or(rep);
    let data = unsafe {
        rep.representationUsingType_properties(NSBitmapImageFileType::PNG, &NSDictionary::new())
    }
    .ok_or("png encode failed")?;
    Ok(data.to_vec())
}

/// Capture `content` by asking the WINDOW SERVER for the composited window and cropping to it.
///
/// This exists because an offscreen render cannot draw macOS's own materials. As of macOS 26 a
/// sidebar `NSSplitViewItem` is a Liquid Glass surface the window server composites from what is
/// behind it; `cacheDisplayInRect` has no backdrop to sample, so it renders the sidebar as an
/// opaque white slab with none of its rows in it — every macos-appkit gallery shot had a blank
/// sidebar. The window server has the real pixels, including the rows.
///
/// It answers only while the window is actually on screen. A hidden, minimized or
/// never-composited window has no image to hand back (verified: hiding the app makes this return
/// NULL while the offscreen path still produces a frame), so this returns `Err` and the caller
/// falls back rather than failing the capture.
fn snapshot_via_window_server(content: &NSView, chrome: bool) -> Result<Vec<u8>, String> {
    let window = content.window().ok_or("view is not in a window")?;
    // An attached sheet is the active modal surface and has its own composited window.
    // Capturing only the parent's window would show dimmed content without the modal UI.
    if let Some(sheet) = window.attachedSheet().and_then(|s| s.contentView()) {
        return snapshot_via_window_server(&sheet, chrome);
    }
    let number = window.windowNumber();
    if number <= 0 {
        return Err(format!("window {number} is not on screen"));
    }
    // The server hands back the frame it last COMPOSITED, which is the previous one whenever the
    // app has changed the view tree since. A capture taken right after a state change then shows
    // the state before it — a `when` whose outgoing arm is already gone from the tree and from the
    // view hierarchy still appears in the image, so a walkthrough asserting on pixels reads a
    // stale frame as "the change did not happen". Push the pending work out first: lay out, draw,
    // then commit the layer tree to the render server.
    unsafe { content.layoutSubtreeIfNeeded() };
    window.displayIfNeeded();
    CATransaction::flush();
    // CGRectNull asks for the window's own bounds rather than a screen region.
    let null_rect = objc2_core_foundation::CGRect::new(
        objc2_core_foundation::CGPoint::new(f64::INFINITY, f64::INFINITY),
        objc2_core_foundation::CGSize::new(0.0, 0.0),
    );
    let shot = unsafe {
        CGWindowListCreateImage(
            null_rect,
            CG_WINDOW_LIST_INCLUDING_WINDOW,
            number as u32,
            CG_WINDOW_IMAGE_IGNORE_FRAMING,
        )
    };
    if shot.is_null() {
        return Err("the window server has no image for this window".into());
    }
    // SAFETY: non-NULL CGImageRef owned by this call (Create rule); CFRetained takes that
    // ownership over, so it is released exactly once.
    let shot = unsafe {
        objc2_core_foundation::CFRetained::from_raw(std::ptr::NonNull::new_unchecked(shot))
    };

    // A chrome capture is the window image as the server composited it — titlebar, toolbar and
    // rounded corners included — so it is done here, before the crop.
    if chrome {
        let rep = unsafe {
            objc2_app_kit::NSBitmapImageRep::initWithCGImage(
                objc2_app_kit::NSBitmapImageRep::alloc(),
                &shot,
            )
        };
        return png_of_rep(&rep);
    }

    // Crop the window frame down to the content view. Keeping the framing identical to the
    // offscreen path is the point: the titlebar has never been part of a Day capture, and every
    // published gallery shot would otherwise change size.
    let frame = window.frame();
    if frame.size.width <= 0.0 || frame.size.height <= 0.0 {
        return Err("zero-size window".into());
    }
    let scale = objc2_core_graphics::CGImage::width(Some(&shot)) as f64 / frame.size.width;
    // Cocoa rects are bottom-left origin; a CGImage's are top-left, so the content's distance
    // from the window top is what the crop needs.
    let in_window = unsafe { content.convertRect_toView(content.bounds(), None) };
    let from_top = frame.size.height - (in_window.origin.y + in_window.size.height);
    let crop = objc2_core_foundation::CGRect::new(
        objc2_core_foundation::CGPoint::new(
            (in_window.origin.x * scale).round(),
            (from_top * scale).round(),
        ),
        objc2_core_foundation::CGSize::new(
            (in_window.size.width * scale).round(),
            (in_window.size.height * scale).round(),
        ),
    );
    let cropped = objc2_core_graphics::CGImage::with_image_in_rect(Some(&shot), crop)
        .ok_or("crop to the content view failed")?;
    let rep = unsafe {
        objc2_app_kit::NSBitmapImageRep::initWithCGImage(
            objc2_app_kit::NSBitmapImageRep::alloc(),
            &cropped,
        )
    };
    png_of_rep(&rep)
}

/// Capture a window content view as PNG (the dayscript screenshot seam, §14).
///
/// The window server first, because it is the only one of the two that can show macOS's own
/// composited materials; the offscreen render when it declines, because it is the only one of the
/// two that works with no window on screen. See each for why.
/// Put a [`Transform`] on a view through its own geometry rather than its layer: the frame is
/// the laid-out `base` scaled about its center and moved by the translation, the bounds keep the
/// laid-out size (so the content draws at the scale), and the rotation is the frame's center
/// rotation (positive is clockwise on screen: Day's parents are flipped, y down).
fn apply_geometry(v: &NSView, base: [f64; 4], t: Transform) {
    let [x, y, w, h] = base;
    let (sw, sh) = (w * t.sx, h * t.sy);
    let frame = NSRect::new(
        NSPoint::new(x + (w - sw) / 2.0 + t.tx, y + (h - sh) / 2.0 + t.ty),
        NSSize::new(sw, sh),
    );
    unsafe {
        // The rotation goes first and comes back last: a rotated view's frame is its bounding
        // box, so setting the frame of a rotated view would scale it.
        v.setFrameCenterRotation(0.0);
        v.setFrame(frame);
        v.setBoundsSize(NSSize::new(w, h));
        if t.rotate_deg != 0.0 {
            v.setFrameCenterRotation(t.rotate_deg);
        }
    }
}

fn snapshot_view(content: &NSView) -> Result<Vec<u8>, String> {
    let modal = content
        .window()
        .and_then(|w| w.attachedSheet())
        .and_then(|s| s.contentView());
    let content = modal.as_deref().unwrap_or(content);
    match snapshot_via_window_server(content, false) {
        Ok(bytes) => Ok(bytes),
        Err(_) => snapshot_view_cache(content),
    }
}

/// Capture a window *with* its chrome — the titlebar and toolbar the content capture crops away
/// (`day::window_image().chrome()`, docs/window-image.md).
///
/// Only the window server can produce this: the offscreen path renders the content view's own
/// hierarchy, which the titlebar is not part of. When it declines (an offscreen or hidden window)
/// the content capture stands in — a smaller image beats no image, and it is what the caller
/// would have got from the plain duty.
fn snapshot_view_chrome(content: &NSView) -> Result<Vec<u8>, String> {
    let modal = content
        .window()
        .and_then(|w| w.attachedSheet())
        .and_then(|s| s.contentView());
    let content = modal.as_deref().unwrap_or(content);
    match snapshot_via_window_server(content, true) {
        Ok(bytes) => Ok(bytes),
        Err(_) => snapshot_view_cache(content),
    }
}

/// The offscreen fallback: `cacheDisplayInRect` over a window-background pre-fill resolved for
/// the view's light/dark appearance. Renders the view hierarchy Day drew, and nothing the window
/// server composites (see `snapshot_via_window_server`).
fn snapshot_view_cache(content: &NSView) -> Result<Vec<u8>, String> {
    let bounds = content.bounds();
    let rep =
        unsafe { content.bitmapImageRepForCachingDisplayInRect(bounds) }.ok_or("no bitmap rep")?;
    // Day containers are transparent (the window server paints the backdrop), so pre-fill
    // the rep with the window background — resolved for the window's light/dark appearance —
    // before compositing the view hierarchy over it (§14).
    let ctx =
        NSGraphicsContext::graphicsContextWithBitmapImageRep(&rep).ok_or("no graphics context")?;
    NSGraphicsContext::saveGraphicsState_class();
    NSGraphicsContext::setCurrentContext(Some(&ctx));
    content
        .effectiveAppearance()
        .performAsCurrentDrawingAppearance(&block2::StackBlock::new(|| unsafe {
            NSColor::windowBackgroundColor().setFill();
            objc2_app_kit::NSRectFill(bounds);
        }));
    NSGraphicsContext::restoreGraphicsState_class();
    unsafe { content.cacheDisplayInRect_toBitmapImageRep(bounds, &rep) };
    png_of_rep(&rep)
}

/// The screen a scripted run asked to open on: `DAY_WINDOW_SCREEN`, the CGDirectDisplayID of the
/// capture display `day launch --script` provides when no attached display has the capture's
/// scale. `None` when unset or when no screen has that id, which leaves the window where it was.
fn capture_screen(mtm: MainThreadMarker) -> Option<Retained<objc2_app_kit::NSScreen>> {
    let wanted: u32 = std::env::var("DAY_WINDOW_SCREEN")
        .ok()?
        .trim()
        .parse()
        .ok()?;
    let key = NSString::from_str("NSScreenNumber");
    objc2_app_kit::NSScreen::screens(mtm)
        .into_iter()
        .find(|screen| {
            let number: Option<Retained<objc2_foundation::NSNumber>> =
                unsafe { msg_send![&*screen.deviceDescription(), objectForKey: &*key] };
            number.is_some_and(|n| n.unsignedIntValue() == wanted)
        })
}

/// Recursively mark a view tree as needing display (startup first-frame fix, see `run`).
fn mark_tree_needs_display(view: &NSView) {
    view.setNeedsDisplay(true);
    for sub in view.subviews() {
        mark_tree_needs_display(&sub);
    }
}

/// Which lifecycle phases this desktop backend delivers (docs/lifecycle.md): the universal set.
/// macOS has no true background/foreground or memory-warning lifecycle. `const` so
/// `day::require_lifecycle!` can reject unsupported phases at compile time. Must agree with the
/// `Toolkit::supports_lifecycle` default (which also returns `is_universal`).
pub const fn lifecycle_supported(phase: day_spec::Lifecycle) -> bool {
    phase.is_universal()
}

/// Follow the SYSTEM appearance while the app runs: macOS posts the distributed
/// "AppleInterfaceThemeChangedNotification" on a theme switch, and AppKit updates
/// `effectiveAppearance` just after — so re-read on the next main-queue turn and refresh
/// day-core's reactive dark-mode signal (palette closures recolor live instead of going
/// stale until the next rebuild). The token is leaked to observe for the app's lifetime.
fn install_appearance_observer() {
    use objc2_foundation::{NSDistributedNotificationCenter, NSNotification, NSString};
    let center = unsafe { NSDistributedNotificationCenter::defaultCenter() };
    let block = block2::RcBlock::new(move |_: std::ptr::NonNull<NSNotification>| {
        dispatch2::DispatchQueue::main()
            .exec_async(|| ffi_guard::contain((), day_core::note_appearance_changed));
    });
    let name = NSString::from_str("AppleInterfaceThemeChangedNotification");
    let token = unsafe {
        center.addObserverForName_object_queue_usingBlock(Some(&name), None, None, &block)
    };
    std::mem::forget(token);
}

/// Follow the SYSTEM reduce-motion switch while the app runs: NSWorkspace posts
/// `NSWorkspaceAccessibilityDisplayOptionsDidChangeNotification` on its own notification
/// center when any Accessibility › Display option flips, and
/// `accessibilityDisplayShouldReduceMotion` already answers the new value by then. The
/// notification arrives on the main thread; the main-queue hop keeps the re-read off the
/// poster's stack, as the appearance observer does. The token is leaked to observe for the
/// app's lifetime.
fn install_reduce_motion_observer() {
    use objc2_foundation::NSNotification;
    let center = objc2_app_kit::NSWorkspace::sharedWorkspace().notificationCenter();
    let block = block2::RcBlock::new(move |_: std::ptr::NonNull<NSNotification>| {
        dispatch2::DispatchQueue::main()
            .exec_async(|| ffi_guard::contain((), day_core::note_motion_changed));
    });
    let token = unsafe {
        center.addObserverForName_object_queue_usingBlock(
            Some(objc2_app_kit::NSWorkspaceAccessibilityDisplayOptionsDidChangeNotification),
            None,
            None,
            &block,
        )
    };
    std::mem::forget(token);
}

/// Bridge the NSApplication activation/termination notifications to day lifecycle events
/// (docs/lifecycle.md). The observer tokens are leaked to live for the whole app.
fn install_lifecycle_observers() {
    use objc2_foundation::{NSNotification, NSNotificationCenter, NSNotificationName};
    let center = unsafe { NSNotificationCenter::defaultCenter() };
    let observe = |name: &NSNotificationName, phase: day_spec::Lifecycle| {
        let block = block2::RcBlock::new(move |_: std::ptr::NonNull<NSNotification>| {
            ffi_guard::contain((), || emit(day_spec::WINDOW_NODE, Event::Lifecycle(phase)));
        });
        let token = unsafe {
            center.addObserverForName_object_queue_usingBlock(Some(name), None, None, &block)
        };
        std::mem::forget(token); // observe for the app's lifetime
    };
    unsafe {
        observe(
            NSApplicationDidBecomeActiveNotification,
            day_spec::Lifecycle::DidBecomeActive,
        );
        observe(
            NSApplicationWillResignActiveNotification,
            day_spec::Lifecycle::WillResignActive,
        );
        observe(
            NSApplicationWillTerminateNotification,
            day_spec::Lifecycle::WillTerminate,
        );
        // `terminate:` exits the process from inside the run loop, so the loop never returns to
        // `launch_with`: the last Day code to run is this notification's second observer, which
        // NSNotificationCenter calls after the first (docs/lifecycle.md).
        observe(
            NSApplicationWillTerminateNotification,
            day_spec::Lifecycle::DidExit,
        );
    }
}

day_localization_ui::locales!();

/// Shared by the initial menu and every reactive replacement. AppKit owns Services
/// and the hide actions; these commands must not depend on a window or app callback.
fn install_application_menu(
    mtm: MainThreadMarker,
    menubar: &NSMenu,
    title: &str,
    about: Option<day_spec::MenuItem>,
    updates: Option<day_spec::MenuItem>,
    prefs: Option<day_spec::MenuItem>,
    quit: Option<day_spec::MenuItem>,
) -> Retained<NSMenu> {
    let app = NSApplication::sharedApplication(mtm);
    use day_spec::{MenuItem as M, MenuRole as R};
    let standard = |role, label| M::Action {
        id: None,
        action: 0,
        label,
        shortcut: None,
        enabled: true,
        checked: None,
        role: Some(role),
        icon: None,
    };
    let mut about =
        about.unwrap_or_else(|| standard(R::About, res::str::about_app(title).format()));
    let mut quit = quit.unwrap_or_else(|| standard(R::Quit, res::str::quit_app(title).format()));
    for (item, title) in [
        (&mut about, res::str::about_app(title).format()),
        (&mut quit, res::str::quit_app(title).format()),
    ] {
        if let M::Action { label, .. } = item {
            *label = title;
        }
    }
    // A registered Day About (docs/settings.md) replaces the stock Info.plist panel: the
    // item fires the dispatch action instead of `orderFrontStandardAboutPanel:`.
    if let M::Action { action, .. } = &mut about
        && *action == 0
    {
        *action = day_core::windows::about_action_id();
    }
    // Check for Updates… sits directly under About (the Sparkle convention), whether the app
    // placed the role itself or the updater only registered its action.
    let updates_id = day_core::windows::check_for_updates_action_id();
    let updates = updates.or_else(|| {
        (updates_id != 0).then(|| {
            standard(
                R::CheckForUpdates,
                day_localization::t(day_localization::key::day_check_for_updates),
            )
        })
    });
    let mut head = vec![about];
    if let Some(mut updates) = updates {
        if let M::Action { action, .. } = &mut updates
            && *action == 0
        {
            *action = updates_id;
        }
        head.push(updates);
    }
    head.push(M::Separator);
    let menu = build_ns_menu(mtm, title, &head);
    if let Some(mut prefs) = prefs {
        if let M::Action { label, .. } = &mut prefs {
            *label = res::str::settings().format();
        }
        let section = build_ns_menu(mtm, title, &[prefs, M::Separator]);
        for item in section.itemArray() {
            section.removeItem(&item);
            menu.addItem(&item);
        }
    }
    // AppKit keeps the registered Services menu across main-menu replacements.
    // Move that same menu to the new bar rather than abandoning its system-populated items.
    let services = app.servicesMenu().unwrap_or_else(|| NSMenu::new(mtm));
    if let Some(parent) = unsafe { services.supermenu() } {
        let index = parent.indexOfItemWithSubmenu(Some(&services));
        if index >= 0 {
            parent.itemAtIndex(index).unwrap().setSubmenu(None);
        }
    }
    let services_item = NSMenuItem::new(mtm);
    services_item.setTitle(&NSString::from_str(&res::str::services().format()));
    services_item.setSubmenu(Some(&services));
    menu.addItem(&services_item);
    menu.addItem(&NSMenuItem::separatorItem(mtm));
    for (label, selector, shortcut) in [
        (
            res::str::hide_app(title).format(),
            sel!(hide:),
            Some(day_spec::Shortcut::primary("h")),
        ),
        (
            res::str::hide_others().format(),
            sel!(hideOtherApplications:),
            Some(day_spec::Shortcut::primary("h").alt()),
        ),
        (
            res::str::show_all().format(),
            sel!(unhideAllApplications:),
            None,
        ),
    ] {
        let item = unsafe {
            NSMenuItem::initWithTitle_action_keyEquivalent(
                NSMenuItem::alloc(mtm),
                &NSString::from_str(&label),
                Some(selector),
                &NSString::from_str(shortcut.as_ref().map_or("", |s| s.key.as_str())),
            )
        };
        if let Some(shortcut) = shortcut {
            item.setKeyEquivalentModifierMask(ns_modifiers(&shortcut));
        }
        // Explicitly target the application so window responders cannot override Hide.
        unsafe { item.setTarget(Some(&app)) };
        menu.addItem(&item);
    }
    menu.addItem(&NSMenuItem::separatorItem(mtm));
    let section = build_ns_menu(mtm, title, &[quit]);
    let quit = section.itemAtIndex(0).unwrap();
    section.removeItem(&quit);
    menu.addItem(&quit);
    let item = NSMenuItem::new(mtm);
    item.setSubmenu(Some(&menu));
    menubar.addItem(&item);
    services
}

/// The default main menu (§21.2 M2): standard application menu; Edit menu wired to the responder
/// chain so Cmd+C/V/X/A work in NSTextFields; Window menu basics.
fn install_main_menu(mtm: MainThreadMarker, app: &NSApplication, title: &str) {
    let menubar = NSMenu::new(mtm);

    let prefs_id = day_core::windows::preferences_action_id();
    let prefs = (prefs_id != 0).then(|| day_spec::MenuItem::Action {
        id: None,
        action: prefs_id,
        label: res::str::settings().format(),
        shortcut: None,
        enabled: true,
        checked: None,
        role: Some(day_spec::MenuRole::Preferences),
        icon: None,
    });
    let services = install_application_menu(mtm, &menubar, title, None, None, prefs, None);

    // File ▸ New Window / Close, when the app registered a new-window builder — the same
    // zero-menu-code rule as Settings…/⌘, above (docs/windows.md). Without this an app that
    // never calls `app_menu` gets the tab-bar "+" and the Window menu's tab commands but no
    // File ▸ New Window, because the default menu bar has no File menu to put it in.
    let new_window_id = day_core::windows::new_window_action_id();
    if new_window_id != 0 {
        let file_item = NSMenuItem::new(mtm);
        let file_menu = unsafe {
            NSMenu::initWithTitle(
                NSMenu::alloc(mtm),
                &NSString::from_str(&day_localization::t(day_localization::key::day_file)),
            )
        };
        let new_window = unsafe {
            NSMenuItem::initWithTitle_action_keyEquivalent(
                NSMenuItem::alloc(mtm),
                &NSString::from_str(&day_localization::t(day_localization::key::day_new_window)),
                Some(sel!(fire:)),
                &NSString::from_str("n"),
            )
        };
        let target = menu_target(mtm);
        let tobj: &objc2::runtime::AnyObject = target.as_ref();
        unsafe { new_window.setTarget(Some(tobj)) };
        new_window.setTag(new_window_id as isize);
        file_menu.addItem(&new_window);
        file_menu.addItem(&NSMenuItem::separatorItem(mtm));
        // Nil-targeted, so it closes whatever window is key — the standard responder route.
        let close = unsafe {
            NSMenuItem::initWithTitle_action_keyEquivalent(
                NSMenuItem::alloc(mtm),
                &NSString::from_str(&day_localization::t(day_localization::key::day_close)),
                Some(sel!(performClose:)),
                &NSString::from_str("w"),
            )
        };
        file_menu.addItem(&close);
        file_item.setSubmenu(Some(&file_menu));
        menubar.addItem(&file_item);
    }

    let edit_item = NSMenuItem::new(mtm);
    let edit_menu = unsafe {
        NSMenu::initWithTitle(
            NSMenu::alloc(mtm),
            &NSString::from_str(&day_localization::t(day_localization::key::day_edit)),
        )
    };
    let add = |key: &str, action: objc2::runtime::Sel, accel: &str| {
        let item = unsafe {
            NSMenuItem::initWithTitle_action_keyEquivalent(
                NSMenuItem::alloc(mtm),
                &NSString::from_str(&day_localization::t(key)),
                Some(action),
                &NSString::from_str(accel),
            )
        };
        edit_menu.addItem(&item);
    };
    add("day_undo", sel!(undo:), "z");
    add("day_redo", sel!(redo:), "Z");
    edit_menu.addItem(&NSMenuItem::separatorItem(mtm));
    add("day_cut", sel!(cut:), "x");
    add("day_copy", sel!(copy:), "c");
    add("day_paste", sel!(paste:), "v");
    add("day_select_all", sel!(selectAll:), "a");
    edit_item.setSubmenu(Some(&edit_menu));
    menubar.addItem(&edit_item);

    install_windows_menu(mtm, app, &menubar);

    app.setMainMenu(Some(&menubar));
    unsafe { app.setServicesMenu(Some(&services)) };
}

/// The standard Window menu (docs/windows.md): Minimize ⌘M / Zoom / Bring All to Front,
/// registered as `NSApp.windowsMenu` — AppKit then appends the open-window list and, with
/// tabbing live, the tab commands (Show Next/Previous Tab, Merge All Windows) itself. All
/// nav hosts are nil-targeted (responder chain), so they act on the key window.
fn install_windows_menu(mtm: MainThreadMarker, app: &NSApplication, menubar: &NSMenu) {
    let menu = unsafe {
        NSMenu::initWithTitle(
            NSMenu::alloc(mtm),
            &NSString::from_str(&day_localization::t(day_localization::key::day_window)),
        )
    };
    let add = |key: &str, action: objc2::runtime::Sel, accel: &str| {
        let item = unsafe {
            NSMenuItem::initWithTitle_action_keyEquivalent(
                NSMenuItem::alloc(mtm),
                &NSString::from_str(&day_localization::t(key)),
                Some(action),
                &NSString::from_str(accel),
            )
        };
        menu.addItem(&item);
    };
    add("day_minimize", sel!(performMiniaturize:), "m");
    add("day_zoom", sel!(performZoom:), "");
    menu.addItem(&NSMenuItem::separatorItem(mtm));
    add("day_bring_all_front", sel!(arrangeInFront:), "");
    let item = NSMenuItem::new(mtm);
    item.setTitle(&NSString::from_str(&day_localization::t(
        day_localization::key::day_window,
    )));
    item.setSubmenu(Some(&menu));
    menubar.addItem(&item);
    unsafe { app.setWindowsMenu(Some(&menu)) };
}

/// Hoist application roles even from nested menus. First declaration wins; remove
/// duplicates and empty containers, then normalize separators left by the move.
fn extract_app_role(
    items: &mut Vec<day_spec::MenuItem>,
    role: day_spec::MenuRole,
) -> Option<day_spec::MenuItem> {
    use day_spec::MenuItem as M;
    let mut found = None;
    let mut remaining = Vec::new();
    for mut item in items.drain(..) {
        match &mut item {
            M::Action { role: Some(r), .. } if *r == role => {
                found.get_or_insert(item);
                continue;
            }
            M::Submenu { items, .. } => {
                let nested = extract_app_role(items, role);
                if found.is_none() {
                    found = nested;
                }
                if items.is_empty() {
                    continue;
                }
            }
            M::Separator
                if remaining.is_empty() || matches!(remaining.last(), Some(M::Separator)) =>
            {
                continue;
            }
            _ => {}
        }
        remaining.push(item);
    }
    while matches!(remaining.last(), Some(M::Separator)) {
        remaining.pop();
    }
    *items = remaining;
    found
}

/// Whether any action in the model (recursively) carries `role`.
fn model_has_role(items: &[day_spec::MenuItem], role: day_spec::MenuRole) -> bool {
    items.iter().any(|it| match it {
        day_spec::MenuItem::Action { role: r, .. } => *r == Some(role),
        day_spec::MenuItem::Submenu { items, .. } => model_has_role(items, role),
        day_spec::MenuItem::Separator => false,
    })
}

// ---------------------------------------------------------------------------
// Menus (§ menus): render day's MenuItem model with NSMenu. Custom items route to a shared
// DayMenuTarget (id in the item's tag → Event::MenuAction); role items use the native selector.
// ---------------------------------------------------------------------------

define_class!(
    #[unsafe(super(NSObject))]
    #[thread_kind = MainThreadOnly]
    #[name = "DayMenuTarget"]
    #[ivars = ()]
    struct DayMenuTarget;

    unsafe impl NSObjectProtocol for DayMenuTarget {}

    impl DayMenuTarget {
        #[unsafe(method(fire:))]
        fn fire(&self, sender: &NSMenuItem) {
            ffi_guard::contain((), || {
                let id = sender.tag() as u64;
                if id != 0 {
                    emit(day_spec::WINDOW_NODE, Event::MenuAction(id));
                }
            })
        }
    }
);

/// The primary window's content view (set once in `run`).
/// Pin the window's content coordinate space under its title bar and toolbar (§7.7). The
/// content view is full-size (`FullSizeContentView`, for the unified toolbar), so it runs
/// beneath the bar; moving its bounds origin up by that strip makes Day's root, laid out from
/// (0, 0), start below the bar — the way UIKit pins the root inside `safeAreaInsets` — while
/// the view's own background still paints edge to edge. Returns the size Day lays out at, the
/// window's `contentLayoutRect`. Called wherever that rect can change: window creation, every
/// resize, and a toolbar coming or going.
pub(crate) fn pin_below_title_bar(window: &NSWindow) -> Option<Size> {
    let content = window.contentView()?;
    let full = content.frame().size;
    let layout = unsafe { window.contentLayoutRect() }.size;
    let top = (full.height - layout.height).max(0.0);
    // An overlay title bar (docs/window-chrome.md) is the one place the content belongs under
    // the bar: it keeps the full height, and the bar's height goes to the app as a safe-area
    // inset so it can pad its own content.
    if window_chrome::is_overlay(window) {
        unsafe { content.setBoundsOrigin(NSPoint::new(0.0, 0.0)) };
        window_chrome::report_title_bar_inset(window, top);
        return Some(Size::new(full.width, full.height));
    }
    unsafe { content.setBoundsOrigin(NSPoint::new(0.0, -top)) };
    Some(Size::new(full.width, (full.height - top).max(0.0)))
}

/// The text a widget displays, for `read_native`: a label's or text field's string, a
/// button's title, a text area's contents. `None` for a secure field (it masks its text), an
/// icon-only button (its title is a tooltip), and every other view.
fn native_text(h: &NSView) -> Option<String> {
    if h.downcast_ref::<NSSecureTextField>().is_some() {
        return None;
    }
    if let Some(tf) = h.downcast_ref::<NSTextField>() {
        // `stringValue` answers the field editor's live text while the field edits.
        return Some(tf.stringValue().to_string());
    }
    if let Some(btn) = h.downcast_ref::<NSButton>() {
        if unsafe { btn.imagePosition() } == objc2_app_kit::NSCellImagePosition::ImageOnly {
            return None;
        }
        return Some(btn.title().to_string());
    }
    // A text area is an NSTextView inside the scroll view its handle names (textarea.rs).
    let sv = h.downcast_ref::<NSScrollView>()?;
    let doc = sv.documentView()?;
    let tv = doc.downcast_ref::<NSTextView>()?;
    Some(tv.string().to_string())
}

/// A slider's value or a determinate progress bar's fraction, for `read_native`. Both native
/// ranges are the ones Day gave: the slider is built with Day's min and max, the bar runs 0–1.
fn native_number(h: &NSView) -> Option<f64> {
    if let Some(sl) = h.downcast_ref::<NSSlider>() {
        return Some(sl.doubleValue());
    }
    let pi = h.downcast_ref::<NSProgressIndicator>()?;
    (!pi.isIndeterminate()).then(|| pi.doubleValue())
}

/// The view's frame in its window's content coordinates, origin top left, for `read_native`.
/// The content view is flipped and pinned below the title bar (`pin_below_title_bar`), so
/// converting into it gives Day's layout space; an unflipped content view is flipped here.
fn native_frame(h: &NSView) -> Option<Rect> {
    let content = h.window()?.contentView()?;
    let r = h.convertRect_toView(h.bounds(), Some(&content));
    let y = if content.isFlipped() {
        r.origin.y
    } else {
        let b = content.bounds();
        b.origin.y + b.size.height - (r.origin.y + r.size.height)
    };
    Some(Rect::new(r.origin.x, y, r.size.width, r.size.height))
}

/// The strip a pinned content view keeps above its layout origin (see `pin_below_title_bar`).
fn title_bar_inset(content: &NSView) -> f64 {
    (-content.bounds().origin.y).max(0.0)
}

fn primary_content() -> Option<Retained<NSView>> {
    PRIMARY_CONTENT.with(|c| c.borrow().clone())
}

fn menu_target(mtm: MainThreadMarker) -> Retained<DayMenuTarget> {
    MENU_TARGET.with(|t| {
        t.borrow_mut()
            .get_or_insert_with(|| {
                let this = DayMenuTarget::alloc(mtm).set_ivars(());
                let obj: Retained<DayMenuTarget> = unsafe { msg_send![super(this), init] };
                obj
            })
            .clone()
    })
}

fn ns_modifiers(s: &day_spec::Shortcut) -> objc2_app_kit::NSEventModifierFlags {
    use objc2_app_kit::NSEventModifierFlags as F;
    let mut m = F::empty();
    if s.primary {
        m |= F::Command;
    }
    if s.shift {
        m |= F::Shift;
    }
    if s.alt {
        m |= F::Option;
    }
    if s.control {
        m |= F::Control;
    }
    m
}

/// A shortcut's key-equivalent string. Single chars pass through (lowercased); a few named keys map
/// to their control characters. Modifiers ride separately via `setKeyEquivalentModifierMask`.
fn ns_key_equivalent(key: &str) -> String {
    match key {
        "Return" | "Enter" => "\r".into(),
        "Tab" => "\t".into(),
        "Delete" | "Backspace" => "\u{8}".into(),
        "Escape" => "\u{1b}".into(),
        "Space" => " ".into(),
        k if k.chars().count() == 1 => k.to_lowercase(),
        _ => String::new(), // named keys we don't map get no key-equivalent (still shown in menu)
    }
}

/// A standard role → (default label, nav host, default shortcut). Nav host `None` = no native action
/// (the app should attach its own via a custom item); the role then only supplies label placement.
fn role_spec(
    role: day_spec::MenuRole,
) -> (
    &'static str,
    Option<objc2::runtime::Sel>,
    Option<day_spec::Shortcut>,
) {
    use day_spec::MenuRole as R;
    use day_spec::Shortcut as S;
    match role {
        R::Cut => ("Cut", Some(sel!(cut:)), Some(S::primary("x"))),
        R::Copy => ("Copy", Some(sel!(copy:)), Some(S::primary("c"))),
        R::Paste => ("Paste", Some(sel!(paste:)), Some(S::primary("v"))),
        R::SelectAll => ("Select All", Some(sel!(selectAll:)), Some(S::primary("a"))),
        R::Undo => ("Undo", Some(sel!(undo:)), Some(S::primary("z"))),
        R::Redo => ("Redo", Some(sel!(redo:)), Some(S::primary("z").shift())),
        R::Delete => ("Delete", Some(sel!(delete:)), None),
        R::About => ("About", Some(sel!(orderFrontStandardAboutPanel:)), None),
        R::Quit => ("Quit", Some(sel!(terminate:)), Some(S::primary("q"))),
        R::Preferences => ("Settings…", None, Some(S::primary(","))),
        R::Minimize => (
            "Minimize",
            Some(sel!(performMiniaturize:)),
            Some(S::primary("m")),
        ),
        R::CloseWindow => ("Close", Some(sel!(performClose:)), Some(S::primary("w"))),
        R::Fullscreen => (
            "Enter Full Screen",
            Some(sel!(toggleFullScreen:)),
            Some(S::primary("f").control()),
        ),
        // No native selector (docs/windows.md): the item dispatches the registered
        // new-window action through the ordinary custom-item path (`fire:`).
        R::NewWindow => ("New Window", None, Some(S::primary("n"))),
        // Likewise: no selector, the registered updater action fires through `fire:`.
        R::CheckForUpdates => ("Check for Updates…", None, None),
    }
}

pub(crate) fn build_ns_menu(
    mtm: MainThreadMarker,
    title: &str,
    items: &[day_spec::MenuItem],
) -> Retained<NSMenu> {
    use day_spec::MenuItem as MI;
    let menu = unsafe { NSMenu::initWithTitle(NSMenu::alloc(mtm), &NSString::from_str(title)) };
    let target = menu_target(mtm);
    for item in items {
        match item {
            MI::Separator => menu.addItem(&NSMenuItem::separatorItem(mtm)),
            MI::Submenu { label, items, .. } => {
                let sub = build_ns_menu(mtm, label, items);
                let it = NSMenuItem::new(mtm);
                it.setTitle(&NSString::from_str(label));
                it.setSubmenu(Some(&sub));
                menu.addItem(&it);
            }
            MI::Action {
                action,
                label,
                shortcut,
                enabled,
                checked,
                role,
                icon,
                ..
            } => {
                // Resolve label/nav host/shortcut, folding in the role's native defaults.
                let (mut lbl, sel, mut sc) = match role {
                    Some(r) => {
                        let (dl, ds, dsc) = role_spec(*r);
                        (dl.to_string(), ds, dsc)
                    }
                    None => (String::new(), None, None),
                };
                if !label.is_empty() {
                    lbl = label.clone();
                }
                if shortcut.is_some() {
                    sc = shortcut.clone();
                }
                // Custom action (nonzero id) overrides any role nav host and targets our
                // trampoline — except the responder-routed set (undo pair, clipboard trio),
                // whose nonzero ids are only the other platforms' fallback dispatchers: here
                // the nil-target nav hosts must stay, so the responder chain resolves the
                // acting object (a focused text field before the app's bridge).
                let responder_role = matches!(
                    role,
                    Some(
                        day_spec::MenuRole::Undo
                            | day_spec::MenuRole::Redo
                            | day_spec::MenuRole::Cut
                            | day_spec::MenuRole::Copy
                            | day_spec::MenuRole::Paste
                            | day_spec::MenuRole::SelectAll
                    )
                );
                let custom = *action != 0 && !responder_role;
                let key = sc
                    .as_ref()
                    .map(|s| ns_key_equivalent(&s.key))
                    .unwrap_or_default();
                let it = unsafe {
                    NSMenuItem::initWithTitle_action_keyEquivalent(
                        NSMenuItem::alloc(mtm),
                        &NSString::from_str(&lbl),
                        if custom { Some(sel!(fire:)) } else { sel },
                        &NSString::from_str(&key),
                    )
                };
                if let Some(s) = &sc {
                    it.setKeyEquivalentModifierMask(ns_modifiers(s));
                    // AppKit's own per-layout/per-language adjustments (macOS 12+): remap a
                    // key equivalent the current keyboard layout cannot type, and MIRROR
                    // directional pairs (⌘[ / ⌘]) under RTL languages — the system half of
                    // shortcut localization; the catalog half is the `.key` attribute
                    // (docs/localization.md).
                    it.setAllowsAutomaticKeyEquivalentLocalization(true);
                    it.setAllowsAutomaticKeyEquivalentMirroring(true);
                }
                if custom {
                    let tobj: &objc2::runtime::AnyObject = target.as_ref();
                    unsafe { it.setTarget(Some(tobj)) };
                    it.setTag(*action as isize);
                }
                it.setEnabled(*enabled);
                // A checkable item takes NSMenuItem's own state, so macOS draws the ✓ it draws
                // everywhere else and reserves the mark's column when it is off (docs/menus.md).
                if let Some(on) = checked {
                    it.setState(if *on {
                        NSControlStateValueOn
                    } else {
                        NSControlStateValueOff
                    });
                }
                // The item's glyph, drawn the way NSMenuItem draws its own (docs/menus.md):
                // template-tinted, sized to the menu's text.
                if let Some(icon) = icon
                    && let Some(img) = crate::toolbar::image_for(icon, &lbl, mtm)
                {
                    img.setSize(NSSize::new(16.0, 16.0));
                    it.setImage(Some(&img));
                }
                menu.addItem(&it);
            }
        }
    }
    menu
}

// AppKit's TLS may be destroyed before the reactive arena drops its last Bitmap.
// The registry already released the native images in that case.
fn release_bitmap(id: day_spec::BitmapId) {
    let _ = BITMAPS.try_with(|m| m.borrow_mut().remove(&id.0));
}

#[cfg(test)]
mod bitmap_teardown_tests {
    use super::*;

    #[test]
    fn releasing_after_bitmap_registry_teardown_does_not_abort() {
        // Isolate destructor panics: Rust aborts the process when a TLS destructor unwinds.
        const CHILD: &str = "DAY_APPKIT_BITMAP_TEARDOWN_CHILD";
        if std::env::var_os(CHILD).is_some() {
            struct LateRelease;
            impl Drop for LateRelease {
                fn drop(&mut self) {
                    assert!(BITMAPS.try_with(|_| ()).is_err());
                    // Same duty called by Bitmap::drop; no NSApplication is needed.
                    release_bitmap(day_spec::BitmapId(1));
                }
            }
            std::thread_local! {
                static LATE: RefCell<Option<LateRelease>> = const { RefCell::new(None) };
            }
            std::thread::spawn(|| {
                LATE.with(|slot| *slot.borrow_mut() = Some(LateRelease));
                BITMAPS.with(|_| ()); // initialized last, destroyed first
            })
            .join()
            .unwrap();
            return;
        }
        let output = std::process::Command::new(std::env::current_exe().unwrap())
            .args([
                "--exact",
                "bitmap_teardown_tests::releasing_after_bitmap_registry_teardown_does_not_abort",
                "--nocapture",
            ])
            .env(CHILD, "1")
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "{}",
            String::from_utf8_lossy(&output.stderr)
        );
    }
}