08_edit_mode.md

summary	Current Edit Mode behavior, user workflow, public APIs, limits, and verification for ActionRail's layout-map authoring shell.
read_when	Using or documenting ActionRail Edit Mode. Extending Phase 2 layout editing or direct manipulation. Checking which Edit Mode features are implemented versus planned.

Edit Mode

Edit Mode is ActionRail's global authoring state for inspecting and adjusting viewport rail layouts. Normal Mode executes rail actions and owns slot payload editing through rail lock/unlock controls; Edit Mode draws an edit-only layout map over the active Maya viewport so whole rails can be selected and positioned without triggering their buttons.

The Edit Mode shell and Phase 2 step 2.5 layout persistence/direct manipulation surface are implemented and Maya-smoke verified. Phase 2 step 2.6 has started: the first collapse path is Maya-smoke verified, collapsed-handle edge placement and hit targets are improved, and Sticky Frames now draws axis-aligned alignment guides. The old right-click frame options popover and Edit Mode slot payload editor have been removed so Edit Mode stays focused on rail layout only.

What It Shows

When Edit Mode is enabled, ActionRail draws:

• a viewport-sized layout-map overlay owned by Maya's main window
• an optional placement grid
• one dark labeled frame for each active runtime rail
• selected-frame styling
• selected-frame guide lines and axis-aligned Sticky Frames alignment guides
• rail source layer labels plus icon-only lock state controls in each frame's top-right corner
• a draggable compact Edit Mode panel with Grid, Grid Size, Snap to Grid, Sticky Frames, and an icon-only selected-frame lock control
• a selected-rail position popover with arrow nudges, numeric X/Y controls, and Reset

The frame view represents rail footprints and hit boxes. It is deliberately not the Normal Mode button rendering.

Maya Workflow

Install the ActionRail Maya menu, show one or more rails, then toggle Edit Mode:

import actionrail

actionrail.install_menu_toggle()
actionrail.show_preset("transform_stack")
actionrail.toggle_edit_mode()

The Maya menu exposes Toggle Edit Mode after install_menu_toggle() is run.

Quick Create can hand off directly into placement. Use its Edit Layout button, or call actionrail.edit_quick_create_layout(draft), to preview the current draft, enter Edit Mode, and select that draft frame.

Inside Edit Mode:

• left-click and drag an unlocked rail frame to move it directly
• edit the X/Y fields or use the arrow controls to nudge an unlocked rail
• enable Grid to show or hide the edit-only grid
• adjust Grid Size to change the grid spacing
• enable Snap to Grid to snap authoring movement to the grid
• enable Sticky Frames to align moved rails to nearby rail edges
• drag the Edit Mode panel out of the way when it covers the rail you want to move
• click the frame's top-right lock icon, or the lock icon in the Edit Mode panel, to toggle whether the selected rail can be moved in the current Edit Mode session
• use save_edit_mode_layout() to persist an unlocked runtime/user rail as a user preset or an unlocked built-in/studio rail as a user override

Outside Edit Mode, use Normal Mode rail slot editing when the goal is to add or remove, move, or swap an action payload from a slot. The public helpers are:

import actionrail

actionrail.unlock_rail_slots("my_user_rail")
actionrail.lock_rail_slots("my_user_rail")

In Normal Mode, the rendered slot context menu can unlock the active rail. Once unlocked, that same menu can assign an action payload or clear the slot. Shift-drag a populated slot to another slot on the same unlocked rail, or onto another unlocked rail, to move its payload; dropping on a populated unlocked target swaps the two payloads. Releasing outside ActionRail clears the source slot, while releasing over a locked different rail cancels the drag so the source payload is preserved. While a rail is unlocked, populated slot clicks are treated as edit gestures instead of running actions. Lock the rail again when the bar should return to normal action execution.

Movement updates active rail overlay positions immediately. Saved persistence is implemented for unlocked runtime/user rails by writing the current runtime spec to the user preset store. Unlocked built-in and studio rail saves write a separate *_user_override user preset; loading the original read-only preset id applies that sidecar override without mutating bundled or studio JSON. Locked built-in and studio presets remain read-only.

Public API

Top-level helpers:

import actionrail

state = actionrail.enter_edit_mode()
state = actionrail.toggle_edit_mode()
state = actionrail.exit_edit_mode()
state = actionrail.edit_mode_state()
state = actionrail.set_edit_mode_options(
    show_grid=True,
    snap_to_grid=True,
    sticky_frames=True,
    grid_size=32,
)
state = actionrail.select_edit_mode_rail("my_user_rail")
path = actionrail.save_edit_mode_layout("my_user_rail")

State objects:

• EditModeSettings: show_grid, snap_to_grid, sticky_frames, grid_size
• EditModeState: enabled, selected_preset_id, settings, rail_count
• RailFrameInfo: viewport-local frame geometry, layout metadata, lock state, collapse state, and source layer

Implementation ownership:

• scripts/actionrail/edit_mode.py: state model, layout-map overlay, grid, frame selection, rail nudging, and layout saves
• scripts/actionrail/overlay.py: Normal Mode rail slot-edit lock state and runtime payload assignment/clear/move hooks
• scripts/actionrail/slot_payloads.py: stable slot payload assignment, clear, move, swap, and cross-rail transfer helpers
• scripts/actionrail/widgets.py: rendered rail buttons, Normal Mode slot edit context menus, and Shift-drag slot payload gestures
• scripts/actionrail/maya_ui.py: Maya menu entry point
• tests/test_edit_mode.py: pure Python API/model coverage
• tests/maya_smoke/actionrail_edit_mode_smoke.py: Maya layout-map, selection, movement, sticky-frame, collapse, save, and screenshot smoke

Current Limits

Implemented now:

• global enter/exit/toggle state
• active-rail frame discovery
• grid visibility and grid-size controls
• left-click frame selection
• selected-frame X/Y popover
• draggable Edit Mode control panel
• selected-frame icon-only lock/unlock controls in the frame corner and panel
• X/Y movement for unlocked rails
• direct frame dragging
• snap-to-grid and Sticky Frames during movement
• selected-frame snap/spacing guide rendering with axis-aligned Sticky Frames alignment hints
• edge-tab collapse/expand runtime support backed by persisted collapse settings and larger edge-clamped collapsed handles
• Save Position for unlocked runtime/user rails
• Save Position user-overrides for unlocked built-in and studio rails
• public layout-save helper that persists adjusted offsets to user presets
• Normal Mode active-rail lock/unlock helpers for slot payload assignment and clearing
• Normal Mode Shift-drag slot payload move/swap/clear-out gestures, including cross-rail transfer between unlocked rails
• Maya menu toggle
• Maya screenshot verification

Not implemented yet:

• Bind Mode, flyouts, command rings, profile layers, marking-menu export, and Viewport 2.0 drawing

Do not modify locked built-in or studio presets directly when adding persistence. Save layout changes as user presets or user overrides.

Verification

Focused smoke:

.\scripts\maya-smoke.ps1 -Script actionrail_edit_mode_smoke.py

Full Maya-facing baseline:

.\scripts\maya-smoke.ps1 -Script all

The verified overview screenshot used by the README is stored at docs/assets/actionrail_readme_edit_mode.png.