docs(decisions): accept 0051–0057, supersede 0038 with 0057
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
e945e646fc
commit
7a6cd93b41
|
|
@ -1,6 +1,6 @@
|
|||
# 0038 Back follows the page's declared parent, never the browser alone
|
||||
|
||||
Status: Proposed · Area: architecture · Date: 2026-10-09 · Decided by: agent
|
||||
Status: Superseded by 0057 · Area: architecture · Date: 2026-10-09 · Decided by: agent
|
||||
|
||||
## Context
|
||||
The new design's R14 rule: every page opened from another page has back on mobile and desktop, because an installed PWA has no browser bar. Roots (خانه, جستجو, the dashboards, a creator's own channel) have none. `history.back()` alone fails on a deep link or a notification tap.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,18 @@
|
|||
# 0051 Cache first for `/_next/static/`, stale-while-revalidate for fonts and the sprite
|
||||
|
||||
Status: Accepted · Area: architecture · Date: 2026-10-09 · Decided by: user
|
||||
|
||||
## Context
|
||||
Adopted from kasra-pay's decision 0032. The pwa lib's worker served all four stored kinds stale-while-revalidate, so every served chunk started a background fetch. Next.js names each `/_next/static/` file after its content, so that check can never find a change. Stale-while-revalidate exists to heal a file changed under its URL against the rules, which only fonts and the icon sprite can be.
|
||||
|
||||
## Decision
|
||||
- The worker serves `/_next/static/` JS and CSS cache first, with no network request on a hit, in both apps.
|
||||
- `writeServiceWorker`'s `strategy` applies to fonts and the sprite only; its default stays `'stale-while-revalidate'`.
|
||||
|
||||
## Alternatives
|
||||
- Stale-while-revalidate for everything (the skill's default): one wasted background fetch per served chunk, and a real download when the HTTP cache dropped the file.
|
||||
- Cache first for everything: a font changed under its old name would never heal.
|
||||
|
||||
## Consequences
|
||||
- Deviates from the skill's lib-pwa.md, which checks all four kinds.
|
||||
- `pwa-assets-v1` keeps its version: stored entries stay valid.
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
# 0052 The service worker evicts the least recently used entry first
|
||||
|
||||
Status: Accepted · Area: architecture · Date: 2026-10-09 · Decided by: user
|
||||
|
||||
## Context
|
||||
Adopted from kasra-pay's decision 0033. The worker evicted the oldest entry first and never rewrote an unchanged file, so after a few deploys it deleted the chunks every page uses before the dead chunks of older deploys. It also listed the whole cache after every put.
|
||||
|
||||
## Decision
|
||||
- The worker reads the cache's key order once per start and keeps it in memory: each put moves its entry to the end, and eviction takes from the front.
|
||||
- A hit in the older half of the cache is stored again, which moves it to the end.
|
||||
|
||||
## Alternatives
|
||||
- Oldest first (the skill's lib-pwa.md): the hottest files go first after a few deploys.
|
||||
- Access times in IndexedDB: a second store, and a write on every hit.
|
||||
- Store every hit again: a disk write per served file per page load.
|
||||
|
||||
## Consequences
|
||||
- A hot file is rewritten at most once per `maxEntries / 2` new entries; with no deploys, never.
|
||||
- Relies on `cache.put` moving an entry to the end of `keys()`, as the Cache API spec says.
|
||||
- Only activation creates the cache, so a worker that outlives its registration (the kill switch in another tab) stores nothing.
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
# 0053 Both apps share one service worker, one cache, and one manifest
|
||||
|
||||
Status: Accepted · Area: architecture · Date: 2026-10-09 · Decided by: user
|
||||
|
||||
## Context
|
||||
Adopted from kasra-pay's decision 0034. Decision 0001 serves bull and bear on one domain, routed by user agent, while the skill's lib-pwa.md assumes each app has its own origin. So one `/sw.js` registration at scope `/`, one `pwa-assets-v1` cache, and one `/manifest.webmanifest` serve both apps, and a device whose user agent switches (an iPad, a desktop-site toggle) gets whichever app nginx picks.
|
||||
|
||||
## Decision
|
||||
- Both apps write the worker with the same `writeServiceWorker` options, set `NEXT_PUBLIC_SERVICE_WORKER_ENABLED` to the same value, and ship in one deploy.
|
||||
- The manifest's fields and `buildManifest` live in `platforms/market/src/app/manifest`, so both apps serve the same manifest.
|
||||
|
||||
## Alternatives
|
||||
- A worker or cache per app: impossible on one origin, where both apps serve the same paths and the worker can't tell which app a request is for.
|
||||
- One origin per app: contradicts 0001.
|
||||
|
||||
## Consequences
|
||||
- A flag that differs between the apps registers and unregisters the worker in turn on a device that switches apps. Nothing checks the two `.env` files agree yet; that check is debt.
|
||||
- `maxEntries` (200) holds about one deploy of both apps; with 0052, a device that uses one app keeps all of that app's files.
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
# 0054 Render the metadata in `<head>` for every visitor
|
||||
|
||||
Status: Accepted · Area: architecture · Date: 2026-10-09 · Decided by: user
|
||||
|
||||
## Context
|
||||
Adopted from kasra-pay's decision 0035. Next.js 16 streams the metadata to the end of `<body>` for every user agent outside its bot list, whether it comes from `metadata` or `generateMetadata`. That moves the manifest link and `apple-touch-icon` out of `<head>`. Chrome reads the manifest link only from `<head>`, and Safari reads its home-screen tags there, so neither app could be installed with its icon.
|
||||
|
||||
## Decision
|
||||
Both apps set `htmlLimitedBots: /.*/` in `next.config.ts`, so every visitor gets blocking metadata in `<head>`.
|
||||
|
||||
## Alternatives
|
||||
- Write the PWA tags into the root layout's `<head>` by hand and keep streaming: Next.js still adds its own manifest and icon links, so each would appear twice.
|
||||
- Keep streaming: the apps can't be installed properly.
|
||||
|
||||
## Consequences
|
||||
- The first byte of a page waits for its metadata. Static metadata (0055) costs nothing; the channel and post pages wait for their channel and post read, skeleton included.
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
# 0055 Static `metadata` everywhere but the channel and post pages
|
||||
|
||||
Status: Accepted · Area: architecture · Date: 2026-10-09 · Decided by: user
|
||||
|
||||
## Context
|
||||
Adapted from kasra-pay's decision 0036. Under blocking metadata (0054), any data a `generateMetadata` awaits delays the page's first byte. Almost every Lumina route's title and description is fixed copy from i18next. The channel (`/@username`) and post (`/@username/posts/[id]`) pages are the exception: search results and shared-link previews need the channel's and post's name, image and noindex state.
|
||||
|
||||
## Decision
|
||||
- Every layout and page exports a static `metadata` object, translated with the app's `i18n` when its module loads. A module whose metadata reads a server-only namespace (`landing`, `terms`) imports the server bootstrap first.
|
||||
- Only the channel and post pages keep `generateMetadata`, reading through the same per-request cache as the page, so the metadata costs no second request.
|
||||
|
||||
## Alternatives
|
||||
- Static everywhere, as kasra-pay: the fastest first byte, but channels and posts lose their titles and images in search and link previews.
|
||||
- `generateMetadata` everywhere it is convenient: every such page holds back its first byte under 0054.
|
||||
|
||||
## Consequences
|
||||
- On the channel and post pages the skeleton waits for the channel or post read.
|
||||
- A new page whose metadata must name its data needs this decision amended.
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
# 0056 Stop iPhone input zoom with `maximum-scale`
|
||||
|
||||
Status: Accepted · Area: design · Date: 2026-10-09 · Decided by: user
|
||||
|
||||
## Context
|
||||
Adopted from kasra-pay's decision 0037. iOS Safari zooms into any focused field whose text is under 16px. Island `TextInput` and `Select` render 16px text, but `SearchField` renders 15px (`text-body-compact`), so search zooms on iPhones.
|
||||
|
||||
## Decision
|
||||
- bull's root `viewport` sets `width=device-width, initial-scale=1, maximum-scale=1`.
|
||||
- bear keeps the default viewport: nginx sends only iPads and desktops there.
|
||||
|
||||
## Alternatives
|
||||
- 16px text in `SearchField`: no zoom and pinch zoom kept on every browser, but changes the search field's design in both apps.
|
||||
|
||||
## Consequences
|
||||
- iOS Safari ignores `maximum-scale` for pinch zoom, so iPhone users can still zoom by hand.
|
||||
- Android Chrome obeys it: Android users of bull lose pinch zoom. This fails WCAG 2.1 AA 1.4.4 (Resize text), and Lighthouse and axe flag the viewport meta.
|
||||
- Superseding this with 16px field text removes both costs.
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
# 0057 Back goes to its parent, through history only when the parent is behind
|
||||
|
||||
Status: Accepted · Area: architecture · Date: 2026-10-09 · Decided by: user · Supersedes: 0038
|
||||
|
||||
## Context
|
||||
Adopted from kasra-pay's decisions 0038 and 0039. Under 0038, back called `router.back()` whenever any page of this site was behind. After a form moves on with `router.push` (profile save to حساب کاربری, checkout to the channel), that entry is the finished form, and a double press went back two entries.
|
||||
|
||||
## Decision
|
||||
- Keep 0038's roots (خانه, جستجو, the dashboards, a creator's own channel, the landing, login), `href` fixed targets, `useBackTarget`, `onBack`, and `DeskBack` on desktop.
|
||||
- Back is a link to `parentHref` (home by default). A plain click goes back in history only when the previous entry is `parentHref`; otherwise it opens it.
|
||||
- A page reached from several places (a post, `/account/install`) sets `backToPrevious`: it goes back to any previous page of this site. A page without `parentHref` names no parent, so it does the same.
|
||||
- Go back with `navigation.traverseTo(key)` from next/link's `onNavigate`, or `useGoBack` from code, so repeated presses land on the same entry.
|
||||
|
||||
## Alternatives
|
||||
- 0038's any-page rule for every screen: returns to finished forms.
|
||||
- Exact match for every screen: a post opened from خانه would open its channel instead.
|
||||
|
||||
## Consequences
|
||||
- Opened from anywhere but its parent, a back with a named parent pushes the parent instead of restoring the page behind.
|
||||
- Browsers without the Navigation API always open the parent route.
|
||||
- Checkout's `router.push` to the channel still leaves checkout behind the channel, whose back goes to any previous page; that is debt.
|
||||
|
|
@ -5,6 +5,7 @@
|
|||
- 0002 Render every tag through island `Element`, flex layouts through `FlexBox`, grid layouts through `GridBox`; never native JSX tags or `flex`/`grid` classes, island included.
|
||||
- 0011 Serve Yekan Bakh FaNum (`font-sans`, all UI text) and Yekan Bakh (`font-latin`, شبا and bank codes only) from `public/fonts/` under fixed names declared in island `fonts.css`; no version, never hashed, never `next/font`; a changed font gets a new name.
|
||||
- 0019 Close every toast by itself: success and info after 4 s (6 with an action), errors after 8 s (10 with an action); hovering, focus or a hidden tab pauses it; callers never pass `duration: Infinity`.
|
||||
- 0056 Set `maximum-scale=1` in bull's root viewport so iPhones never zoom into fields under 16px; bear keeps the default viewport.
|
||||
|
||||
## Architecture (ADR)
|
||||
|
||||
|
|
@ -14,6 +15,12 @@
|
|||
- 0018 Call the API from the browser only on the app's own origin under `/api`, rewritten by `next.config.ts` to `API_INTERNAL_ORIGIN`; media URLs use the same path, and the server render calls the gateway directly.
|
||||
- 0026 Prerender the landing (`/`) with `force-static` and `revalidate = 600`; every other route keeps `force-dynamic` in its route group's layout, never the root's.
|
||||
- 0027 Serve خانه at `/feed` and the landing at `/`; send a signed-in visitor of `/` to `homeRoute` in the browser with `LandingRedirect`, never in a proxy.
|
||||
- 0051 Serve `/_next/static/` JS and CSS cache first in the service worker; `strategy` (default stale-while-revalidate) applies to fonts and the sprite only.
|
||||
- 0052 Evict the service worker's least recently used entry first, with the key order kept in memory and older-half hits stored again.
|
||||
- 0053 Ship bull and bear with the same worker options and `NEXT_PUBLIC_SERVICE_WORKER_ENABLED`; both serve the manifest from `platforms/market/src/app/manifest`.
|
||||
- 0054 Set `htmlLimitedBots: /.*/` in both apps' `next.config.ts`, so every visitor gets metadata in `<head>`.
|
||||
- 0055 Export static `metadata` from every layout and page; only the channel and post pages use `generateMetadata`, through the page's cached read.
|
||||
- 0057 Back links to `parentHref` and traverses history only when that is the previous entry; `backToPrevious` pages (and pages without `parentHref`) accept any previous page.
|
||||
|
||||
## Proposed
|
||||
|
||||
|
|
@ -39,7 +46,6 @@
|
|||
- 0035 design: Pick a promotion's Shamsi date and time with island `Select`s in a sheet or modal, not a drawn wheel.
|
||||
- 0036 architecture: Keep «ذخیره قیمتگذاری» live during the 7-day lock so promotion changes save; standing prices and period switches stay read-only.
|
||||
- 0037 architecture: Open payout receipts from the API's session-authorized `/payouts/me/payouts/:id/receipt` through `/api`, not signed expiring URLs.
|
||||
- 0038 architecture: Resolve back as onBack → declared target → href → in-app history → `parentHref` → home; desktop non-root pages show `DeskBack` above the title.
|
||||
- 0039 design: Place toasts above whatever draws the bottom edge, declared by that part (nav 80, pinned footer 152, desktop 32, low in sheets).
|
||||
- 0040 architecture: Render the connection bar under the sticky bars, inside their sticky box, never above or over content.
|
||||
- 0041 architecture: Confirm sign-out, call `auth.logout`, then reload to the landing.
|
||||
|
|
|
|||
Loading…
Reference in New Issue