# Layout

> Where things go on a phone, a sideways phone, a tablet, a desk and a television, decided by one shared compact query, with the screenplay page at the centre of every one.

Source: https://kwark.space/designSystem/foundations/layout

## One question, asked the same way everywhere

Kwark used to ask "how wide is the window?" and got the wrong answer twice. A phone turned on its side is about 900px wide and 400px tall; it was handed the desktop, with a menu bar, the scene list and a shortcut strip over 200 pixels of page. So the question became: is this a phone, in either hand?

```js
// pages/Understanding/EditorModule/hooks/useEditorLayout.ts
export const COMPACT_QUERY = '(max-width: 767px), (pointer: coarse) and (max-height: 520px)';
```

**Compact** is a narrow screen, or a touch screen too short for desktop chrome. It is the one definition of "phone" in Kwark:

- In React, `useEditorLayout().compact` in the editor and `usePhoneHeader()` (from `PageHeader`) everywhere else. Both read `COMPACT_QUERY`.
- In CSS, every phone rule uses exactly the same string: `@media (max-width: 767px), (pointer: coarse) and (max-height: 520px)`. `components/ui/system.css` does this for every shared control. The build fails if a rule in the screenplay module goes back to a bare `max-width: 767px`; a rule that means upright phones only must say `orientation` in its query.

> **For agents:** For phone layout, use `COMPACT_QUERY` (`useEditorLayout()` or `usePhoneHeader()` in React, the identical media query string in CSS). Never use `useBreakpoint().isMobile` or a bare `max-width: 767px` for new phone rules: they miss phones held sideways.

## The ranges

| Range | How it is detected | What changes |
|---|---|---|
| Compact: upright phones up to 767px, and any touch screen 520px tall or less | `COMPACT_QUERY` | One 44px header line, the floating dial, menus as bottom sheets, 44px targets, no breadcrumb, no rail. In the editor: one column, drawers, the writing keys docked, the timeline as a 22px strip |
| Narrow: up to 1023px | `OVERLAY_NAV_QUERY`, `(max-width: 1023px)` | The scene list comes over the page as a drawer with its own open state, and goes away once a scene is chosen |
| Middle: 1024–1279px | Width | Panels sit over the page inside the editor's workspace (`position: absolute`), and the page keeps a minimum of 460px |
| Wide: 1280px and up | Width | Scene list, page, panel and the tool rail side by side; the page keeps at least 560px; the dial steps left of the rail |
| Very large: 2400 × 1300 and up | Width and height | The page opens at Fit page instead of 100% |
| Any touch | `ANY_TOUCH_QUERY`, `(any-pointer: coarse)` | An iPad with a trackpad or a touch laptop keeps the desk layout but gains touch affordances |

`hooks/useBreakpoint.ts` still reports `xs` below 640, `sm` to 767, `md` (tablet) to 1023, `lg` to 1279 and `xl` above; older screens and `Modal` use its `isMobile`. It is width only, so it is right for an upright phone and wrong for a sideways one.

### Tablets

A tablet upright (768–1023px) is not a phone: it gets the desktop header and menus, the scene list as an overlay drawer, and the page at full width. A tablet on its side (1024px and up) is a desk. Touch is detected separately, so a tablet's controls stay large enough for a finger where `(any-pointer: coarse)` is used.

## The screenplay at the centre

Every layout in the editor is built around one rule: the page is a page.

- **Width.** `min(816px, 100% − 32px)`: a US Letter page at 96 to the inch, or the room available minus a 16px gap either side, whichever is smaller. It never sits flush against the scene list or a panel.
- **Indents follow the page, not the window.** The page is a container (`container-name: script-page`). Below 580px of page width (a full text column is 587px), the indents keep the printed proportions of a full column (Decision 0041). Before that fix, a narrow-page rule fired on every page, and cues sat at 2.08 inches instead of 2.2.
- **On a phone** the page is the screen: no border, no corner, no shadow, 16px side padding, 20px at the head.

### Zoom: Fit width, Fit page, or a size

The writer chooses how large the page is drawn (`utils/pageZoom.ts`). The page count never changes with any of it, only what fits on the screen.

| Choice | What it does |
|---|---|
| A size | 60% to 200%, in steps of 10 |
| Fit width | The page as wide as the room, less 64px |
| Fit page | A whole page in the room's height (its two inch margins and its lines at 16px each), or its width if that is smaller |

Fits are held between 50% and 400% and rounded down to the nearest 5%. With nothing chosen yet, a screen of 2400 × 1300 or larger opens at Fit page, because a 4K monitor or a television drew the page at a fifth of the room's width. The choice is kept on the device, not in the script.

## The editor on a desk

