# CTM iPad Web Preview

Status: implemented for local and staging checks
Date: 2026-05-19

## Goal

Use `/ipad.html` to run the CTM mobile app inside an iPad-sized frame from any CTM server. This is a fast desktop-browser check for the iPad layout before testing on a physical iPad.

The preview is intentionally same-origin by default:

```text
http://localhost:3456/ipad.html
  frames
http://localhost:3456/m/
```

When testing a staging/tunnel server, open that server's own preview page:

```text
https://<staging-host>/ipad.html
```

That keeps CTM cookies, device tokens, service worker scope, and API calls on the same origin as the mobile app.

## Run A Safe Local Staging Instance

Use `bin/dev.sh --refresh` with a separate port and data directory so iPad testing has copied CTM/Wall-E data without mutating the primary CTM state:

```bash
WALLE_DEV_DIR=/tmp/walle-dev-4456 \
DEV_CTM_PORT=4456 \
DEV_WALLE_PORT=4457 \
bash bin/dev.sh --refresh
```

Open:

```text
http://localhost:4456/ipad.html
```

The source field defaults to `/m/`. Keep it there for normal testing. If the preview loads but has no sessions, restart with `--refresh`; that copies the current CTM and Wall-E databases into the staging data directory.

## Preview Modes

`/ipad.html` includes four device presets:

- `Test Portrait`: `768 x 1024`, matching the automated tablet regression test.
- `Test Landscape`: `1024 x 768`, matching the automated split-workspace regression test.
- `11 Portrait`: `834 x 1194`, close to an 11-inch iPad CSS viewport.
- `11 Landscape`: `1194 x 834`, close to an 11-inch iPad landscape viewport.

Use `Reload` to reload only the framed mobile app. Use `Open` to launch the framed URL directly.

## What This Catches

- Tablet breakpoint regressions.
- Horizontal overflow.
- Portrait single-column sizing.
- Landscape list/detail split layout.
- Detail pane modal-vs-region behavior.
- Composer and bottom navigation placement.
- Search and session-card density at iPad widths.

## What Still Requires A Real iPad

The preview does not replace Safari-on-iPad validation. Always do one physical-device pass before shipping high-risk mobile changes because desktop browser framing does not fully emulate:

- iPad Safari viewport height changes when the software keyboard opens.
- PWA standalone mode.
- touch momentum scrolling and rubber-band edges.
- safe-area inset differences.
- iOS third-party cookie and passkey behavior.
- real camera/file-picker attachment flows.

## Automated Companion Test

The existing mobile render suite covers the same core tablet breakpoints:

```bash
npm --prefix claude-task-manager exec playwright test -- \
  --config tests/rendering/playwright.config.js \
  scenarios/mobile-pwa.spec.js \
  -g "iPad|tablet|iPad preview"
```

Use the automated test for regression gates and `/ipad.html` for quick visual inspection.
