Which mark, where, and who says so

.claude/memory/MEMORY.md

@@ -0,0 +1,10 @@
+# Memory index
+
+- [Hifth app identity](hifth-app-identity.md) — Quran navigation app for huffaz, renamed from "Linker", loops plan in docs/PLAN.md
+- [Artifacts in English by default](artifacts-english-by-default.md) — mocks/walkthroughs use English chrome, only scripture stays Arabic; watch published artifacts for feedback
+- [Desktop edge-grab page turn](desktop-edge-grab-turn.md) — desktop spread turns by grabbing the outer fore-edge (hand cursor); mid-page drags never turn
+- [Juz-jump leaf alignment](juz-jump-leaf-alignment.md) — a hop revealed the incoming leaf before centring it (1-frame ~9px flash); fixed by centerCurrent() in navigateTo; rebuild dist before e2e
+- [Desktop zoom StrictMode orphan](desktop-zoom-strictmode-orphan.md) — "zoom broken on spread" was a dev-only StrictMode orphan host; teardown now removes hosts; prod was never affected
+- [SPA hash nav is not a reload](spa-hash-nav-no-reload.md) — a #-only navigate keeps the old bundle on 5173; force location.reload() before calling a change "not rendered"
+- [Playwright WebKit missing](playwright-webkit-missing.md) — iphone e2e project cannot launch locally; run the Chromium projects, ask before installing WebKit
+- [Designs public on the site](designs-public-on-site.md) — tenet since 2026-09-01: docs/ pages are served from blog.bytesofpurpose.com/hifth/docs/ by the build; never publish a decision page to claude.ai as its address

.claude/memory/artifacts-english-by-default.md

