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?
// 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().compactin the editor andusePhoneHeader()(fromPageHeader) everywhere else. Both readCOMPACT_QUERY. - In CSS, every phone rule uses exactly the same string:
@media (max-width: 767px), (pointer: coarse) and (max-height: 520px).components/ui/system.cssdoes this for every shared control. The build fails if a rule in the screenplay module goes back to a baremax-width: 767px; a rule that means upright phones only must sayorientationin its query.
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
<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-panelwhile 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 ofclamp(16px, 3.5vw, 40px). A module that needs more room setsdata-wideand getsmin(1600px, 100%). - Two panes: a module whose work is two panes (the stripboard and its tray) sets
data-fulland 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: 70chis 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,
@pagesized 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.
Rules
- Must use
COMPACT_QUERYfor 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