Tiling Reference

Complete reference for Lattices window tiling — positions, grids, execution paths, and voice interpretation.

Position System

Every tile position is a cell in a cols × rows grid, expressed as fractional (x, y, w, h) of the screen's visible area (excluding menu bar and dock).

Named Positions

All valid position strings that TilePosition accepts:

Custom Grid Syntax

For arbitrary grids: grid:CxR:C,R

• C = total columns, R = total rows
• C,R = target cell (0-indexed position)
• Example: grid:5x3:2,1 = center cell of a 5×3 grid

Parsed by PlacementSpec / parseGridString() into fractional (x, y, w, h).

Placement Contract

Placement strings are convenient at the boundary, but the daemon uses a typed placement model internally:

• named tile positions
• arbitrary grid cells
• raw fractional rectangles

That is what keeps CLI, daemon, voice, and hands-off execution aligned.

Drag Snap Zones

The menu bar app can also use placement specs as drag-to-snap targets. When you drag a window, Lattices shows faint landing zones plus a live preview of the resulting frame. Releasing over a zone tiles the dragged window to that placement. Hold Command while dragging to reveal snap mode, and release Command to drop back to a normal free drag without ending the gesture.

The recommended agent-owned config lives in ~/.lattices/snap-zones.json:

{
  "enabled": true,
  "modifier": "command",
  "zoneOpacity": 0.08,
  "highlightOpacity": 0.18,
  "previewOpacity": 0.14,
  "rules": [
    {
      "id": "left-edge",
      "label": "Left",
      "placement": "left",
      "trigger": { "x": 0.0, "y": 0.18, "w": 0.12, "h": 0.64 },
      "priority": 10
    },
    {
      "id": "notes-rail",
      "label": "Notes",
      "placement": { "x": 0.68, "y": 0.0, "w": 0.32, "h": 1.0 },
      "trigger": { "x": 0.88, "y": 0.18, "w": 0.12, "h": 0.64 },
      "priority": 30
    }
  ]
}

Notes:

• rules is the preferred list key. zones is still accepted for backward compatibility.
• modifier accepts command, option, control, or shift.
• placement can be a named placement/preset string or raw fractions.
• trigger uses normalized (x, y, w, h) fractions of the screen's visible area, with y = 0 at the top.
• priority breaks ties when trigger regions overlap.
• trigger can also be a named placement or preset string if you want the trigger region itself to reuse an existing tile definition.
• The older ~/.lattices/grid.json snapZones section still works, but ~/.lattices/snap-zones.json is the cleaner file for agents to edit.

Execution Paths

The old split-brain tiling logic has been collapsed toward a shared path. The canonical mutation is now:

{ "method": "window.place", "params": { "placement": "left" } }

All higher-level surfaces should compile into the same placement model:

• Daemon / CLI: window.place is the canonical mutation
• Compatibility: window.tile maps to window.place
• Voice / hands-off: parse natural language, then emit a placement spec
• HUD: still exposes a smaller shortcut set, but should target the same placement executor

The important change is that placement resolution now happens through PlacementSpec, not through separate ad hoc parsers per surface.

Frame Calculation

All paths eventually call one of:

1. WindowTiler.tileFrame(for:on:) — takes a TilePosition + NSScreen, returns a CGRect in AX coordinates (origin = top-left of primary display)
2. WindowTiler.tileFrame(fractions:inDisplay:) — takes raw (x, y, w, h) fractions + display rect

The math:

visible = screen.visibleFrame  (excludes menu bar + dock)
primaryH = primary screen height
axTop = primaryH - visible.maxY  (flip from AppKit bottom-left to AX top-left)

frame.x = visible.x + visible.width × fx
frame.y = axTop + visible.height × fy
frame.w = visible.width × fw
frame.h = visible.height × fh

Window Targeting

The tile_window intent resolves the target window in this priority:

1. session slot → LatticesApi.window.place / window.tile compatibility wrapper
2. wid slot → DesktopModel.shared.windows[wid] (direct window ID lookup)
3. app slot → first matching window by localizedCaseInsensitiveContains, excluding recently-tiled windows (prevents double-matching in batch commands like "Chrome left, Chrome right")
4. No target → tiles the frontmost window

HandsOff-specific targeting

The system prompt instructs the LLM to always use wid from the desktop snapshot, never app. This avoids ambiguity when multiple windows of the same app exist. In speech, the LLM says the app name; in the JSON action, it uses the wid.

Common Layouts (multi-action)

These are composed from multiple tile_window actions:

CLI shortcuts compile into the same distributor:

• lattices tile family → smart-grid the frontmost app's visible windows
• lattices distribute iTerm2 right → smart-grid visible iTerm windows inside the right half

HandsOff Smart Distribution

When the LLM sends multiple tile_window actions targeting the same position, HandsOffSession.distributeTileActions() subdivides:

• 2+ windows → "left" becomes top-left, left, bottom-left
• 2+ windows → "right" becomes top-right, right, bottom-right
• 2+ windows → "maximize" fans out to quadrants then halves

Guardrails

• Typed placement validation: invalid placement strings or objects are rejected at the daemon boundary.
• Recently-tiled dedup: IntentEngine.recentlyTiledWids prevents the same window from being matched twice within 2 seconds during batch operations.
• Compatibility wrappers: window.tile still works, but routes through the same placement machinery.

Current Gaps

1. Voice extraction still needs to catch up: the canonical executor understands horizontal thirds and edge quarters, but the local voice resolver still needs broader phrase coverage.
2. HUD coverage is narrower than the executor: keyboard tiling exposes a small subset of the full placement vocabulary.
3. Optimization and layer actions are still wrapper-level: space.optimize and layer.activate are now stable action IDs, but they currently wrap existing distributor and layer-switching behavior rather than a full planner.