diff --git a/docs/decisions/0038-back-resolution-and-desk-back.md b/docs/decisions/0038-back-resolution-and-desk-back.md index ad6f343..2302164 100644 --- a/docs/decisions/0038-back-resolution-and-desk-back.md +++ b/docs/decisions/0038-back-resolution-and-desk-back.md @@ -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. diff --git a/docs/decisions/0051-cache-first-for-next-static.md b/docs/decisions/0051-cache-first-for-next-static.md new file mode 100644 index 0000000..8a36d0f --- /dev/null +++ b/docs/decisions/0051-cache-first-for-next-static.md @@ -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. diff --git a/docs/decisions/0052-least-recently-used-eviction.md b/docs/decisions/0052-least-recently-used-eviction.md new file mode 100644 index 0000000..40c5a97 --- /dev/null +++ b/docs/decisions/0052-least-recently-used-eviction.md @@ -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. diff --git a/docs/decisions/0053-one-origin-one-worker.md b/docs/decisions/0053-one-origin-one-worker.md new file mode 100644 index 0000000..6faaceb --- /dev/null +++ b/docs/decisions/0053-one-origin-one-worker.md @@ -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. diff --git a/docs/decisions/0054-blocking-metadata-in-head.md b/docs/decisions/0054-blocking-metadata-in-head.md new file mode 100644 index 0000000..0ee11f1 --- /dev/null +++ b/docs/decisions/0054-blocking-metadata-in-head.md @@ -0,0 +1,16 @@ +# 0054 Render the metadata in `` 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 `` 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 ``. Chrome reads the manifest link only from ``, 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 ``. + +## Alternatives +- Write the PWA tags into the root layout's `` 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. diff --git a/docs/decisions/0055-static-metadata-except-channel-and-post.md b/docs/decisions/0055-static-metadata-except-channel-and-post.md new file mode 100644 index 0000000..7bac403 --- /dev/null +++ b/docs/decisions/0055-static-metadata-except-channel-and-post.md @@ -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. diff --git a/docs/decisions/0056-no-input-zoom-on-iphone.md b/docs/decisions/0056-no-input-zoom-on-iphone.md new file mode 100644 index 0000000..b4cfe9a --- /dev/null +++ b/docs/decisions/0056-no-input-zoom-on-iphone.md @@ -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. diff --git a/docs/decisions/0057-back-goes-to-its-parent.md b/docs/decisions/0057-back-goes-to-its-parent.md new file mode 100644 index 0000000..4894c83 --- /dev/null +++ b/docs/decisions/0057-back-goes-to-its-parent.md @@ -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. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 65302d7..8ffb491 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -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 ``. +- 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.