Grid Editor
Designgrid-editorGrid Editor is an Agent Skill for design published in the andymai/gridfinity-layout-tool repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
2D layout canvas — pointer interactions (draw/drag/resize/stagingDrag/paint in useInteraction.ts and src/shared/hooks/interactions/), __staging__ stash semantics, layer view modes, half-grid 0.5 snapping, collision/blocked zones, canPlaceBin validation. Load for symptoms like offset drag ghosts, mirrored Y placement, phantom collisions, bins drifting in the stash, laggy drag previews, or half-grid toggle failing.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/andymai/gridfinity-layout-tool/blob/HEAD/.claude/skills/grid-editor/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/grid-editor, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Grid Editor: 2D Canvas Interactions
When to use
- Changing any pointer interaction: draw, drag, resize, stagingDrag, paint.
- Touching placement validation, collision, blocked zones, or displacement-to-staging.
- Half-grid (0.5-unit) snapping, sizing, or toggle behavior.
- Bugs: offset/mirrored bin positions, phantom collisions, stash rendering glitches, laggy drags.
For CQRS commands/undo behind mutations see the state-and-cqrs skill; for compartment internals see bin-designer; for the 3D preview render systems see three-preview.
Mental model
- Orchestrator + mode hooks.
src/features/grid-editor/hooks/useInteraction.tsowns pointer events, pointer capture, and RAF throttling, then delegates to per-mode hooks insrc/shared/hooks/interactions/(shared so mobile/tablet shells reuse them). That directory's README is the ground truth for mode behavior — the grid-editor README undersells it. - Y is inverted once, in one place. Grid (0,0) is bottom-left; screen Y=0 is top.
useGridCoords.ts(getGridCoords/clampCoords) does the inversion (y = drawer.depth - cellY - 1). Never hand-roll px→grid math. dragstores a delta;stagingDragstores an absolute. In adragInteraction,currentCoordis the constrained delta fromstartCoord; commit isbin.x + delta. InstagingDragit is an absolute grid position (null until the pointer reaches the grid). See theInteractionunion insrc/core/types.ts(~line 301).- Staging is a sentinel, not a layer.
STAGING_ID = '__staging__'(src/core/constants.ts) never appears inlayout.layers. Every collision/validation loop must skip it:binsCollideResultreturns ok(false),getBlockedZonesandcanPlaceBinskip. Any new placement code that forgets this makes stashed bins phantom-block the grid. - Collision is 3D. Footprint overlap AND vertical overlap, where a bin's zEnd can protrude past its layer into layers above (blocked zones). Layer height is only a default for new bins;
canPlaceBin(src/shared/utils/validationPlacement.ts) checks height againstdrawer.height - layerZStart, never against layer height. - Half-grid changes rendering, not coordinates. Internal coords stay in real grid units at 0.5 steps (
snapToHalf). OnlyGrid.tsxdoubles:visualCellSize = (cellSize - gap) / HALF_BIN_SCALE,scale = HALF_BIN_SCALE. Never store scaled coordinates. - CLAUDE.md is stale about layer view modes.
layerViewMode('focus'|'stack'|'all') lives insrc/core/store/view.ts, NOTinteraction.ts; its only rendering consumer is the 3D preview (src/features/grid-editor/components/Grid/IsometricPreview/useBinsToRender.ts), and the value is also serialized into share links viasrc/shared/utils/ephemeralState.ts. The 2D canvas's lower-layer ghosting is separate:view.tsshowOtherLayers→ ghost bins inGridCanvas/GridCanvas.tsx.
Recipes
Add or change a placement validation reason
- Extend
ValidationReasoninsrc/core/types.ts; return it fromcanPlaceBininsrc/shared/utils/validationPlacement.ts(check order: bounds → layer → height → blocked_zone → collision). - Map it to a user message in
getPlacementErrorMessageinsrc/shared/utils/validation.ts; add keys per the i18n-changes skill. - Keep the
layerId === STAGING_IDskip andexcludeBinIds(group drags) working. - Update switches over the union —
src/features/grid-editor/components/Grid/Overlay/Overlay.tsx— orpnpm run check:exhaustivenessblocks the commit.
Change staging/displacement semantics
- Store side:
src/core/store/layout/drawerActions.ts(drawer shrink) andlayerActions.ts(layer delete) both setlayerId = STAGING_IDand preserve x/y. - Mirror the change in the CQRS replay handlers
src/core/cqrs/v2/domain/drawer/updateDrawer.tsandsrc/core/cqrs/v2/domain/layer/deleteLayer.ts— divergence silently corrupts undo/collab replay (see state-and-cqrs skill). - Stash visuals:
src/features/staging/components/Staging/Staging.tsx+src/features/staging/utils/packing.ts. Packed positions are recomputed per render — never persist them back to bins.
Modify half-grid behavior
- Snapping helpers:
snapToHalf/snapToGrid/isFractionalinsrc/core/constants.ts. Pointer conversion + clamping:useGridCoords.ts. Min draw size (0.5 : 1):src/shared/hooks/interactions/useDrawInteraction.ts. Smart-snap step:useDragInteraction.ts/useStagingDragInteraction.ts(step = halfGridMode ? 0.5 : 1). - Rendering is separate:
Grid.tsxvisual math andsrc/features/grid-editor/utils/fractionalPixels.ts. - If validity of existing layouts changes, update
validateHalfGridModeToggleinsrc/shared/utils/halfGridConstraints.ts(the toggle-off guard insrc/core/store/halfGridMode.ts).
Add a new interaction mode or drop target
- Study an existing mode hook in
src/shared/hooks/interactions/and its README; wire it intouseInteraction.tsfollowing the ref-of-handlers pattern (drawModeRefetc. synced inuseLayoutEffect). - Extend the
Interactionunion insrc/core/types.ts; runpnpm run check:exhaustiveness. - Drop targets are geometric, not DOM drop events:
Staging.tsxlistens to documentpointermove, compares client coords to its bounding rect, setsinteractionStore.dropTarget = 'staging';useDragInteraction.handleUpreadsdropTargetbefore grid placement. A new target needs both sides.
Verification
pnpm run test:run src/features/grid-editor
pnpm run test:run src/shared/hooks/interactions
pnpm run test:run src/core/store/layout.scenario.displacement
pnpm run test:run src/core/store/layout.scenario.half-grid
pnpm run check:exhaustiveness
pnpm run test:e2e
Interaction behavior specs live in src/features/grid-editor/hooks/useInteraction.{core,drag,draw,resize,staging}.test.ts; displacement semantics in src/core/store/layout.scenario.displacement.test.ts. Always test with a half-grid layout (x.5 coords) in addition to integer grids.
Traps
| Symptom | Cause | Fix |
|---|---|---|
| Bins mirrored vertically / drag ghost offset from cursor | Y inversion missed or applied twice | Route all conversion through useGridCoords getGridCoords/clampCoords |
| Group drop lands near (0,0) | Treated drag currentCoord as absolute | It is the delta; commit as bin.x + currentCoord.x (see useDragInteraction.handleUp) |
| "Collision"/"blocked zone" on an empty-looking layer | Lower-layer bin protrudes upward, or new code forgot the STAGING_ID skip | Inspect getBlockedZones output; skip bin.layerId === STAGING_ID in every bin loop |
| Drag preview lags / validation storms | Heavy work in the unthrottled draw/paint path | Keep expensive validation in the RAF-throttled branch of useInteraction (processHeavyMove); draw/paint stays cheap |
| Handlers act on stale state | Mode handlers captured directly in document listeners | Use the existing ref-sync pattern; read live state via useInteractionStore.getState() inside handlers |
| Commit logic never ran after a drag | pointercancel (OS gesture steal) discards without calling handleUp | Never assume handleUp runs; keep all commit logic in handleUp, nothing partial before it |
| Interaction stuck or cleared twice | Mode handleUp called setInteraction(null) on normal completion | Parent useInteraction clears it; only early-return branches (swap, staging drop) clear themselves |
| Staged bins drift above stash Y=0 | CSS repeat(N, …) drops non-integer N | Keep Staging.tsx gridHeight = Math.ceil(...) and StagingBin.tsx alignSelf: 'end' for fractional depth — git show 5517327ae |
| Half-grid toggle-off silently fails | toggleHalfGridMode returns Err while fractional bins exist | Check the Result; resize/delete fractional bins first. localStorage key gridfinity-half-bin-mode is legacy — never rename without a migration |
| Selection empties on layer switch | setActiveLayer clears selectedBinIds by design (src/core/store/selection.ts) | Not a bug; cross-layer selection is a product decision |
| Blocked zones stale mid-drag | getBlockedZones caches by reference equality of bins/layers arrays (src/shared/utils/collision.ts) | Never mutate layout arrays in place; Zustand+Immer must produce new references |
| Half-grid ON changes bin-designer defaults | Intentional: seeds base.halfSockets = true on new designs | See halfGridMode.ts docstring; bin-designer skill covers the designer side |
Other verified behaviors to respect: multi-select drag is all-or-nothing unless snapGroupDelta rescues it (Ctrl disables snap; ctrlKeyRef resets on window blur and visibilitychange because keyup never fires); getGridCoords uses cellX/cellY = -1 as the fractional-edge sentinel; mlTracking.trackMove/trackPlacement must fire before mutations (they need pre-mutation positions); moved bins keep their height across layers/staging by design; exploded 3D view forces layerViewMode='all' (view.ts coupling).