plugin.zig

//! The pixel-art editor plugin: registration + draw entry points. Its contributions
//! reach the plugin's state through the `Globals` injection. Registered from
//! `Editor.postInit`.
const std = @import("std");
const builtin = @import("builtin");
const dvui = @import("dvui");
const icons = @import("icons");
const internal = @import("src/pixi.zig");
const sdk = internal.sdk;
const runtime = @import("src/runtime.zig");
const State = internal.State;
const Packer = internal.Packer;
const CanvasData = @import("src/CanvasData.zig");
const FileWidget = @import("src/widgets/FileWidget.zig");
const ImageWidget = @import("src/widgets/ImageWidget.zig");
const keybind_ticks = @import("src/keybind_ticks.zig");
const radial_menu = @import("src/radial_menu.zig");
const clipboard = @import("src/clipboard.zig");
const pack_project = @import("src/pack_project.zig");
const transform_op = @import("src/transform_op.zig");
const infobar_status = @import("src/infobar_status.zig");
const GridLayout = @import("src/dialogs/GridLayout.zig");
const NewFile = @import("src/dialogs/NewFile.zig");
const Export = @import("src/dialogs/Export.zig");
const commands = @import("src/commands.zig");

const DocHandle = sdk.DocHandle;
const Internal = internal.internal;

/// Injected at build time from `plugin.zig.zon` — required by fizzy's generated dylib root,
/// which reaches its own copy of this plugin's identity through this export rather than
/// importing `fizzy_plugin_options` itself (see fizzy's `docs/PLUGINS.md` §2.5).
pub const plugin_options = @import("fizzy_plugin_options");

pub const view_tools = "pixi.tools";
pub const view_sprites = "pixi.sprites";
pub const view_project = "pixi.project";
pub const view_project_preview = "pixi.project.preview";
pub const bottom_sprites = "pixi.sprites_panel";

pub fn selectSidebar(host: *sdk.Host, id: []const u8) void {
    host.setSelectionFor(sdk.keywords.ide.sidebar, id);
}

pub fn sidebarShows(host: *sdk.Host, id: []const u8) bool {
    const cur = host.selectionFor(sdk.keywords.ide.sidebar) orelse return false;
    return std.mem.eql(u8, cur, id);
}

var plugin: sdk.Plugin = .{
    .state = undefined,
    .vtable = &vtable,
    .id = plugin_options.id,
    .display_name = plugin_options.name,
    .step_format = @import("src/internal/steps.zig").format,
};

const vtable: sdk.Plugin.VTable = .{
    .deinit = pluginDeinit,
    .initPlugin = pluginInit,
    .fileTypes = fileTypes,
    .contributeKeybinds = contributeKeybinds,
    .loadDocument = loadDocument,
    .loadDocumentFromBytes = loadDocumentFromBytes,
    .loadUntitledDocument = loadUntitledDocument,
    .documentStackSize = documentStackSize,
    .documentStackAlign = documentStackAlign,
    .documentIdFromBuffer = documentIdFromBuffer,
    .deinitDocumentBuffer = deinitDocumentBuffer,
    .setDocumentGroupingOnBuffer = setDocumentGroupingOnBuffer,
    .createDocument = createDocument,
    .isDirty = isDirty,
    .captureDocumentState = captureDocumentState,
    .restoreDocumentState = restoreDocumentState,
    .applyStep = applyStep,
    .historyLine = historyLine,
    .historyGoTo = historyGoTo,
    .restoreHistory = restoreHistory,
    .documentFingerprint = documentFingerprint,
    .documentSnapshot = documentSnapshot,
    .encodeSnapshot = encodeSnapshot,
    .releaseSnapshot = releaseSnapshot,
    .documentWritten = documentWritten,
    .reloadDocument = reloadDocument,
    .closeDocument = closeDocument,
    .registerOpenDocument = registerOpenDocument,
    .documentPtr = documentPtr,
    .documentByPath = documentByPath,
    .unregisterDocument = unregisterDocument,
    .bindDocumentToPane = bindDocumentToPane,
    .documentGrouping = documentGrouping,
    .setDocumentGrouping = setDocumentGrouping,
    .documentPath = documentPath,
    .setDocumentPath = setDocumentPath,
    .documentHasNativeExtension = documentHasNativeExtension,
    .documentHasRecognizedSaveExtension = documentHasRecognizedSaveExtension,
    .documentDefaultSaveAsFilename = documentDefaultSaveAsFilename,
    .drawDocument = drawDocument,
    .infobarEntries = infobarEntries,
    // universal per-frame phases (pixel-art does its raster/canvas work inside them)
    .beginFrame = beginFrame,
    .prepareFrame = warmupActiveDocumentComposites,
    .tickKeybinds = tickKeybinds,
    .tickActiveDocument = tickActiveDocumentPlayback,
    .drawOverlay = drawOverlay,
    .endFrame = resetDocumentPeekLayers,
    .needsContinuousRepaint = isAnyDocumentActivelyDrawing,
    // folder lifecycle + save protocol
    .saveQuestion = saveQuestion,
};

/// A `DocHandle` for one of this plugin's open `*Internal.File`s. Resolved by `doc.id`
/// because `docs.files` may reallocate and stale `doc.ptr` values.
fn docFile(doc: DocHandle) *Internal.File {
    return runtime.state().docs.fileById(doc.id).?;
}

/// Extensions pixi offers to open: its native `.pixi`/`.fiz` plus the flat images it can
/// import and export. This is an *offer*, not a claim — which plugin actually opens a given
/// extension is the user's persisted choice (fizzy prompts when two plugins offer the same one
/// and surfaces the result in Settings > File Types). There is no numeric priority to win.
fn fileTypes(_: *anyopaque) []const []const u8 {
    return &.{ ".pixi", ".fiz", ".png", ".jpg", ".jpeg" };
}

