feat(ui): the mobile shell — routes with real history, five destinations, the lesson as one screen

The reworked artifact went mobile-first; this ports its shell, minus the
quirks it shipped with.

Routes. #lesson #today #settings #words #learn #sent #grammar #cj #hangul
#drill, each a history entry, so the phone's back gesture works. The word
sheet, a popover and the review screen are layers: each owns an entry while
open, and Back closes the topmost before it leaves a route — the artifact
read window.__onBack but never set it. shell/history.ts holds the rules,
free of React and tested against a history whose traversals land late, as a
browser's do. Unlike the artifact's router:
  · re-tapping the current destination pushes nothing;
  · leaving a route closes what is open on it, rewinding its entries first;
  · a sub-page's ← goes back only when history leads to its parent, and
    otherwise becomes the parent — history.length > 1 let ← leave the app.

Shell. The page never scrolls; each route owns one scroller, in svh. A
bottom bar under 600px, a 76px rail to 840px, a labelled rail beyond, with
the artifact's icons and a due badge on 복습. Routes mount on first visit and
stay mounted, so a draft or a drill survives a trip elsewhere. Settings,
the conjugation trainer and the reading drill are pages of their own; 학습
is a hub. The design tokens gain the layout set and a second register:
reference panels stay square, what a thumb works is rounded.

복습 is its own screen: tap anywhere to reveal, grades in the thumb zone,
and an empty queue says so instead of doing nothing. Its pool is "my
units" once there are twenty such words, as in the artifact — plus his own
words, which the artifact dropped from review at that point.

The lesson is a column that fits the screen: roadmap strip, conversation,
composer with the quick-reply chips, and a ··· menu for focus and clearing.
The word list is docked from 840px; below that it is a sheet with peek,
half and full detents and a drag handle, whose height comes off the shell
so the exercise above shrinks rather than being covered. Focusing an answer
drops it to peek; a new exercise takes it down from full.

Fixed on the way: the log now follows a reply by what the learner did, not
by distance — its own scroll event arrived after the stream had added more
than the threshold, which read as scrolling away and stopped the follow
mid-reply. Sending re-sticks. The keyboard's focus guard moves to
pointerdown; React 19 attaches touchstart passively, so preventDefault()
there was ignored.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

test/ui/history.test.ts

