Desktop Grid Model

Status

This document defines the responsive desktop grid direction for Prox OS. It does not implement a new desktop grid UI, route model, database schema, or drag/drop persistence.

Prox OS runs inside the browser. The desktop surface can be resized at any time by browser chrome, device rotation, embedded contexts, side panels, Alma, the Dock, or shell overlays. Desktop items and windows therefore cannot depend on absolute native-OS pixels as their source of truth.

Core Principles

Desktop items should use responsive grid coordinates, not fixed pixels.
Window geometry may use normalized coordinates plus min/max constraints.
Browser resize must clamp windows and desktop items into visible safe areas.
Top bar, Dock, sidebar, Alma, drawers, and panels must be treated as safe areas.
Small screens may enter single-window or maximized-first mode.
Advanced free placement should come after a stable grid and safe-area model.

Desktop Item Layout

Desktop items should be modeled as grid placements within a Space.

Conceptual shape:

type DesktopItemLayout = {
  spaceId: string
  itemId: string
  col: number
  row: number
  colSpan: number
  rowSpan: number
  order: number
}

The source of truth is the logical grid position, not the last rendered pixel position. Pixel positions are derived from the active desktop container size, safe areas, density, and item size rules.

Window Geometry

Window geometry can keep runtime pixels while the current shell is local-only, but persistent or cross-device state should move toward normalized geometry.

Conceptual shape:

type WindowGeometry = {
  xRatio: number
  yRatio: number
  widthRatio: number
  heightRatio: number
  minWidth: number
  minHeight: number
  maxWidth?: number
  maxHeight?: number
}

When restoring a window, the shell can derive pixel geometry from the current workspace bounds and then clamp it. App manifests can provide size hints, but the shell owns final geometry.

Safe Areas

Safe areas are shell-owned layout exclusions:

RuntimeCommandStrip / top bar.
Dock.
Alma or sidebar.
Utility trays.
Floating command surfaces.
System overlays.
Mobile browser viewport constraints.

Windows and desktop items should avoid ending up under persistent chrome. Transient overlays can appear above them, but resize and restore logic should still keep primary controls reachable.

Resize Strategy

When the desktop container width or height changes:

Recompute available columns and rows from the container, density, safe areas, and minimum item size.
Keep grid items in their logical order.
Clamp visible items into the available grid.
Move items outside the current visible grid into a future page, wrap region, or overflow folder.
Recompute window pixel geometry from normalized geometry when available.
Clamp every window into the visible safe area.
Prefer maximized-first or single-window mode on narrow screens.

Windows should never become unreachable after resize. At minimum, each restored window must keep a reachable titlebar and close/minimize/fullscreen controls.

Current Phase Constraints

The current shell can start with auto-arranged desktop items, folders, and window clamping. Full freeform desktop placement, persistent responsive grid editing, and cross-device layout sync should be separate implementation tasks.

Do not introduce a large desktop grid rewrite just to support one feature. New Space or desktop work should document whether it touches item layout, window geometry, safe areas, or persistence.

Relationship With Spaces

Desktop item layout belongs to a Space. A user switching Spaces should see a different desktop item set, widget set, and window layout memory. A future Space can also store a default window group preset; see Window Group Layout Presets.