/// Natural size reported for an atlas sprite icon, as a multiple of its native pixel size.
///
/// With `expand = .ratio` (see `host_slot_fit`) this no longer decides how big the icon *renders*
/// — the host's slot does that, and a ratio fit is invariant under a uniform scale of the
/// requested size. It only sets the min size reported upward for hosts that lay out around it.
const file_icon_sprite_scale: f32 = 2.0;

/// Fill the slot the host reserved for us.
///
/// The shell reserves a fixed rect per tree row (`core.widgets.treeRowGlyph`) and every icon —
/// vector, sprite, or letter — is expected to fit itself into it with `expand = .ratio`. Drawing
/// at a size of our own choosing instead makes pixi's rows taller than everyone else's and knocks
/// the labels out of alignment, which is exactly what the hard-coded scales below used to do.
const host_slot_fit: dvui.Options = .{
    .expand = .ratio,
    .gravity_x = 0.5,
    .gravity_y = 0.5,
    .padding = dvui.Rect.all(0),
    .margin = dvui.Rect.all(0),
};

/// Draw the file-tree icon for the file types pixi owns: its own `ui_atlas` sprites for
/// `.fiz` (the `fiz` animation in `assets/src/misc.pixi`) and `.pixi` (the `pixi` animation),
/// plus a generic vector icon for flat images. Returns false for anything else so the workbench
/// falls back to a generic icon.
/// One painter for both the file-tree glyph and the plugin logo (`Host.Painter`).
fn paint(_: ?*anyopaque, subject: sdk.Host.Painter.Subject) bool {
    const ui_atlas = runtime.uiAtlas();
    const file = switch (subject) {
        .file => |f| f,
        .plugin_logo => {
            _ = ui_atlas.sprites[internal.atlas.sprites.pixi_default].draw(@src(), ui_atlas.source, file_icon_sprite_scale, host_slot_fit);
            return true;
        },
    };
    const ext = file.ext;
    const color = file.color;
    if (std.ascii.eqlIgnoreCase(ext, ".fiz")) {
        _ = ui_atlas.sprites[internal.atlas.sprites.fiz_default].draw(@src(), ui_atlas.source, file_icon_sprite_scale, host_slot_fit);
        return true;
    }
    if (std.ascii.eqlIgnoreCase(ext, ".pixi")) {
        _ = ui_atlas.sprites[internal.atlas.sprites.pixi_default].draw(@src(), ui_atlas.source, file_icon_sprite_scale, host_slot_fit);
        return true;
    }
    if (Internal.File.isFlatImageExtension(ext)) {
        dvui.icon(@src(), "PixiFileIcon", dvui.entypo.image, .{ .stroke_color = .{ .color = color }, .fill_color = .{ .color = color } }, host_slot_fit.override(.{ .background = false }));
        return true;
    }
    return false;
}

/// Load `path` into the plugin-owned `*Internal.File` at `out_doc`. Runs on the shell's
/// load worker thread; `File.fromPath` is the pixel-art loader.
fn loadDocument(_: *anyopaque, path: []const u8, out_doc: *anyopaque) anyerror!void {
    // Web loads via bytes only (`loadDocumentFromBytes`); the comptime guard keeps the
    // disk-reading `File.fromPath` path (Dir.cwd / posix.AT) out of the wasm binary.
    if (comptime builtin.target.cpu.arch == .wasm32) return error.Unsupported;
    const file = try Internal.File.fromPath(path) orelse return error.InvalidFile;
    @as(*Internal.File, @ptrCast(@alignCast(out_doc))).* = file;
}

/// As `loadDocument`, from in-memory bytes (browser file picker; synchronous).
fn loadDocumentFromBytes(_: *anyopaque, path: []const u8, bytes: []const u8, out_doc: *anyopaque) anyerror!void {
    const file = try Internal.File.fromBytes(path, bytes) orelse return error.InvalidFile;
    @as(*Internal.File, @ptrCast(@alignCast(out_doc))).* = file;
}

/// A sprite never saved, back from its unsaved bytes after a crash or a restart: read as the
/// format they were written in (`bytes_path`, `untitled.pixi`), then given its title back. A path
/// with no extension is what keeps it untitled and unsaved (`File.dirty`), so Save offers Save As.
fn loadUntitledDocument(_: *anyopaque, title: []const u8, bytes_path: []const u8, bytes: []const u8, out_doc: *anyopaque) anyerror!void {
    var file = try Internal.File.fromBytes(bytes_path, bytes) orelse return error.InvalidFile;
    errdefer file.deinit();
    const gpa = runtime.allocator();
    const owned = try gpa.dupe(u8, title);
    gpa.free(file.path);
    file.path = owned;
    @as(*Internal.File, @ptrCast(@alignCast(out_doc))).* = file;
}

/// A tape's seek takes a sprite's pixels, and puts them back in place rather than reopening it.
fn captureDocumentState(_: *anyopaque, doc: DocHandle, allocator: std.mem.Allocator) anyerror![]u8 {
    return docFile(doc).captureState(allocator);
}
fn restoreDocumentState(_: *anyopaque, doc: DocHandle, bytes: []const u8) anyerror!void {
    try docFile(doc).restoreState(bytes);
}

fn historyLine(_: *anyopaque, doc: DocHandle, arena: std.mem.Allocator) anyerror!sdk.Plugin.HistoryLine {
    const history = &docFile(doc).history;
    const steps = try history.line(arena);
    const entries = try arena.alloc(sdk.Plugin.HistoryLine.Entry, steps.len);
    for (steps, entries) |st, *e| e.* = .{ .id = st.id, .title = st.title };
    return .{ .version = history.version, .entries = entries, .at = history.undo_stack.items.len };
}

