Mobile Shell Spec

This document defines the implementation rules for bringing the desktop-style shell to phones and smaller tablets without flattening it into a generic mobile website.

Goal

• Preserve the desktop metaphor.
• Adapt interaction for touch.
• Favor legibility, tap accuracy, and safe viewport behavior over literal desktop parity.
• Prevent windows, icons, and shell chrome from drifting into broken or unreachable states on small screens.

Breakpoints

Use shell behavior breakpoints instead of app-specific guesses.

• desktop: >= 1024px
  • current overlapping-window model remains primary
• tablet: 768px - 1023px
  • overlapping windows still allowed, but default sizes should become larger and safer
• mobile: <= 767px
  • single-primary-window behavior becomes the default mental model

If a device reports coarse pointer input, prefer touch rules even if the width is borderline.

Input Model

Tap

• Single tap on desktop icon:
  • focus icon
  • second tap or short follow-up tap opens app
• Single tap on a window:
  • focus that window
• Single tap on taskbar item:
  • restore or focus the window

Touch Drag Entry

• Window movement on touch must not begin immediately on pointer down.
• Title bars should require a press-and-hold of roughly 220ms - 320ms before drag mode begins.
• During hold detection:
  • suppress accidental text selection
  • do not move the window yet
  • show a subtle visual armed state on the title bar

Drag Mode

• Once armed, dragging from the title bar moves the window.
• Drag mode ends on pointer release, pointer cancel, or loss of capture.
• While dragging:
  • window position must be clamped to the visible viewport
  • top-edge drag should maximize the window
  • side-edge drag may snap on tablet, but should be disabled on narrow mobile widths unless it feels reliable

Resizing

• Corner resize handles should remain available for mouse and trackpad.
• On phones, freeform resize should be disabled by default.
• On tablets, resize can remain available if the handles are enlarged to a touch-safe target.
• On phones, maximize/restore is the primary resize model.

Window State Model

Desktop

• supported states:
  • normal
  • minimized
  • maximized
  • snapped

Tablet

• supported states:
  • normal
  • minimized
  • maximized
  • optional snap left/right

Mobile

• supported states:
  • focused
  • minimized
  • maximized
• mobile windows should open in a near-maximized state by default.
• overlapping many partial windows should not be the default presentation.

Window Sizing Rules

Desktop

• keep current sizing model

Tablet

• default width: min(viewportWidth - 32px, 880px)
• default height: min(viewportHeight - taskbarHeight - 24px, 760px)
• min width: 360px
• min height: 320px

Mobile

• default width: viewportWidth - 12px
• default height: viewportHeight - taskbarHeight - 12px
• max width: min(viewportWidth - 12px, 480px)
• max height: viewportHeight - taskbarHeight - 12px
• min width: 280px
• min height: 240px

On mobile, maximize should effectively become the default state, with a small exterior gutter preserved only if it improves readability and keeps the shell visible.

Window Chrome Rules

• Title bar height:
  • desktop: current height
  • tablet: current height or +2px
  • mobile: increase to at least 40px
• Window control hit targets must be at least 44px.
• Menu bars may collapse or become horizontally scrollable on mobile rather than wrapping into broken rows.
• Status bars may simplify on mobile, but should not disappear if they carry important context.

Desktop Icon Layout

Desktop

• keep neighborhood layout and saved positions

Tablet

• preserve neighborhood grouping
• reduce horizontal spread
• allow 2 to 3 icons per row inside a neighborhood depending on width

Mobile

• do not reuse desktop pixel coordinates
• use a dedicated mobile icon grid
• recommended grid:
  • 2 columns on narrow phones
  • 3 columns on larger phones
• icon card footprint:
  • width: 88px - 112px
  • min tap target: 44px
• labels:
  • max 2 lines
  • center aligned
  • allow truncation after line 2

If drag-to-rearrange is retained on mobile, it must be explicit:

• long press enters icon rearrange mode
• selected icon shows armed state
• drag handles or stronger visual framing appear
• normal tap-to-open remains the default outside rearrange mode

Persistence Rules

• Mobile icon positions should not reuse desktop saved coordinates.
• Recommended storage split:
  • os_icon_pos_desktop_v*
  • os_icon_pos_mobile_v*
• Window sizes and positions should also be mode-aware if current persisted desktop geometry produces invalid mobile restores.
• If a saved window position is off-screen for the current viewport, restore it to a safe centered or maximized mobile position.

Typography And Spacing

• Body text floor:
  • mobile: 14px
• Metadata floor:
  • mobile: 12px
• Title bar text:
  • mobile: 13px - 14px
• Control spacing should increase on touch breakpoints rather than shrinking to fit more UI.
• Dense app interiors should switch from multi-column to stacked layouts before text is reduced below readable sizes.

App-Level Behavior Rules

Reader

• open nearly maximized on mobile
• content column should become single-column
• side navigation should collapse into a top control or drawer

Record Library And Our Record Library

• open nearly maximized on mobile
• album list and detail panel should become a vertical stack
• track lists should use larger tap rows
• the selected track should remain visible while playing

Resume / About / Recipes / Wildlife

• window shell remains visible
• interiors stack vertically
• avoid preserving desktop side rails if they make content too narrow

Interaction States

Each touch-enabled shell element should have explicit states.

Window

• idle
• focused
• armed-for-drag
• dragging
• maximized
• minimized

Desktop Icon

• idle
• focused
• armed-for-open
• rearrange-armed
• dragging

Taskbar Item

• idle
• focused
• active-window
• minimized-window

Safety Rules

• No window should be draggable beyond a state where it cannot be recovered without resetting storage.
• No required control should fall under the mobile browser safe area or taskbar.
• The shell should respect 100dvh-style behavior where possible so browser chrome collapse does not trap content.
• Drag gestures should not block ordinary scrolling inside app content areas.

Implementation Order

1. Add viewport-mode detection and central shell breakpoints.
2. Make persisted window/icon state mode-aware.
3. Add touch drag arming on title bars.
4. Clamp mobile windows and default them to near-maximized sizing.
5. Replace inherited desktop icon coordinates with a dedicated mobile grid.
6. Tune window chrome hit targets and typography.
7. Then tune each app interior one by one.

Primary Files To Change First

• src/components/shell/Desktop.tsx
• src/components/shell/desktopNeighborhoods.ts
• src/components/shell/AppWindow.tsx
• src/components/windows/WindowManager.tsx
• src/components/shell/TaskBarXP.tsx
• app interiors such as:
  • src/apps/ReaderView/index.tsx
  • src/apps/MusicPlayer/index.tsx
  • src/apps/SharedRecordLibrary/index.tsx

Non-Negotiables

• Mobile must still feel like the same operating environment.
• Touch must feel intentional, not like desktop drag behavior awkwardly transplanted onto a phone.
• Windows and icons must always remain reachable and recoverable.
• Readability and tap safety outrank strict desktop mimicry on narrow screens.