```html
<div style="display:grid;grid-template-columns:clamp(120px,16%,180px) 1fr 200px 46px;grid-template-rows:36px 24px 1fr;height:340px;background:var(--k-bg);border:1px solid var(--k-line);border-radius:var(--k-radius-card);overflow:hidden;font:500 var(--k-fs-meta)/1.3 var(--k-font-ui);color:var(--k-text-2)">
  <div style="grid-column:1/-1;display:flex;align-items:center;gap:var(--k-space-4);padding:0 var(--k-space-3);background:var(--k-surface);border-bottom:1px solid var(--k-line);color:var(--k-text)">File<span>Edit</span><span>View</span><span>Tools</span><span>Help</span><span style="margin-left:auto;color:var(--k-text-2)">menu bar · z 100</span></div>
  <div style="grid-column:1/-1;display:flex;align-items:center;padding:0 var(--k-space-3);background:var(--k-surface);border-bottom:1px solid var(--k-line)">timeline · z 50</div>
  <div style="padding:var(--k-space-3);background:var(--k-surface);border-right:1px solid var(--k-line)">Scene list<br>clamp(180px, 16vw, 260px), resizable</div>
  <div style="display:flex;justify-content:center;padding:var(--k-space-4);overflow:hidden"><div style="width:min(100%,320px);padding:var(--k-space-4);background:var(--k-surface);border:1px solid var(--k-line);border-radius:4px;font:400 var(--k-fs-meta)/1.3 var(--k-font-screenplay);color:var(--k-text)">INT. EDIT SUITE – NIGHT<br><br>Mira scrubs back. Stops.<br><br><span style="padding-left:11ch">MIRA</span><br><span style="padding-left:5ch">Play it again.</span><br><br><span style="font:500 var(--k-fs-meta)/1.3 var(--k-font-ui);color:var(--k-text-2)">page · min(816px, 100% − 32px)</span></div></div>
  <div style="padding:var(--k-space-3);background:var(--k-surface);border-left:1px solid var(--k-line)">Panel<br>beside the page at 1280px and up; over it below</div>
  <div style="display:grid;align-content:start;justify-items:center;gap:var(--k-space-1);padding-top:var(--k-space-2);background:var(--k-surface);border-left:1px solid var(--k-line)"><span style="width:34px;height:34px;border-radius:var(--k-radius-control);background:var(--k-raise)"></span><span style="width:34px;height:34px;border-radius:var(--k-radius-control)"></span><span style="width:34px;height:34px;border-radius:var(--k-radius-control)"></span></div>
</div>
```

- **The menu bar** holds five menus: File, Edit, View, Tools, Help (Decision 0015). It is the only toolbar on a desk.
- **The tool rail** is 46px on the right edge with 34px buttons, shown at 1280px and up. It is the home for the editor's panels; below 1280px they move into the menus, and on a phone into the ⋯ menu.
- **The scene list** is `clamp(180px, 16vw, 260px)` and the writer can drag it wider. Below 1024px it becomes an overlay.
- **Panels** sit beside the page from 1280px; below that they sit over the page inside the workspace, below the menu bar, and the editor root carries `data-panel` while one is open.
- **The app's quick note and comments** do not float in the editor: they are rail buttons on a desk and ⋯ menu entries on a phone.

## The production office

Pre-production modules share one shell (`pages/PreProduction/shared/ProductionShell.tsx`, `ProductionOffice.css`):

- **Width:** `min(1280px, 100%)`, centred, with gutters of `clamp(16px, 3.5vw, 40px)`. A module that needs more room sets `data-wide` and gets `min(1600px, 100%)`.
- **Two panes:** a module whose work is two panes (the stripboard and its tray) sets `data-full` and takes the window exactly. The header is what it is, and everything left over belongs to the panes. No arithmetic against a guessed header height.
- **Beside the script:** Breakdown, Shots & Boards and Schedule can open as a panel beside the live screenplay. Nothing else in the office can, because nothing else has a page to sit beside. On a phone this choice is not offered.
- **Trail:** on a desk, the shared breadcrumb (`--k-crumb-*`, Decision 0044). On a phone, `PageHeader`.

## Drawers, dialogs and sheets

| Surface | On a desk | Compact |
|---|---|---|
| `Modal` sizes `sm`, `md`, `lg` | Centred, 384, 512 or 672px wide, up to 90% of the height | A bottom sheet, up to 85–90% of the height |
| `Modal` sizes `xl`, `full` | 896px, or 95% of the window | Full screen |
| `Drawer` | From the right edge, 420px, the full height | Full width |
| `Sheet` | Not used | From the foot, up to 560px wide and 88% of the height |
| Menus | Dropdowns, 224–296px wide | Bottom sheets that drill down one page at a time |

`Modal` still decides with `useBreakpoint().isMobile`, so a phone held sideways gets the centred desktop dialog. New dialogs on a phone use `Sheet` behind `COMPACT_QUERY`.

## Line lengths

- Interface prose: 60–75 characters (`max-width: 70ch` is the app's usual).
- The script: its format's measure, never the window's.
- Settings and forms: one column of fields up to about 480px; labels above fields, not beside them, so they survive a phone and a translation.

## Print layout

- The script prints on the paper chosen at export: US Letter or A4, `@page` sized to it.
- Production paper (the call sheet, the one-liner) is drawn on screen at up to 900px wide (`.po-paper`) and prints at its own paper size; on a phone it runs to the screen's edges.
- Chrome never prints: the dial, the beat ribbon and editor markers are hidden under `@media print`. See [Print and export](https://kwark.space/designSystem/patterns/print-and-export.md).

## Rules

- **Must** use `COMPACT_QUERY` for phone layout, in React and in CSS.
- **Must** keep the page at `min(816px, 100% − 32px)` and let the indents follow the page's container, never the window.
- **Never** change desktop layout as part of a phone fix. Phone rules live inside the compact query.
- **Always** check a layout at 375 × 812, 320 × 568, a sideways phone (about 844 × 390, touch), 1024, 1280 and 1440.
- **Never** let zoom change the page count.

## AI readiness test

**Task:** Add a "Notes" panel to the screenplay editor that a writer opens from the tool rail.

**Give the agent:** This page, Elevation (layers), Spacing, useEditorLayout.ts.

**Constraint:** It must work on a 1440 desk, a 1100 laptop, an upright phone and a sideways phone, without changing how the page is measured.

**A reliable answer:**
- At 1280px and up it sits beside the page and the page keeps at least 560px
- From 1024 to 1279 it sits over the page inside the workspace, below the menu bar
- In compact it opens as a sheet from the ⋯ menu, not from a rail
- Phone detection uses COMPACT_QUERY or useEditorLayout().compact, not isMobile
- The page width and indents are untouched