fn historyGoTo(_: *anyopaque, doc: DocHandle, id: u64) anyerror!void {
    const file = docFile(doc);
    try commands.refuseWhilePersonBusy(file);
    try file.history.goTo(file, id);
}

fn documentFingerprint(_: *anyopaque, doc: DocHandle) u64 {
    return docFile(doc).fingerprint();
}

fn restoreHistory(_: *anyopaque, doc: DocHandle, history: sdk.Plugin.RestoredHistory) anyerror!void {
    const file = docFile(doc);
    try file.history.restore(file, history);
}

fn applyStep(_: *anyopaque, doc: DocHandle, effect: []const u8, motion: []const u8, ms: u32) anyerror!void {
    try docFile(doc).applyStep(effect, motion, ms > 0);
}

fn isDirty(_: *anyopaque, doc: DocHandle) bool {
    return docFile(doc).dirty();
}

/// A save is a snapshot on the UI thread and an encode on fizzy's worker; fizzy writes the bytes
/// wherever the document lives (the disk, a mounted drive, the browser's download) and reports back
/// through `documentWritten`. `path` picks the format, so Save As to a `.png` writes a PNG.
fn documentSnapshot(_: *anyopaque, doc: DocHandle, path: []const u8, allocator: std.mem.Allocator) anyerror!*anyopaque {
    return @ptrCast(try docFile(doc).saveSnapshot(path, allocator));
}
fn encodeSnapshot(_: *anyopaque, snapshot: *anyopaque, _: []const u8, allocator: std.mem.Allocator) anyerror![]u8 {
    return Internal.File.encode(@ptrCast(@alignCast(snapshot)), allocator);
}
fn releaseSnapshot(_: *anyopaque, snapshot: *anyopaque) void {
    const snap: *Internal.File.Snapshot = @ptrCast(@alignCast(snapshot));
    snap.destroy();
}
fn saveQuestion(_: *anyopaque, doc: DocHandle, path: []const u8, allocator: std.mem.Allocator) ?sdk.Plugin.SaveQuestion {
    return docFile(doc).saveQuestion(path, allocator);
}
fn documentWritten(_: *anyopaque, doc: DocHandle, path: []const u8) anyerror!void {
    try docFile(doc).written(path);
}

/// Reload from disk when the shell's document watcher sees an external change on a
/// clean tab (or the user picks Discard in the on-disk conflict dialog).
fn reloadDocument(_: *anyopaque, doc: DocHandle) anyerror!void {
    try docFile(doc).reloadFromDisk();
}

/// Release the document's resources. The shell removes it from `open_files` and
/// fixes up the active-tab index; this just frees the pixel-art `File`.
fn closeDocument(_: *anyopaque, doc: DocHandle) void {
    docFile(doc).deinit();
}

/// Render the open pixel-art document into the workbench-provided content region (the
/// current dvui parent). The workbench owns only the container + tab/split frame and sets
/// `canvas.id` / `workspace_handle` / `center` before routing here; pixi owns the
/// entire region: rulers, the canvas hbox, the transform/edit/sample overlays, the editing
/// widget, and the sample magnifier. The per-pane ruler/overlay/reorder state + draw helpers
/// live on the pixel-art-owned `CanvasData` (keyed by workbench pane `grouping` on `State`).
fn drawDocument(_: *anyopaque, doc: DocHandle) anyerror!void {
    const file = docFile(doc);
    const canvas = CanvasData.forGrouping(file.editor.grouping);
    const container = dvui.parentGet().data();

    // Grid (column/row) reorder is driven by the rulers and consumed by `FileWidget`; commit
    // the pending reorder and clear the per-frame drag indices after the whole document (incl.
    // the file widget) has drawn. Registered first so they run last.
    defer canvas.columns_drag_index = null;
    defer canvas.rows_drag_index = null;
    defer canvas.processColumnReorder(file);
    defer canvas.processRowReorder(file);

    internal.perf.canvasPaneDrawn();

    if (runtime.state().settings.show_rulers.get() and !dvui.firstFrame(container.id)) {
        const prof = internal.profile.section("rulers");
        defer prof.end();
        canvas.drawRuler(file, .horizontal);
    }

    var canvas_hbox = dvui.box(@src(), .{ .dir = .horizontal }, .{ .expand = .both });
    defer canvas_hbox.deinit();

    if (runtime.state().settings.show_rulers.get() and !dvui.firstFrame(container.id)) {
        const prof = internal.profile.section("rulers");
        defer prof.end();
        canvas.drawRuler(file, .vertical);
    }

    canvas.drawTransformDialog(file, container);
    // Before the file widget so FloatingWidget uses window-scale coords (not canvas zoom).
    // Right to left: each floats over what came before it, a tooltip only over what its own
    // bubble floats over, and each button's tooltip opens to its right, over its neighbours.
    canvas.drawFitButton(container, file);
    canvas.drawSampleButton(container, file);
    canvas.drawEditPill(container, file);

    var file_widget = FileWidget.init(@src(), .{
        .file = file,
        .center = file.editor.center,
    }, .{
        .expand = .both,
        .background = false,
        .color_fill = .transparent,
    });
    defer file_widget.deinit();
    file_widget.processEvents();

    if (dvui.dataGet(null, file.editor.canvas.id, "sample_data_point", dvui.Point)) |data_pt| {
        if (file.editor.canvas.samplePointerInViewport(dvui.currentWindow().mouse_pt)) {
            FileWidget.drawSampleMagnifier(file, data_pt);
        }
    }
}