@@ -0,0 +1,25 @@
+---
+name: artifacts-english-by-default
+description: Build design artifacts/mocks with English UI chrome by default; keep only scripture Arabic; watch them for comment feedback
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: e1a37078-db9f-4e9e-a2a4-0d297cd099ff
+  modified: 2026-08-29T19:28:22.343Z
+---
+
+When building a visual artifact / mock / walkthrough for review (e.g. the confusion-points
+"Where You Slip" page), the **app chrome must default to English** — button labels, menu
+items, warnings, list rows, legends. The only Arabic that stays is the **Qur'an text itself**
+(ayah words, surah names as they appear on the mus'haf) — that is scripture, not chrome.
+
+Also: **publish these design artifacts in English mode and set a comment watch** so feedback
+can be captured for future sessions.
+
+**Why:** the owner reviews and leaves feedback in English; Arabic-only chrome in the mocks
+makes the experience unreadable to a reviewer and to anyone they show it to, and undercuts the
+CLAUDE.md tenet that a decision page be followable by a stranger.
+
+**How to apply:** default new mock UI labels to English; render ayah text in Arabic; keep a
+short glossary for domain words; after publishing, establish/keep a comment watch. See
+[[hifth-app-identity]].

.claude/memory/designs-public-on-site.md

@@ -0,0 +1,26 @@
+---
+name: designs-public-on-site
+description: "Tenet since 2026-09-01 — every design page under docs/ is public on the app's own site at the same path; never publish decision pages to claude.ai as their address"
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: c8c77742-fa0c-48ea-9c25-4e720245832a
+  modified: 2026-09-02T02:13:50.680Z
+---
+
+The owner wants every design and decision page public-facing, for transparency, and made it a
+tenet of the repo (CLAUDE.md "Every design is public"). The web build stages `docs/**/*.html`
+onto the site at the same path, so `docs/design/x.html` is
+`https://blog.bytesofpurpose.com/hifth/docs/design/x.html`, with a front door at `/docs/` linked
+from the colophon. A decision's `artifact` is derived from its `page` and the gate refuses any
+other address.
+
+**Why:** "i want all the designs to be public facing for transparency" / "this should be a tenant
+for our repo". Earlier, nine pages went to claude.ai and the tree named five; a link on another
+host dies with the host.
+
+**How to apply:** publishing a design = merging it. Do not publish pages to claude.ai as the
+decision's address; a conversational copy is allowed but goes in `docs/artifacts.json` as a copy.
+Pages reference vendored art as `../../apps/web/public/assets/…` and the staging step rewrites
+it; any other dangling relative link fails the build. See [[hifth-app-identity]] and
+[[artifacts-english-by-default]].

.claude/memory/desktop-edge-grab-turn.md

@@ -0,0 +1,45 @@
+---
+name: desktop-edge-grab-turn
+description: "On the desktop spread the page turns only by grabbing its outer fore-edge, not by dragging across the middle"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: c8c77742-fa0c-48ea-9c25-4e720245832a
+  modified: 2026-09-01T17:31:44.144Z
+---
+
+On the desktop two-page spread, turning a page is an **edge grab**, not a swipe
+across the page. The user was explicit: hovering the outer sides shows a hand
+cursor, grabbing a fore-edge and dragging turns/flips the leaf, and **any drag
+that does not start at a page edge must not turn the page** — the middle is left
+free to pan and select. Grab zone shape: a strip down each leaf's outer edge that
+**widens at the top/bottom corners** (pinched to a sliver at the vertical middle);
+the centre fold/gutter is never grabbable.
+
+**Why:** a hafiz turns a physical mus'haf by its fore-edge; the old
+drag-anywhere swipe-to-turn fought selecting and panning on a big screen.
+
+**How to apply:** the rails live on the book (one outer edge belongs to the
+*facing* leaf, which the live stage feels no pointer on) and drive the live
+stage's exposed turn verbs; left edge pulls forward, right edge pulls back
+(drag-right = forward, matching the swipe convention). Desktop swipe-to-turn is
+off (the live stage gets `dragToTurn={!desktop}`); wheel and arrow keys still
+turn. The phone is untouched — it keeps swipe-to-turn and has no rails. See
+[[hifth-app-identity]].
+
+**The grab is a trigger, not a tracked band (as of the peel decision).** Reusing
+the phone's finger-locked band on desktop drew a thin fore-edge strip creeping
+1:1 over a spread whose two pages had not changed yet — the reader saw "a
+vertical bar on the same page," not a turn. So the desktop edge verbs now draw
+nothing while the hand moves; on release the commit rule decides, and a
+committed grab is handed to the *ordinary* animated turn (the same flip a wheel
+or arrow plays — grab, wheel and arrows all funnel through `onTurn → turnTo →
+runTurn`). A faithful drag-to-**peel** that reveals the destination *opening*
+under a lifting corner is the larger job tracked as the desktop page-turn
+animation (#11): it must drive **both** leaves at once (the leaf that lifts and
+the destination pages sit on opposite sides of the gutter, and which leaf lifts
+depends on turn direction), respect "no 170KB SVG glyph moves" (reveal by
+masking a corner off the current page over the already-mounted destination
+beneath — never a transform on the page), and wants a live browser to tune.
+Because every trigger shares `runTurn`, building the peel there gives scroll and
+arrows the peel for free — keep that coupling.

.claude/memory/desktop-zoom-strictmode-orphan.md

@@ -0,0 +1,21 @@
+---
+name: desktop-zoom-strictmode-orphan
+description: "Zoom broken on desktop spread" (one leaf grows, one stays) was a dev-only React StrictMode orphan host, not a prod bug
+metadata:
+  type: project
+---
+
+The desktop-spread "zooming is broken / don't see full pages on zoom" report reproduced
+**only in the dev server** (`pnpm dev`, port 5173), never in the production build (`vite
+preview`, 4173). Cause: React StrictMode's dev double-invoke mounts → tears down → remounts
+against the *same* layer. `PageStage`'s teardown effect cleared the page Map but did **not**
+`host.remove()`, so the first mount's host lingered as an orphan `<div>` outside the Map. Zoom
+transforms only the Map's host (`applyTransform` reads `pagesRef.get(currentPage)`), so the
+orphan twin sat un-magnified under the one that grew — reading as "one leaf zooms, one doesn't."
+
+Fix (in `apps/web/src/components/PageStage.tsx`): teardown now removes each host from the
+layer; `mountPage` re-reads the Map after its last await and yields to a rival that already
+landed the page. Guarded by a StrictMode regression test in `PageStage.budget.test.tsx`
+(confirmed it fails `-2/+1` on original code). Production was never affected — StrictMode is a
+dev-only wrapper — but the dev server is what a developer previews in. See also the cold-link
+blank-leaf reveal fix in the same file (showPage/navigateTo reveal unconditionally).

.claude/memory/hifth-app-identity.md

@@ -0,0 +1,21 @@
+---
+name: hifth-app-identity
+description: "What the hifth project is — Quran navigation app for huffaz, renamed from design-phase \"Linker\", built in loops per docs/PLAN.md"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 0da21e77-a946-4228-877a-aee0949749f7
+  modified: 2026-07-20T09:33:16.009Z
+---
+
+Hifth (حفظ) is a pure navigation web app for huffaz: tap/highlight an ayah on real
+mushaf SVG pages → hop to similar verses (mutashabihat), shared roots, etc. Knowledge
+graph = static adjacency JSON; no backend. Designed in a claude.ai conversation
+(shared: https://claude.ai/share/9d43fe10-4c1a-4880-86eb-4adcadb3dfbb) under the
+codename "Linker · رابط"; user renamed it **Hifth** on 2026-07-20.
+
+Key user decisions (2026-07-20): web app first with mobile support (PWA, touch-first);
+implement iteratively in loops (each loop = vertical slice demoed on a phone); proper
+component architecture is a requirement, not an afterthought. Spec of record:
+`docs/reference/linker-spec.md`; plan: `docs/PLAN.md`; interactive mock and architecture
+diagram also in `docs/reference/`.

.claude/memory/juz-jump-leaf-alignment.md

@@ -0,0 +1,36 @@
+---
+name: juz-jump-leaf-alignment
+description: "Why a juz jump could flash the two desktop leaves at different heights, and the one-line fix"
+metadata:
+  node_type: memory
+  type: project
+  originSessionId: c8c77742-fa0c-48ea-9c25-4e720245832a
+  modified: 2026-09-01T17:53:16.966Z
+---
+
+On the desktop two-page spread, a jump to another juz (or any non-adjacent
+relocation) could flash the two leaves at **different heights** for one frame —
+the reported "sometimes things aren't aligned after a juz jump."
+
+**Root cause.** A juz jump is a *hop*, not a page turn: it runs the live stage's
+`navigateTo`, which reveals the incoming page (`setCurrentPage` → `display:block`)
+and only *frames* it afterwards, inside an `await`ed tween. A freshly mounted host
+wears no transform, so for the one paint before the tween's first frame the
+incoming page sat at its leaf's top-left — one centring offset (~9px) above the
+facing leaf beside it. On a fast machine that is a single frame; on a real one the
+incoming ~170KB SVG's parse stalls the correcting frame long enough to see and
+screenshot. (The page-*turn* path, `crossFade`, never had this — it applies the
+transform synchronously and forces a reflow *before* revealing: the "arrive
+already wearing your transform" rule.)
+
+**Fix.** One line in `navigateTo`: call `centerCurrent()` right after
+`setCurrentPage`, so the incoming leaf arrives centred before the tween can yield.
+A zoom-1 hop then simply rests there; a closer hop (an ayah hop) tweens out from
+fit, which is the correct motion anyway.
+
+**Guard.** `desktop.spec.ts` → "a juz jump keeps the two leaves level through
+every frame" polls both leaves' top edges every frame across the settle and fails
+if any frame caught them >1.5px apart (proven to bite without the fix). Note the
+e2e gotcha: `vite preview` serves the pre-built `dist/`, so **rebuild (`pnpm
+build`) after every source edit** or the test runs stale bytes. See
+[[desktop-edge-grab-turn]], [[hifth-app-identity]].

.claude/memory/playwright-webkit-missing.md

@@ -0,0 +1,20 @@
+---
+name: playwright-webkit-missing
+description: "The e2e \"iphone\" project runs on WebKit, which is not installed on this laptop — every iphone test fails at browser launch, not in the app; run desktop/android/golden (Chromium) and ask before installing"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: c8c77742-fa0c-48ea-9c25-4e720245832a
+  modified: 2026-09-02T00:04:00.172Z
+---
+
+On 2026-09-01 the full `npx playwright test` run failed every `[iphone]` test with
+`browserType.launch: Executable doesn't exist at ~/Library/Caches/ms-playwright/webkit-2311/pw_run.sh`.
+The `desktop`, `android` (Pixel 7) and `golden` projects are Chromium and run fine.
+
+**Why:** WebKit was never installed via `npx playwright install webkit` on this machine. Installing it
+is a download from Playwright's CDN, which needs the user's explicit go-ahead first.
+
+**How to apply:** Verify a change with `--project desktop --project android --project golden`. Report
+the iphone project as *not run*, never as failing. Offer the install as a one-line ask rather than
+starting it. See [[spa-hash-nav-no-reload]] for the rest of the verification recipe.

.claude/memory/spa-hash-nav-no-reload.md

@@ -0,0 +1,26 @@
+---
+name: spa-hash-nav-no-reload
+description: "Navigating the dev app to a hash-only URL does not reload the SPA — the DOM keeps the old bundle even after a Vite restart; force location.reload() before concluding a change \"did not render\""
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: c8c77742-fa0c-48ea-9c25-4e720245832a
+  modified: 2026-09-01T23:47:36.435Z
+---
+
+When verifying a UI change on `localhost:5173`, navigating the tab to `http://localhost:5173/#/...`
+(a hash-only change) does **not** reload the document. The React tree keeps running the old
+module graph. Restarting Vite and clearing `node_modules/.vite` does not help either, because
+the browser never re-fetches the entry. The served source can be verified new (fetch the module
+and grep it) while the DOM is still old.
+
+**Why:** In this session the finished page-bar redesign (30 juz detents, page-icon handle) read as
+"not rendering" for several turns — the DOM had zero detents while the served `PageSlider.tsx`
+already contained them. One `location.reload()` showed everything. See also
+[[desktop-zoom-strictmode-orphan]] for the sibling trap: a fault that shows only under the dev
+server's StrictMode double-mount (5173) and not in the built app (4173).
+
+**How to apply:** After editing, force a real reload (JS `location.reload()` or navigate to a
+different path and back) before reading the DOM. If something reproduces on 5173 and not 4173,
+say it is dev-only. Rebuild `dist` before e2e and free port 4173 first. The `run-app` skill
+carries the recipe.