@@ -0,0 +1,218 @@
+/* Routes and layers over history — with the one property that makes it hard:
+   history.go() lands on a later task, and anything pushed in between is
+   undone by it. The fake below behaves like a browser in that respect: a
+   traversal only takes effect, and only fires popstate, when the test lets
+   the queue run. */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { Navigator, type HistoryLike } from "@app/ui/shell/history.js";
+
+class FakeHistory implements HistoryLike {
+  entries: { state: unknown; url: string }[] = [{ state: null, url: "#lesson" }];
+  at = 0;
+  pending: number[] = [];
+  onPop: (state: unknown, hash: string) => void = () => {};
+
+  get state() {
+    return this.entries[this.at]!.state;
+  }
+  get hash() {
+    return this.entries[this.at]!.url.slice(1);
+  }
+  pushState(data: unknown, _: string, url = "") {
+    this.entries.splice(this.at + 1, Infinity, { state: structuredClone(data), url });
+    this.at++;
+  }
+  replaceState(data: unknown, _: string, url = "") {
+    this.entries[this.at] = { state: structuredClone(data), url };
+  }
+  go(delta: number) {
+    this.pending.push(delta);
+  }
+  /** The user's own back gesture. */
+  back() {
+    this.pending.push(-1);
+  }
+  /** Let queued traversals land, each firing popstate, as a browser would. */
+  run() {
+    while (this.pending.length) {
+      const delta = this.pending.shift()!;
+      const to = Math.max(0, Math.min(this.entries.length - 1, this.at + delta));
+      if (to === this.at) continue;
+      this.at = to;
+      this.onPop(this.state, this.hash);
+    }
+  }
+  /** Where the address bar is and how deep the stack goes. */
+  get view() {
+    return { at: this.at, urls: this.entries.map((e) => e.url) };
+  }
+}
+
+let h: FakeHistory;
+let nav: Navigator;
+
+beforeEach(() => {
+  h = new FakeHistory();
+  nav = new Navigator(h, "lesson");
+  h.onPop = (s, hash) => nav.onPopState(s, hash);
+});
+
+describe("routes", () => {
+  it("pushes one entry per move, and none for the route already showing", () => {
+    nav.go("words");
+    nav.go("words");
+    nav.go("words");
+    expect(h.view).toEqual({ at: 1, urls: ["#lesson", "#words"] });
+  });
+
+  it("follows the back gesture", () => {
+    nav.go("today");
+    nav.go("settings");
+    h.back();
+    h.run();
+    expect(nav.route).toBe("today");
+    h.back();
+    h.run();
+    expect(nav.route).toBe("lesson");
+  });
+
+  it("sends ← back through history when history leads to the parent", () => {
+    nav.go("learn");
+    nav.go("grammar");
+    nav.go("cj");
+    nav.back();
+    h.run();
+    expect(nav.route).toBe("grammar");
+    expect(h.view.at).toBe(2);
+  });
+
+  it("makes ← become the parent when history leads somewhere else", () => {
+    // Straight from the lesson to the trainer: ← goes up, not back to the lesson.
+    nav.go("cj");
+    nav.back();
+    h.run();
+    expect(nav.route).toBe("grammar");
+    expect(h.view).toEqual({ at: 1, urls: ["#lesson", "#grammar"] });
+  });
+
+  it("never lets ← on a page opened directly leave the app", () => {
+    const direct = new FakeHistory();
+    direct.entries = [{ state: null, url: "#drill" }];
+    const n = new Navigator(direct, "drill");
+    n.back();
+    expect(n.route).toBe("hangul");
+    expect(direct.pending).toEqual([]);
+  });
+});
+
+describe("layers", () => {
+  it("lets Back close the topmost layer before it leaves the route", () => {
+    const closed: string[] = [];
+    nav.go("words");
+    nav.openLayer("sheet", () => closed.push("sheet"));
+    nav.openLayer("pop", () => closed.push("pop"));
+
+    h.back();
+    h.run();
+    expect(closed).toEqual(["pop"]);
+    expect(nav.route).toBe("words");
+
+    h.back();
+    h.run();
+    expect(closed).toEqual(["pop", "sheet"]);
+    expect(nav.route).toBe("words");
+
+    h.back();
+    h.run();
+    expect(nav.route).toBe("lesson");
+  });
+
+  it("takes a layer's entry off the history when its owner closes it", () => {
+    nav.openLayer("review", () => {});
+    expect(h.view.at).toBe(1);
+    nav.releaseLayer("review");
+    h.run();
+    expect(h.view.at).toBe(0);
+    expect(nav.isOpen("review")).toBe(false);
+  });
+
+  it("closes what is open, and rewinds its entries, before moving to another route", () => {
+    const closed: string[] = [];
+    nav.openLayer("sheet", () => closed.push("sheet"));
+    nav.openLayer("pop", () => closed.push("pop"));
+    nav.go("today");
+    expect(closed).toEqual(["pop", "sheet"]);
+    // Nothing is pushed until the rewind has landed — a push made before it
+    // would be undone by it.
+    expect(nav.route).toBe("lesson");
+    h.run();
+    expect(nav.route).toBe("today");
+    expect(h.view).toEqual({ at: 1, urls: ["#lesson", "#today"] });
+
+    h.back();
+    h.run();
+    expect(nav.route).toBe("lesson");
+  });
+
+  it("keeps operations in order while a traversal is still in flight", () => {
+    // Close the popover and open another in the same tick — the second push
+    // must not be made before the first entry is gone.
+    nav.openLayer("pop", () => {});
+    nav.releaseLayer("pop");
+    nav.openLayer("pop", () => {});
+    expect(h.view.at).toBe(1); // still the first popover's entry
+    h.run();
+    expect(h.view.at).toBe(1);
+    expect(nav.isOpen("pop")).toBe(true);
+    h.back();
+    h.run();
+    expect(nav.isOpen("pop")).toBe(false);
+    expect(h.view.at).toBe(0);
+  });
+
+  it("closes the layers above one its owner closes", () => {
+    const closed: string[] = [];
+    nav.openLayer("sheet", () => closed.push("sheet"));
+    nav.openLayer("pop", () => closed.push("pop"));
+    nav.releaseLayer("sheet");
+    expect(closed).toEqual(["pop"]);
+    h.run();
+    expect(h.view.at).toBe(0);
+  });
+
+  it("does not wedge if a traversal never reports back", () => {
+    vi.useFakeTimers();
+    try {
+      nav.openLayer("sheet", () => {});
+      nav.releaseLayer("sheet");
+      h.pending = []; // lost
+      nav.go("today");
+      expect(nav.route).toBe("lesson");
+      vi.advanceTimersByTime(2000);
+      expect(nav.route).toBe("today");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe("reloads and foreign entries", () => {
+  it("comes back on the route it was on, with nothing open", () => {
+    nav.go("words");
+    nav.openLayer("sheet", () => {});
+    const reloaded = new Navigator(h, "words");
+    expect(reloaded.route).toBe("words");
+    expect(reloaded.isOpen("sheet")).toBe(false);
+    expect((h.state as { layer?: string }).layer).toBeUndefined();
+  });
+
+  it("adopts a hash typed into the address bar", () => {
+    const closed: string[] = [];
+    nav.openLayer("sheet", () => closed.push("sheet"));
+    h.pushState(null, "", "#hangul");
+    nav.onPopState(null, "hangul");
+    expect(nav.route).toBe("hangul");
+    expect(closed).toEqual(["sheet"]);
+  });
+});