/// Packed-atlas preview. A surface of its own (`takeover_when = pixi.project`) so
/// the layout shows it in Main while Project is selected, without a workbench hook.
fn drawProjectView(_: ?*anyopaque) anyerror!dvui.App.Result {
    var content_color = dvui.themeGet().color(.window, .fill);

    if (runtime.state().host.appliesNativeWindowOpacity()) {
        content_color = if (!runtime.state().host.isMaximized())
            content_color.opacity(runtime.state().host.contentOpacity())
        else
            content_color;
    }

    const show_packed_atlas = if (comptime builtin.target.cpu.arch == .wasm32)
        runtime.packer().atlas != null
    else
        runtime.state().host.folder() != null and runtime.packer().atlas != null;

    const grouping: u64 = 0;
    var canvas_vbox = sdk.pane_layout.mainCanvasVbox(content_color, show_packed_atlas, grouping);
    defer {
        dvui.toastsShow(canvas_vbox.data().id, canvas_vbox.data().contentRectScale().r.toNatural());
        canvas_vbox.deinit();
    }

    if (show_packed_atlas) {
        const atlas = &runtime.packer().atlas.?;
        var image_widget = ImageWidget.init(@src(), .{
            .source = atlas.source,
            .canvas = &atlas.canvas,
            .grouping = grouping,
        }, .{
            .id_extra = @intCast(grouping),
            .expand = .both,
            .background = false,
            .color_fill = .transparent,
        });
        defer image_widget.deinit();

        image_widget.processEvents();

        if (dvui.dataGet(null, atlas.canvas.id, "sample_data_point", dvui.Point)) |data_pt| {
            if (atlas.canvas.samplePointerInViewport(dvui.currentWindow().mouse_pt)) {
                ImageWidget.drawSampleMagnifier(&atlas.canvas, atlas.source, data_pt);
            }
        }
    } else {
        var box = sdk.pane_layout.emptyStateCard(content_color, grouping);
        defer box.deinit();

        const alpha = dvui.alpha(1.0);
        dvui.alphaSet(1.0);
        defer dvui.alphaSet(alpha);

        const hint: []const u8 = if (comptime builtin.target.cpu.arch == .wasm32)
            "Pack open files to see the preview."
        else if (runtime.state().host.folder() == null)
            "Open a project folder, then pack to see the preview."
        else
            "Pack the project to see the preview.";

        dvui.labelNoFmt(
            @src(),
            hint,
            .{ .align_x = 0.5 },
            .{
                .gravity_x = 0.5,
                .gravity_y = 0.5,
                .color_text = .{ .color = dvui.themeGet().color(.control, .text) },
                .font = dvui.Font.theme(.body),
            },
        );
    }
    return .ok;
}

fn infobarEntries(state: *anyopaque, active_doc: ?DocHandle) []const sdk.infobar.Entry {
    const st: *State = @ptrCast(@alignCast(state));
    return infobar_status.infobarEntries(st, active_doc);
}

/// The active document, when it is one of ours: what fizzy's Undo and Redo act on.
fn activeOurs(state: *anyopaque) ?DocHandle {
    const st: *State = @ptrCast(@alignCast(state));
    const doc = st.host.activeDoc() orelse return null;
    return if (doc.owner == &plugin) doc else null;
}

fn undoEnabled(state: *anyopaque) bool {
    const st: *State = @ptrCast(@alignCast(state));
    return st.canUndo(activeOurs(state) orelse return false);
}

fn pluginUndo(state: *anyopaque) anyerror!void {
    const file = docFile(activeOurs(state) orelse return);
    try commands.refuseWhilePersonBusy(file);
    try file.history.undoRedo(file, .undo);
}

fn redoEnabled(state: *anyopaque) bool {
    const st: *State = @ptrCast(@alignCast(state));
    return st.canRedo(activeOurs(state) orelse return false);
}

fn pluginRedo(state: *anyopaque) anyerror!void {
    const file = docFile(activeOurs(state) orelse return);
    try commands.refuseWhilePersonBusy(file);
    try file.history.undoRedo(file, .redo);
}

/// Pixi owns its own runtime state + atlas packer (like any third-party plugin) instead of the
/// shell allocating them. They live as plugin-image statics, created in `register` and torn down
/// in `pluginDeinit`.
var plugin_state: State = undefined;
var packer_state: Packer = undefined;

