Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -238,8 +238,16 @@ just screens <folder> <path>… # a whole-page picture of each path at every
just screens-same <before> <after> # names the pictures that differ, and fails if any do
just proto-new <issue>-<slug> <path>… # .dev/prototypes/<issue>-<slug>/: the real screens as static pages
just proto-serve <name> <port> # serve .dev/prototypes/<name>/ to the LAN, caching off
just ux-measure <folder> [--everyday] # the UX audit's counts and pictures of every screen, on throwaway instances
```

- **`just ux-measure` never measures the dev instance** (#629). Opening the
cooking screen starts a cooking and the share screen makes a Share Link, so
it copies the dev library into a throwaway instance on a spare port, starts a
second one empty for the empty screens and the pages a secret link opens, and
removes both. It counts the measures of
`docs/research/ux-reading-crowding-and-finding.md`, section 3, all but Depth,
which the walkthrough counts by hand. The table and pictures stay in `.dev/`.
- **The sizes are written once**, in `ui/tools/sizes.mjs`. A script that needs a
screen size imports it from there.
- **"Is the phone unchanged?" is two sets of pictures.** Run `just screens` into
Expand Down
15 changes: 15 additions & 0 deletions justfile
Original file line number Diff line number Diff line change
Expand Up @@ -320,6 +320,21 @@ proto-new name +$paths:
proto-serve folder port:
@node ui/tools/proto-serve.mjs "{{folder}}" "{{port}}"

# Count what each screen holds at the UX audit's sizes and in every Language,
# photograph it in English and French, and write measures.csv, details.json and
# pictures/ into <folder> (#629). It never touches the dev instance: it copies
# the dev library into a throwaway instance of the debug binary, starts a second
# one empty, measures both on 127.0.0.1 and removes them. Like `just test`, it
# builds ui/build first, which leaves a running vite answering 500 until the
# next `just dev-start`. --everyday measures the everyday screens alone.
ux-measure folder *flags:
#!/usr/bin/env bash
set -euo pipefail
just _npm-deps
cargo build
just ui-build
node ui/tools/ux-measure.mjs --binary "{{binary}}" "{{folder}}" {{flags}}

# ── Cutting a release ─────────────────────────────────────────────────────────

# A release is cut by these two commands and nothing else (ADR 0047). The
Expand Down
42 changes: 27 additions & 15 deletions ui/tools/dev-session.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,29 @@ export function secretFrom(setCookies) {
return null;
}

/**
* Sign in at one of an instance's `/auth/*` doors, and give back the Secret
* of the Session it made. `just ux-measure` signs in to its throwaway
* instances here too (#629).
* @param {string} url the door, as in `https://…/auth/login`
* @param {Record<string, string>} body
*/
export async function signInAt(url, body) {
const response = await reach(url, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(body),
});
const secret = secretFrom(response.headers.getSetCookie());
if (!response.ok || !secret) {
const answer = await response.json().catch(() => null);
throw new ToolError(
`${new URL(url).origin} refused the sign-in: ${answer?.error?.message ?? response.status}`,
);
}
return secret;
}

/** @param {string} label */
async function start(label) {
const file = sessionFile(label);
Expand All @@ -53,22 +76,11 @@ async function start(label) {
return;
}

const response = await reach(`${origin}/auth/login`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
name: need(env, 'KAMOSU_DEV_ADMIN_NAME'),
password: need(env, 'KAMOSU_DEV_ADMIN_PASSWORD'),
session_name: label,
}),
const secret = await signInAt(`${origin}/auth/login`, {
name: need(env, 'KAMOSU_DEV_ADMIN_NAME'),
password: need(env, 'KAMOSU_DEV_ADMIN_PASSWORD'),
session_name: label,
});
const secret = secretFrom(response.headers.getSetCookie());
if (!response.ok || !secret) {
const answer = await response.json().catch(() => null);
throw new ToolError(
`the dev instance refused the sign-in: ${answer?.error?.message ?? response.status}`,
);
}
fs.mkdirSync(SESSIONS_DIR, { recursive: true });
fs.writeFileSync(file, `${secret}\n`, { mode: 0o600 });
fs.chmodSync(file, 0o600);
Expand Down
74 changes: 59 additions & 15 deletions ui/tools/dev.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,23 @@ export function devOrigin(env = devEnv()) {
return `https://${need(env, 'KAMOSU_DEV_HOST')}`;
}

