mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-10-19 13:36:48 +00:00
Maurice
431eb883c9
All eight guides of Trip > Places now have their pictures, taken from the real app, plus the hero of the screen, and the block is translated into the other 22 languages. Making the pictures showed three texts describing a UI that is not there, and they are corrected: the file import dialog has no Enrich places via Google switch (only the list import has one, and only with a Google key), a GPX import closes with a message while only KML and KMZ leave a summary behind, and both list providers are always offered. The search and the details column need no Google key either: they fill themselves from the TREK index, OpenStreetMap, Wikipedia, Wikivoyage and Wikimedia, and only ratings are Google's. The script needed the same honesty. ConfirmDialog and the two import dialogs are portals of their own with none of Modal's classes, so they get their own locators, and create-place now looks up a place whose entry actually carries a picture, opening hours and a description, instead of photographing an empty details column.
Help-center media
Every picture the help center shows is made here, by Playwright, against the real app. Nothing is drawn or cropped by hand, so a new screen gets pictures in exactly the same style by following the same path.
The style, in one place
Everything visual is fixed in guide.ts and promote.mjs; change it there, never
in a script.
| What | Where | Value |
|---|---|---|
| Viewport | guide.ts VIEWPORT |
1920 × 1080, device scale 2 (playwright.config.ts, project help-media) |
| Step picture frame | guide.ts frameFor |
16:10, at least 960 px wide, 64 px padding around the target, centred on it; a target taller than the frame is shown from its top |
| Ring around the target | guide.ts ring |
3 px in the app's --accent, 12 px radius, 6 px outside the element, the rest dimmed 30 %; a numbered badge (step number) at the top-left corner |
| Drag & drop | guide.ts ringDrag (a step with dropTo) |
source ringed and numbered, destination ringed dashed, a bowed arrow from the one to the other, both undimmed |
| Hover | captureGuide |
the target is hovered before the shot (tooltips, hover-only buttons show); hover overrides where the centre is wrong |
| Result picture | guide.media.result |
the full frame after the last step, pointer parked in the corner |
| Hero (screen overview) | captureHero |
the full frame of the screen as the reader finds it |
| Output | promote.mjs |
PNG → WebP quality 84; steps 1440 px wide, heroes and results 1920 px; into public/help-media/<guide-id>/step-<n>.webp, result.webp, ctx/<screen-id>.webp |
| No videos | stills only, by decision |
The app's own appearance is the default theme, English, light mode, the seeded
demo data (e2e/screenshots/seed.ts) plus the fixtures in fixtures.ts. Do not
change the theme, the language or the zoom for a picture.
How a screen gets its pictures
- Register the screen and its guides in
src/help/contexts/<screen>.tsandsrc/help/registry.ts; write the English texts as a block inshared/src/i18n/en/help.ts(// ── Screen: <id>). Guide ids are global: one id, one picture directory, so never reuse an id from another screen (registry.test.tsrefuses duplicates). - Write
e2e/help/<screen>.guide.ts: oneGuideScriptper guide, exactly oneStepActionper registered step,startthat opens the screen,cleanupthat puts the seed back. A step'stargetis the element the text tells the reader to use;preparegets there,actdoes what the text says. - Run
npm run help:media -- <screen>.guide.ts(own ports 5183/3011, fresh database, the seed, then the file). Fix until every guide passes; a failing step is a text that no longer matches the UI. - Look at the pictures in
e2e/.tmp/help-media/, thennode e2e/help/promote.mjs. - Translate the block into all 22 locales (
i18n:parity:strictis the gate) and runsrc/help/registry.test.ts, which checks every promised picture is on disk.
Rules learned the hard way
- Never edit
shared/while a media run is going: the watcher rebuildsdistmid-run and the pictures show raw i18n keys. - Never
npm run build --workspace=sharedwhilenpm run devis running; restart the dev server if it happened. - Each run boots a fresh server (~2 min); batch fixes, and dump the accessibility
tree once (
page.locator('body').ariaSnapshot()) instead of guessing locators. - A plugin installed by a run lives in
server/data/plugins/; the dev server imports it on its next restart. Guides that install one uninstall it incleanup. - The trip is running on the seed's dates: the plan opens on today's (empty) day;
openTripintrip-shared.tsselects day 1 and closes its details panel.