pub fn register(host: *sdk.Host) !void {
    plugin_state = try State.init(sdk.allocator(), host);
    packer_state = try Packer.init(sdk.allocator());
    plugin_state.packer = &packer_state;
    runtime.adoptState(&plugin_state);
    plugin.state = @ptrCast(&plugin_state);
    try host.registerPlugin(&plugin);
    try host.subscribe(.{ .event = "fizzy.folder.closed", .owner = &plugin, .handler = folderClosed });
    try host.subscribe(.{ .event = "fizzy.folder.opened", .owner = &plugin, .handler = folderOpened });
    try host.subscribe(.{ .event = "workbench.pane.closed", .owner = &plugin, .handler = paneClosed });
    try host.registerFileRowFillColor(.{ .owner = &plugin, .color = &fileRowFillColor });
    try host.registerPainter(.{ .owner = &plugin, .draw = paint });
    try host.registerSurface(.{
        .id = view_tools,
        .owner = &plugin,
        .icon = .{ .tvg = dvui.entypo.pencil },
        .title = "Tools",
        .keywords = sdk.keywords.ide.sidebar,
        .draw = drawTools,
    });
    try host.registerSurface(.{
        .id = view_sprites,
        .owner = &plugin,
        .icon = .{ .tvg = dvui.entypo.grid },
        .title = "Sprites",
        .keywords = sdk.keywords.ide.sidebar,
        .draw = drawSprites,
    });
    try host.registerSurface(.{
        .id = view_project,
        .owner = &plugin,
        .icon = .{ .tvg = dvui.entypo.box },
        .title = "Project",
        .keywords = sdk.keywords.ide.sidebar,
        .draw = drawProject,
    });
    // Fills the main area while Project is the sidebar selection — the same
    // rule the store README uses, instead of a workbench-only `draw_workspace`.
    try host.registerSurface(.{
        .id = view_project_preview,
        .owner = &plugin,
        .title = "Project",
        .keywords = sdk.keywords.ide.main,
        .draw = drawProjectView,
        .takeover_when = view_project,
    });
    try host.registerSurface(.{
        .id = bottom_sprites,
        .owner = &plugin,
        .title = "Sprites",
        .keywords = sdk.keywords.ide.panel,
        .draw = drawSpritesPanel,
        .persistent = true,
    });
    try plugin_state.registerSettings(host, &plugin);

    // The guide before every other command, so an agent's index of commands opens on it.
    try commands.guide.register(host, &plugin);

    // Pixel-art's invocable, plugin-specific features. The shell/menus/keybinds trigger these
    // by id via `host.runCommand` without naming them. (Generic active-doc editing verbs like
    // `transform`/`copy`/`paste` are *not* commands — they are `Plugin.VTable` hooks the shell
    // dispatches to the focused document's owner.)
    try host.registerCommand(.{
        .id = "pixi.gridLayout",
        .owner = &plugin,
        .title = "Grid Layout…",
        .run = gridLayoutCommand,
        .isEnabled = editActionEnabled,
        .icon = icons.tvg.lucide.@"grid-3x3",
    });
    // Dispatched by the shell keymap (owner-scoped `mod+p`) — not by `tickKeybinds`, so it
    // no longer races Quick Open / the command palette on the same chord.
    try host.registerCommand(.{
        .id = "pixi.export",
        .owner = &plugin,
        .title = "Export…",
        .run = exportCommand,
        .isEnabled = exportEnabled,
    });
    try host.registerCommand(.{
        .id = "pixi.packProject",
        .owner = &plugin,
        .title = "Pack Project",
        .run = packProjectCommand,
        .isEnabled = packProjectEnabled,
    });

    // Editing verbs the shell's Edit menu / keybinds dispatch to per active-doc owner
    // (`<owner_id>.<action>`, i.e. `pixi.<action>` since `plugin.id == "pixi"`). These are
    // pixel-art's answers; another editor registers its own under its own id.
    try host.registerCommand(.{ .id = "pixi.copy", .owner = &plugin, .title = "Copy", .run = pluginCopy, .icon = icons.tvg.lucide.copy });
    try host.registerCommand(.{ .id = "pixi.paste", .owner = &plugin, .title = "Paste", .run = pluginPaste, .icon = icons.tvg.lucide.@"clipboard-paste" });
    try host.registerCommand(.{ .id = "pixi.transform", .owner = &plugin, .title = "Transform", .run = pluginTransform, .isEnabled = editActionEnabled, .icon = icons.tvg.lucide.move });
    try host.registerCommand(.{ .id = "pixi.acceptEdit", .owner = &plugin, .title = "Accept Edit", .run = pluginAcceptEdit });
    try host.registerCommand(.{ .id = "pixi.cancelEdit", .owner = &plugin, .title = "Cancel Edit", .run = pluginCancelEdit });
    try host.registerCommand(.{ .id = "pixi.deleteSelection", .owner = &plugin, .title = "Delete Selection", .run = pluginDeleteSelection });
    try host.registerCommand(.{ .id = "pixi.undo", .owner = &plugin, .title = "Undo", .run = pluginUndo, .isEnabled = undoEnabled, .icon = icons.tvg.lucide.undo });
    try host.registerCommand(.{ .id = "pixi.redo", .owner = &plugin, .title = "Redo", .run = pluginRedo, .isEnabled = redoEnabled, .icon = icons.tvg.lucide.redo });
    // New File's entry for a sprite. Internal: fizzy's New File… is the person's way in.
    try host.registerCommand(.{
        .id = "pixi.new",
        .owner = &plugin,
        .title = "Sprite",
        .visibility = .internal,
        .params = NewSprite.params,
        .runWith = NewSprite.bind(cmdNewSprite),
        .icon = icons.tvg.lucide.@"image-plus",
    });

    // Everything a person does in pixi, as commands with arguments (`src/commands.zig`).
    try commands.register(host, &plugin);

    // Transform / Grid Layout are pixel-art-only concepts — the shell's Edit menu has no
    // knowledge of them. Inject both directly into the shell's existing "Edit" menu (in-app +
    // native), only doing anything while the focused document is one of ours.
    try host.registerMenuSection(.{
        .id = "pixi.menu.edit_section",
        .parent_menu_id = "fizzy.menu.edit",
        .owner = &plugin,
        .draw = drawEditMenuSection,
    });
    // Naming the command on each native item is what puts its chord on the macOS menu, and keeps
    // it there across a rebind; `run` is still the click path.
    try host.registerNativeMenuItem(.{
        .id = "pixi.native.transform",
        .owner = &plugin,
        .parent_menu_id = "fizzy.menu.edit",
        .title = "Transform",
        .command = "pixi.transform",
        .sf_symbol = "arrow.up.left.and.down.right.magnifyingglass",
        .run = nativeTransform,
    });
    try host.registerNativeMenuItem(.{
        .id = "pixi.native.gridLayout",
        .owner = &plugin,
        .parent_menu_id = "fizzy.menu.edit",
        .title = "Grid Layout…",
        .command = "pixi.gridLayout",
        .sf_symbol = "square.grid.3x3",
        .run = nativeGridLayout,
    });
}

/// Whether the shell's active document belongs to this plugin — Transform/Grid Layout only
/// mean anything for a pixi document, so both entry points below no-op otherwise.
fn activeDocIsOurs() bool {
    const doc = runtime.state().host.activeDoc() orelse return false;
    return doc.owner == &plugin;
}

/// `Command.isEnabled` for `pixi.transform`/`pixi.gridLayout`. Naming this on the command (rather
/// than each call site re-deriving it) is what lets both the in-app dvui menu row
/// (`Host.drawMenuItem`, via `Host.commandEnabled`) and the native macOS row
/// (`FizzyNativeMenuGenericActionEnabled`, via the same lookup) grey themselves out for a
/// non-pixi document without either side special-casing pixi.
fn editActionEnabled(_: *anyopaque) bool {
    return activeDocIsOurs();
}