/**
* The titles of the cards that belong to the browser a tool drives and not
* to the screen: "your library isn't on this phone yet" and its kin, in one
* Language. They are found by their titles, read from the message file so a
* reworded card is still found. `just proto-new` strips them from a capture,
* and `just ux-measure` hides them before it counts (#629).
* @param {string} [locale]
*/
export function browserCardTitles(locale = 'en') {
const messages = JSON.parse(
fs.readFileSync(path.join(ROOT, 'ui', 'messages', `${locale}.json`), 'utf8'),
);
return Object.entries(messages)
.filter(([key]) => /^offline_(\w+_)?title(_\w+)?$/.test(key))
.map(([, text]) => String(text));
}

/**
* The cookie file of the Session a label names.
* @param {string} label
Expand Down Expand Up @@ -280,24 +297,20 @@ export async function openBrowser({ webkit = false } = {}) {
* @param {string} secret
* @param {number[]} size
* @param {string} [locale]
* @param {{ touch?: boolean }} [options] a touch screen, as `toolContext` takes it
*/
export async function signedInContext(browser, origin, secret, [width, height], locale = 'en') {
const context = await browser.newContext({
viewport: { width, height },
serviceWorkers: 'block',
reducedMotion: 'reduce',
});
await context.addInitScript((chosen) => localStorage.setItem('PARAGLIDE_LOCALE', chosen), locale);
await holdWindowStill(context);
await holdCodeStill(context);
await leaveNoTrace(context);
export async function signedInContext(browser, origin, secret, size, locale = 'en', options = {}) {
const context = await toolContext(browser, size, locale, options);
await context.addCookies([
{
// `__Host-` takes a cookie for this host alone, with no Domain, so it
// is given by its address rather than by a domain and a path (#368).
// Chrome refuses a Secure cookie given for http://localhost, but
// sends one given for its https form there, since it holds localhost
// safe: so `just ux-measure` signs in to an instance on plain HTTP.
name: '__Host-kamosu_session',
value: secret,
url: `${new URL(origin).origin}/`,
url: `${new URL(origin).origin.replace(/^http:\/\/localhost\b/, 'https://localhost')}/`,
httpOnly: true,
secure: true,
sameSite: 'Lax',
Expand All @@ -306,6 +319,35 @@ export async function signedInContext(browser, origin, secret, [width, height],
return context;
}

/**
* A browser context of one size as every tool opens one, signed in to
* nothing: its interface in `locale`, the service worker kept out, and what
* the tools do held off the screen (`holdWindowStill`, `holdCodeStill`,
* `leaveNoTrace`). `just ux-measure` opens the pages a secret link leads to
* in one, as the stranger holding the link does (#629).
*
* With `touch`, the window is a touch screen with no mouse, as a phone or an
* iPad is, so a screen draws what it draws there: the `(hover: hover)` gate
* hides what only a pointer sees (#223).
* @param {import('playwright').Browser} browser
* @param {number[]} size
* @param {string} [locale]
* @param {{ touch?: boolean }} [options]
*/
export async function toolContext(browser, [width, height], locale = 'en', { touch = false } = {}) {
const context = await browser.newContext({
viewport: { width, height },
...(touch ? { hasTouch: true, isMobile: true } : {}),
serviceWorkers: 'block',
reducedMotion: 'reduce',
});
await context.addInitScript((chosen) => localStorage.setItem('PARAGLIDE_LOCALE', chosen), locale);
await holdWindowStill(context);
await holdCodeStill(context);
await leaveNoTrace(context);
return context;
}

/**
* Chrome takes a full-page picture by shrinking the window to 1×1 and back
* (#529). Told of that, the app switched to the phone layout and back, built
Expand Down Expand Up @@ -458,10 +500,12 @@ const watching = new WeakSet();
* depending on which was quicker that time.
* @param {import('playwright').Page} page
* @param {string} url
* @param {{ limit?: number }} [options] how long to wait, in ms; a test waits less
* @param {{ limit?: number, quiet?: number }} [options] how long to wait, in ms, a test
* waiting less; and how long the screen must be still, `just ux-measure` asking for
* the research note's two seconds (#629)
* @returns {Promise<string | undefined>} what was still changing, or nothing once settled
*/
export async function openSettled(page, url, { limit = SETTLE_LIMIT_MS } = {}) {
export async function openSettled(page, url, { limit = SETTLE_LIMIT_MS, quiet = QUIET_MS } = {}) {
if (!watching.has(page)) {
watching.add(page);
// Before the page's own scripts, so the first change they make counts.
Expand Down Expand Up @@ -553,8 +597,8 @@ export async function openSettled(page, url, { limit = SETTLE_LIMIT_MS } = {}) {
const reasons = [
open.size > 0 &&
`waiting on ${[...new Set([...open].map((request) => request.url().slice(origin.length)))].join(', ')}`,
open.size === 0 && sinceRequest < QUIET_MS && 'a request just ended',
look.sinceChange < QUIET_MS && 'the page just changed',
open.size === 0 && sinceRequest < quiet && 'a request just ended',
look.sinceChange < quiet && 'the page just changed',
look.fonts !== 'loaded' && 'a font is loading',
!look.drawn && 'a picture is loading',
].filter(Boolean);
Expand Down
14 changes: 1 addition & 13 deletions ui/tools/proto-new.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ import {
ROOT,
ToolError,
atEverySize,
browserCardTitles,
openBrowser,
openSettled,
run,
Expand All @@ -33,19 +34,6 @@ import {
} from './dev.mjs';
import { SIZES } from './sizes.mjs';

/**
* The cards that belong to the browser doing the capture and not to the
* screen: "your library isn't on this phone yet" and its kin. They are found
* by their titles, read from the message file so a reworded card is still
* found.
*/
function browserCardTitles() {
const messages = JSON.parse(fs.readFileSync(path.join(ROOT, 'ui/messages/en.json'), 'utf8'));
return Object.entries(messages)
.filter(([key]) => /^offline_(\w+_)?title(_\w+)?$/.test(key))
.map(([, text]) => String(text));
}

/**
* The file a photograph is kept in: its address, made safe for a file name.
* @param {string} src
Expand Down
2 changes: 1 addition & 1 deletion ui/tools/screens.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ function measure(page) {
* @param {string} size
* @returns {Promise<{ files: string[], height: number }>}
*/
async function photograph(page, out, route, size) {
export async function photograph(page, out, route, size) {
const { width, height, ratio } = await measure(page);
// A clip is given in CSS pixels, the limit in the screen's.
const limit = Math.floor(PICTURE_LIMIT / ratio);
Expand Down
17 changes: 17 additions & 0 deletions ui/tools/sizes.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,20 @@ export const SIZES = {
* width of many Android phones, where the tab bar has the least room (#600).
*/
export const NARROWEST_PHONE = [360, 760];

/**
* The sizes that stand for a screen with a mouse rather than a finger. Every
* other one is a phone or a tablet, which `just ux-measure` opens as a touch
* screen (#629). An iPad is wide and touch (#223).
*/
export const MOUSE_SIZES = ['macbook', 'monitor'];

/**
* The two phones the UX audit judges comfort at (#627, decision 3), named by
* their widths: an iPhone 17 and a Pixel 10. A list of their own, so `just
* screens` keeps photographing the nine above.
*/
export const AUDIT_PHONES = {
'phone-402': [402, 874],
'phone-412': [412, 924],
};
Loading
Loading