/// In-app "Edit" menu section (see `Host.registerMenuSection`). Always drawn — greying for a
/// non-pixi document comes from `editActionEnabled` above via `Host.drawMenuItem`, not from an
/// early return here. An early return used to make both rows disappear entirely from this menu
/// while the *native* macOS one (a static bar with no per-row enabled hook of its own) kept
/// showing them regardless, so the two disagreed on every non-pixi document.
///
/// Both rows go through `Host.drawMenuItem`, naming the command each one runs: the shell draws
/// that command's current chord as the accelerator, so rebinding Transform / Grid Layout in the
/// Keyboard Shortcuts pane updates the menu. The hand-rolled row this replaced looked the chord
/// up by dvui *bind name* (`"transform"`, `"grid_layout"`) — names these commands have no entry
/// under — so it always drew a blank accelerator, and it built dvui menu widgets inside the
/// plugin dylib, which `EditorAPI.VTable.drawMenuItem`'s doc comment spells out is unsafe.
fn drawEditMenuSection(_: ?*anyopaque) anyerror!void {
    if (runtime.state().host.drawMenuItem("Transform", "pixi.transform")) {
        runtime.state().host.runCommand("pixi.transform") catch |err| {
            dvui.log.err("Transform command failed: {s}", .{@errorName(err)});
        };
    }
    if (runtime.state().host.drawMenuItem("Grid Layout…", "pixi.gridLayout")) {
        runtime.state().host.runCommand("pixi.gridLayout") catch |err| {
            dvui.log.err("Grid layout command failed: {s}", .{@errorName(err)});
        };
    }
}

/// AppKit now greys these two rows for a non-pixi document too (`FizzyNativeMenuGenericActionEnabled`
/// reads `editActionEnabled` off the named command, same as the in-app menu), so this guard
/// shouldn't fire in the ordinary click path anymore — kept as a backstop against any other way
/// `run` could be reached (e.g. a future direct dispatch that skips menu validation).
fn nativeTransform(_: ?*anyopaque) anyerror!void {
    if (!activeDocIsOurs()) return;
    try runtime.state().host.runCommand("pixi.transform");
}

fn nativeGridLayout(_: ?*anyopaque) anyerror!void {
    if (!activeDocIsOurs()) return;
    try runtime.state().host.runCommand("pixi.gridLayout");
}

/// Stable `*Plugin` for constructing `DocHandle.owner` fields.
pub fn pluginPtr() *sdk.Plugin {
    return &plugin;
}

fn fileRowFillColor(_: ?*anyopaque, color_index: usize) ?dvui.Color {
    if (runtime.state().colors.palette) |*palette| {
        return palette.getDVUIColor(color_index);
    }
    return null;
}

fn drawTools(_: ?*anyopaque) anyerror!dvui.App.Result {
    try runtime.state().tools_pane.draw();
    return .ok;
}
fn drawSprites(_: ?*anyopaque) anyerror!dvui.App.Result {
    try runtime.state().sprites_pane.draw();
    return .ok;
}
fn drawProject(_: ?*anyopaque) anyerror!dvui.App.Result {
    try internal.explorer.project.draw();
    return .ok;
}
fn drawSpritesPanel(_: ?*anyopaque) anyerror!dvui.App.Result {
    try runtime.state().sprites_panel.draw();
    return .ok;
}

fn tickKeybinds(_: *anyopaque) anyerror!void {
    try keybind_ticks.tick();
}

/// Pixel-art's per-frame overlay: the radial tool menu (processes its hold-to-open input,
/// then draws while visible). Wired to the universal `Plugin.drawOverlay` phase.
fn drawOverlay(_: *anyopaque) anyerror!void {
    radial_menu.processHoldOpenInput();
    if (radial_menu.visible()) try radial_menu.draw();
}

fn pluginCopy(state: *anyopaque) anyerror!void {
    const st: *State = @ptrCast(@alignCast(state));
    try clipboard.copy(st);
}

fn pluginTransform(state: *anyopaque) anyerror!void {
    const st: *State = @ptrCast(@alignCast(state));
    try transform_op.begin(st);
}

fn registerOpenDocument(state: *anyopaque, file: *anyopaque) anyerror!*anyopaque {
    const st: *State = @ptrCast(@alignCast(state));
    const internal_file: *Internal.File = @ptrCast(@alignCast(file));
    const ptr = try st.registerOpenDocument(internal_file);
    return ptr;
}

fn documentPtr(state: *anyopaque, id: u64) ?*anyopaque {
    const st: *State = @ptrCast(@alignCast(state));
    return st.documentFromId(id);
}

fn documentByPath(state: *anyopaque, path: []const u8) ?*anyopaque {
    const st: *State = @ptrCast(@alignCast(state));
    return st.documentFromPath(path);
}

fn unregisterDocument(state: *anyopaque, id: u64) void {
    const st: *State = @ptrCast(@alignCast(state));
    st.unregisterDocument(id);
}

fn bindDocumentToPane(state: *anyopaque, doc: DocHandle, canvas_id: dvui.Id, workspace_handle: *anyopaque, center: bool) void {
    const st: *State = @ptrCast(@alignCast(state));
    st.bindDocumentToWorkspace(doc, canvas_id, workspace_handle, center);
}

fn documentGrouping(state: *anyopaque, doc: DocHandle) u64 {
    const st: *State = @ptrCast(@alignCast(state));
    return st.documentGrouping(doc);
}

fn setDocumentGrouping(state: *anyopaque, doc: DocHandle, grouping: u64) void {
    const st: *State = @ptrCast(@alignCast(state));
    st.setDocumentGrouping(doc, grouping);
}

/// `workbench.pane.closed`: the pane's canvas view goes with it.
fn paneClosed(state: *anyopaque, e: sdk.events.Event) void {
    const st: *State = @ptrCast(@alignCast(state));
    const pane = sdk.events.parse(struct { grouping: u64 }, st.host.arena(), e) catch return;
    State.removeCanvasPane(st, sdk.allocator(), pane.grouping);
}

fn documentPath(state: *anyopaque, doc: DocHandle) []const u8 {
    const st: *State = @ptrCast(@alignCast(state));
    return st.documentPath(doc);
}

fn setDocumentPath(state: *anyopaque, doc: DocHandle, path: []const u8) anyerror!void {
    const st: *State = @ptrCast(@alignCast(state));
    return st.setDocumentPath(doc, path);
}

fn documentHasNativeExtension(state: *anyopaque, doc: DocHandle) bool {
    const st: *State = @ptrCast(@alignCast(state));
    return st.documentHasNativeExtension(doc);
}

fn documentHasRecognizedSaveExtension(state: *anyopaque, doc: DocHandle) bool {
    const st: *State = @ptrCast(@alignCast(state));
    return st.documentHasRecognizedSaveExtension(doc);
}

/// A folder already open when pixi loads (a hot reload, an install) was opened before it
/// listened, so its project is read here. Not in `register`: in a dylib, `dvui.io` is not yet
/// the host's there, and reading the file through it crashed every hot reload with a folder open.
fn pluginInit(state: *anyopaque) anyerror!void {
    const st: *State = @ptrCast(@alignCast(state));
    if (st.project != null) return;
    if (st.host.folder()) |folder| st.reloadProjectForFolder(sdk.allocator(), folder);
}

fn pluginDeinit(state: *anyopaque) void {
    const st: *State = @ptrCast(@alignCast(state));
    const gpa = sdk.allocator();
    if (st.host.folder()) |folder| st.persistProject(folder); // the quit path
    if (st.packer) |p| p.deinit();
    st.deinit(gpa);
}

fn documentStackSize(state: *anyopaque) usize {
    const st: *State = @ptrCast(@alignCast(state));
    return st.sizeOfDocument();
}

fn documentStackAlign(state: *anyopaque) usize {
    const st: *State = @ptrCast(@alignCast(state));
    return st.alignOfDocument();
}

fn documentIdFromBuffer(state: *anyopaque, doc: *anyopaque) u64 {
    const st: *State = @ptrCast(@alignCast(state));
    return st.documentIdFromBuffer(doc);
}

fn deinitDocumentBuffer(state: *anyopaque, doc: *anyopaque) void {
    const st: *State = @ptrCast(@alignCast(state));
    st.deinitDocumentBuffer(doc);
}

fn setDocumentGroupingOnBuffer(state: *anyopaque, doc: *anyopaque, grouping: u64) void {
    const st: *State = @ptrCast(@alignCast(state));
    st.setDocumentGroupingOnBuffer(doc, grouping);
}

fn createDocument(state: *anyopaque, path: []const u8, grid: sdk.EditorAPI.NewDocGrid, out_doc: *anyopaque) anyerror!void {
    const st: *State = @ptrCast(@alignCast(state));
    return st.createDocument(path, grid, out_doc);
}

fn documentDefaultSaveAsFilename(state: *anyopaque, doc: DocHandle, allocator: std.mem.Allocator) anyerror![]const u8 {
    const st: *State = @ptrCast(@alignCast(state));
    return st.documentDefaultSaveAsFilename(doc, allocator);
}

const NewSprite = sdk.Command.Params(struct {
    parent_path: sdk.Command.Arg([]const u8, .{ .description = "The folder to create it in. Empty: an untitled document." }) = .init(""),
});
/// `pixi.new`, fizzy's New File entry for a sprite: pixi's own dialog asks for its size.
fn cmdNewSprite(_: *anyopaque, args: NewSprite.Args, _: *sdk.Command.Call) anyerror!void {
    NewFile.request(if (args.parent_path.len > 0) args.parent_path else null, 0);
}

/// Command body for `pixi.gridLayout` — opens the grid-layout dialog for the active doc.
fn gridLayoutCommand(_: *anyopaque) anyerror!void {
    const doc = runtime.state().host.activeDoc() orelse return;
    GridLayout.request(doc.id);
}

fn exportEnabled(_: *anyopaque) bool {
    return activeDocIsOurs();
}

fn exportCommand(_: *anyopaque) anyerror!void {
    if (!activeDocIsOurs()) return;
    var mutex = internal.core.dialogs.dialog(@src(), .{
        .displayFn = Export.dialog,
        .callafterFn = Export.callAfter,
        .title = "Export...",
        .ok_label = "Export",
        .cancel_label = "Cancel",
        .resizeable = false,
        .modal = false,
        .header_kind = .info,
        .default = .ok,
    });
    mutex.mutex.unlock(dvui.io);
}

fn beginFrame(state: *anyopaque) void {
    const st: *State = @ptrCast(@alignCast(state));
    // Advance the per-frame render clock used as a composite-cache invalidation key.
    internal.render.frame_index +%= 1;
    // Sweep any in-flight atlas-pack jobs. The shell no longer orchestrates packing — the
    // plugin drives its own background work from this universal per-frame phase.
    pack_project.tick(st);
    // Drawings being shown drawn, a little more each frame.
    const now = dvui.frameTimeNS();
    for (st.docs.files.values()) |*file| file.stepReveal(now);
    // Calls that waited for the person to let go: run now that they have.
    for (st.docs.files.values()) |*file| commands.runWaiting(file);
    if (comptime @import("builtin").target.cpu.arch == .wasm32) pack_project.runWasmWorkers(st);
}

/// Command body for `pixi.packProject`.
fn packProjectCommand(state: *anyopaque) anyerror!void {
    const st: *State = @ptrCast(@alignCast(state));
    try pack_project.start(st);
}

/// `pixi.packProject` is enabled only when no pack is already in flight.
fn packProjectEnabled(state: *anyopaque) bool {
    const st: *State = @ptrCast(@alignCast(state));
    return !pack_project.isActive(st);
}

fn tickActiveDocumentPlayback(state: *anyopaque, timer_host_id: dvui.Id) void {
    const st: *State = @ptrCast(@alignCast(state));
    st.tickActiveDocumentPlayback(timer_host_id);
}

fn resetDocumentPeekLayers(state: *anyopaque) void {
    const st: *State = @ptrCast(@alignCast(state));
    st.resetDocumentPeekLayers();
}

fn warmupActiveDocumentComposites(state: *anyopaque) void {
    const st: *State = @ptrCast(@alignCast(state));
    st.warmupActiveDocumentComposites();
}

fn isAnyDocumentActivelyDrawing(state: *anyopaque) bool {
    const st: *State = @ptrCast(@alignCast(state));
    return st.isAnyDocumentActivelyDrawing();
}

// Editing-verb command bodies (registered in `register`). `anyerror!void` to match `Command.run`.
fn pluginAcceptEdit(state: *anyopaque) anyerror!void {
    const st: *State = @ptrCast(@alignCast(state));
    st.acceptEdit();
}

fn pluginCancelEdit(state: *anyopaque) anyerror!void {
    const st: *State = @ptrCast(@alignCast(state));
    st.cancelEdit();
}

fn pluginDeleteSelection(state: *anyopaque) anyerror!void {
    const st: *State = @ptrCast(@alignCast(state));
    st.deleteSelection();
}

/// `fizzy.folder.closed`: save the project into the folder it came from (by now `host.folder()`
/// is the next one, or none).
fn folderClosed(state: *anyopaque, e: sdk.events.Event) void {
    const st: *State = @ptrCast(@alignCast(state));
    const folder = sdk.events.parse(sdk.events.Path, st.host.arena(), e) catch return;
    st.persistProject(folder.path);
    st.project = null;
}

/// `fizzy.folder.opened`: the new folder's project file.
fn folderOpened(state: *anyopaque, e: sdk.events.Event) void {
    const st: *State = @ptrCast(@alignCast(state));
    const folder = sdk.events.parse(sdk.events.Path, st.host.arena(), e) catch return;
    st.reloadProjectForFolder(sdk.allocator(), folder.path);
}

fn pluginPaste(state: *anyopaque) anyerror!void {
    const st: *State = @ptrCast(@alignCast(state));
    try clipboard.paste(st);
}

/// Pixel-art editing + tool keybinds.
/// binds in `Keybinds.register`; this fills in the pixel-art half. Platform: see
/// `Keybinds.register` for why `host.isMacOS()` (not `builtin`) is used.
fn contributeKeybinds(state: *anyopaque, win: *dvui.Window) anyerror!void {
    const st: *State = @ptrCast(@alignCast(state));
    if (st.host.isMacOS()) {
        try win.keybinds.putNoClobber(win.gpa, "undo", .{ .key = .z, .command = true, .shift = false });
        try win.keybinds.putNoClobber(win.gpa, "redo", .{ .key = .z, .command = true, .shift = true });
        try win.keybinds.putNoClobber(win.gpa, "sample", .{ .control = true });
        try win.keybinds.putNoClobber(win.gpa, "transform", .{ .command = true, .key = .t });
        try win.keybinds.putNoClobber(win.gpa, "grid_layout", .{ .command = true, .key = .g });
        // shift=false so this never matches Cmd+Shift+P (command palette). Dispatch of Export
        // itself goes through the shell keymap (`pixi.export`); this entry is only for menu hints.
        try win.keybinds.putNoClobber(win.gpa, "export", .{ .command = true, .key = .p, .shift = false });
        try win.keybinds.putNoClobber(win.gpa, "delete_selection_contents", .{ .key = .backspace });
    } else {
        try win.keybinds.putNoClobber(win.gpa, "undo", .{ .key = .z, .control = true, .shift = false });
        try win.keybinds.putNoClobber(win.gpa, "redo", .{ .key = .z, .control = true, .shift = true });
        try win.keybinds.putNoClobber(win.gpa, "sample", .{ .alt = true });
        try win.keybinds.putNoClobber(win.gpa, "transform", .{ .control = true, .key = .t });
        try win.keybinds.putNoClobber(win.gpa, "grid_layout", .{ .control = true, .key = .g });
        try win.keybinds.putNoClobber(win.gpa, "export", .{ .control = true, .key = .p, .shift = false });
        try win.keybinds.putNoClobber(win.gpa, "delete_selection_contents", .{ .key = .delete });
    }

    try win.keybinds.putNoClobber(win.gpa, "increase_stroke_size", .{ .key = .right_bracket });
    try win.keybinds.putNoClobber(win.gpa, "decrease_stroke_size", .{ .key = .left_bracket });
    try win.keybinds.putNoClobber(win.gpa, "quick_tools", .{ .key = .space });

    try win.keybinds.putNoClobber(win.gpa, "pencil", .{ .key = .d, .command = false, .control = false, .alt = false, .shift = false });
    try win.keybinds.putNoClobber(win.gpa, "eraser", .{ .key = .e, .command = false, .control = false, .alt = false, .shift = false });
    try win.keybinds.putNoClobber(win.gpa, "bucket", .{ .key = .b, .command = false, .control = false, .alt = false, .shift = false });
    try win.keybinds.putNoClobber(win.gpa, "selection", .{ .key = .s, .command = false, .control = false, .alt = false, .shift = false });
    try win.keybinds.putNoClobber(win.gpa, "pointer", .{ .key = .escape });
}