@swiftbrowser/web 0.9.3 → 0.9.4

package/README.md

@@ -292,6 +292,25 @@ remains for the landing page and for `/app/` without a parameter. In the
 `/manifest.webmanifest` is the app's, and the page is titled by the app's
 display name alone.
 
+## Browser history
+
+`src/browserHistory.ts` mirrors the app's navigation in the browser's history
+on the app page: pushing a screen or presenting a sheet adds an entry, and the
+browser's back (a phone's edge swipe, the toolbar button, Alt+Left) pops or
+dismisses it through the same `tap` the bar's back button and the sheet's
+scrim send, so Swift's state stays the source of truth. A pop the app makes
+itself takes the history back with it, and forward returns to the entry that
+matches rather than re-pushing. Depth is read from the DOM after every
+`commit`: the presented sheets plus the pushed screens of each visible stack
+(the selected tab's, both columns of a split view, the top sheet's). The URL
+is left alone. While it is on, the renderer's own edge swipe ignores touch and
+pen: the browser's edge swipe is the swipe back, and it arrives as a
+`popstate` (a mouse drag from the edge still pops through the renderer).
+Its own `history.go` after a pop the app made itself is remembered until the
+`popstate` lands, so commits meanwhile do not go back again.
+An island has it on by default and opts out with `mount(..., { history: false })`
+(`<SwiftUIView history={false}>` in @swiftbrowser/react).
+
 ## Deploying (Cloudflare Pages)
 
 `npm run build` writes a static site to `dist/`: `index.html`, `app/index.html`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swiftbrowser/web",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "type": "module",
   "description": "SwiftBrowser web renderer and dev server: applies render ops from a Swift/Wasm app to the DOM inside an iPhone frame.",
   "repository": {

package/src/browserHistory.ts

@@ -0,0 +1,199 @@
+/**
+ * The browser's history as the app's navigation: pushing a screen or
+ * presenting a sheet adds a history entry, and the browser's back (a
+ * phone's edge swipe, the toolbar button, Alt+Left) pops or dismisses it,
+ * as the bar's own back button would. Forward cannot re-push a screen, so a
+ * forward step lands back where the app is.
+ *
+ * Depth is read from the DOM after every commit: the presented sheets, plus
+ * the pushed screens of every visible stack (the selected tab's, both
+ * columns of a split view, the top sheet's). Pops go through the same event
+ * the back button and the scrim send, so the app's own state stays the
+ * source of truth; the page's URL is never touched, and an app that maps
+ * screens to paths should set them with `replaceState` on the entry the
+ * renderer made.
+ *
+ * While enabled, the renderer's own edge swipe to pop is off for touch and
+ * pen: the browser's edge swipe (Safari's, Android's back gesture) is the
+ * swipe back, and it lands here as a `popstate`. A mouse drag from the edge
+ * still pops through the renderer, since no browser turns one into history.
+ */
+import type { Renderer } from './renderer';
+
+interface HistoryState {
+  /** Our marker; entries without it belong to the page or the app. */
+  sbHistory: true;
+  /** How many levels (screens and sheets) are above the base in this entry. */
+  sbDepth: number;
+}
+
+/** What the renderer's elements need to say for this to read them (`sbId`, `sbDepth` datasets). */
+const stateOf = (value: unknown): HistoryState | null => (typeof value === 'object' && value !== null && (value as HistoryState).sbHistory === true ? (value as HistoryState) : null);
+
+function shown(win: Window, el: HTMLElement): boolean {
+  if (el.hidden || el.getClientRects().length === 0) return false;
+  return win.getComputedStyle(el).visibility !== 'hidden';
+}
+
+export class BrowserHistory {
+  private readonly win: Window;
+  /** Levels the latest `popstate` still asks to dismiss, one commit at a time. */
+  private pendingPops = 0;
+  /** `popstate` events to ignore: the ones our own `history.go` causes. */
+  private ignorePops = 0;
+  /**
+   * The depth our own `history.go` is travelling to while its `popstate` is
+   * still on its way (`go` is asynchronous): commits meanwhile compare
+   * against it, so a second commit does not go back a second time.
+   */
+  private movingTo: number | null = null;
+  private movingTimer: ReturnType<typeof setTimeout> | null = null;
+  private enabled = false;
+
+  constructor(
+    private readonly renderer: Renderer,
+    private readonly root: HTMLElement,
+    win: Window = window,
+  ) {
+    this.win = win;
+  }
+
+  /** Marks the current entry as the base and starts mirroring pushes and pops. */
+  enable(): void {
+    if (this.enabled) return;
+    this.enabled = true;
+    const current = stateOf(this.win.history.state);
+    if (!current) this.win.history.replaceState({ ...(this.win.history.state ?? {}), sbHistory: true, sbDepth: 0 }, '');
+    this.renderer.interaction.nativeBackGesture = true;
+    this.root.addEventListener('sb:commit', this.onCommit);
+    this.win.addEventListener('popstate', this.onPopState);
+    this.sync();
+  }
+
+  dispose(): void {
+    if (!this.enabled) return;
+    this.enabled = false;
+    this.renderer.interaction.nativeBackGesture = false;
+    if (this.movingTimer) clearTimeout(this.movingTimer);
+    this.movingTo = null;
+    this.root.removeEventListener('sb:commit', this.onCommit);
+    this.win.removeEventListener('popstate', this.onPopState);
+  }
+
+  /** The levels above the base the app shows now: sheets, plus pushed screens in each visible stack of the top layer. */
+  depth(): number {
+    const sheets = this.sheets();
+    const top = sheets.at(-1) ?? this.root;
+    let depth = sheets.length;
+    for (const stack of this.stacks(top)) depth += this.topDepth(stack);
+    return depth;
+  }
+
+  private sheets(): HTMLElement[] {
+    return [...this.root.querySelectorAll<HTMLElement>(':scope > .sb-sheet')].filter((sheet) => shown(this.win, sheet));
+  }
+
+  /** The visible navigation stacks within `container`, not those inside a deeper sheet. */
+  private stacks(container: HTMLElement): HTMLElement[] {
+    return [...container.querySelectorAll<HTMLElement>('.sb-navstack')].filter((stack) => shown(this.win, stack) && stack.closest('.sb-sheet') === (container.classList.contains('sb-sheet') ? container : null));
+  }
+
+  private topScreen(stack: HTMLElement): HTMLElement | null {
+    const screens = stack.querySelectorAll<HTMLElement>(':scope > .sb-slot > .sb-navscreen');
+    return screens.length ? screens[screens.length - 1]! : null;
+  }
+
+  private topDepth(stack: HTMLElement): number {
+    const top = this.topScreen(stack);
+    return top ? Number(top.dataset['sbDepth'] ?? '0') || 0 : 0;
+  }
+
+  /** Asks the app to dismiss one level: the top sheet when nothing is pushed inside it, else the deepest visible stack's top screen. */
+  private dismissOne(): boolean {
+    const sheets = this.sheets();
+    const top = sheets.at(-1) ?? this.root;
+    const stacks = this.stacks(top)
+      .map((stack) => ({ stack, depth: this.topDepth(stack) }))
+      .filter((s) => s.depth > 0)
+      .sort((a, b) => b.depth - a.depth);
+    const deepest = stacks[0];
+    if (deepest) {
+      const screen = this.topScreen(deepest.stack);
+      const id = Number(screen?.dataset['sbId']);
+      if (!Number.isInteger(id)) return false;
+      this.renderer.tap(id); // what the back button sends
+      return true;
+    }
+    const sheet = sheets.at(-1);
+    const id = Number(sheet?.dataset['sbId']);
+    if (!Number.isInteger(id)) return false;
+    this.renderer.tap(id); // a dismiss request, as the scrim's tap
+    return true;
+  }
+
+  private recorded(): number {
+    return this.movingTo ?? stateOf(this.win.history.state)?.sbDepth ?? 0;
+  }
+
+  /** Our own `history.go`, remembered until its `popstate` lands (or a moment passes without one: a `go` past the ends fires none). */
+  private go(delta: number, to: number): void {
+    this.ignorePops += 1;
+    this.movingTo = to;
+    if (this.movingTimer) clearTimeout(this.movingTimer);
+    this.movingTimer = setTimeout(() => {
+      if (this.movingTo === null) return;
+      this.movingTo = null;
+      this.ignorePops = Math.max(0, this.ignorePops - 1);
+    }, 1000);
+    this.win.history.go(delta);
+  }
+
+  private arrived(): void {
+    this.movingTo = null;
+    if (this.movingTimer) clearTimeout(this.movingTimer);
+    this.movingTimer = null;
+  }
+
+  private readonly onCommit = (): void => this.sync();
+
+  /** After a commit: new levels get entries; levels the app dismissed itself take the history back with them. */
+  sync(): void {
+    if (!this.enabled) return;
+    const depth = this.depth();
+    const recorded = this.recorded();
+    if (this.pendingPops > 0) {
+      // Dismissing for a `popstate`: the entry already names the target depth.
+      if (depth > recorded) {
+        if (!this.dismissOne()) this.pendingPops = 0;
+        else this.pendingPops -= 1;
+      } else this.pendingPops = 0;
+      return;
+    }
+    if (depth > recorded) {
+      for (let level = recorded + 1; level <= depth; level++) this.win.history.pushState({ sbHistory: true, sbDepth: level } satisfies HistoryState, '');
+    } else if (depth < recorded) {
+      // The app popped or dismissed on its own (back button, swipe, code): leave those entries.
+      this.go(depth - recorded, depth);
+    }
+  }
+
+  private readonly onPopState = (event: PopStateEvent): void => {
+    if (this.ignorePops > 0) {
+      this.ignorePops -= 1;
+      this.arrived();
+      return;
+    }
+    const target = stateOf(event.state);
+    if (!target) return; // an entry of the page's own (before the base, or the app's router): not ours
+    const depth = this.depth();
+    if (target.sbDepth < depth) {
+      // Back: dismiss one level now, the rest as each commit lands.
+      this.pendingPops = depth - target.sbDepth;
+      if (!this.dismissOne()) this.pendingPops = 0;
+      else this.pendingPops -= 1;
+    } else if (target.sbDepth > depth) {
+      // Forward: a screen cannot be re-pushed; return to the entry that matches.
+      this.go(depth - target.sbDepth, depth);
+    }
+  };
+}

package/src/interaction.ts

@@ -202,6 +202,14 @@ export class InteractionController {
   private session: Session | null = null;
   private openSwipe: OpenSwipe | null = null;
   private swipeBack: SwipeBackState | null = null;
+  /**
+   * The browser's own back gesture is in charge (browserHistory.ts mirrors
+   * navigation in the history): the renderer's edge swipe then ignores touch
+   * and pen, whose edge swipe the browser turns into a `popstate` that pops,
+   * so running both would pop twice. A mouse drag from the edge still pops
+   * here: no browser navigates on one.
+   */
+  nativeBackGesture = false;
   /** Wheel-driven swipe of a row: the host, its live offset and the idle timer that settles it. */
   private wheelSwipe: { host: SwipeHost; offset: number; timer: number } | null = null;
   /** Wheel-driven pull at the top of a refreshable scroller. */
@@ -426,7 +434,8 @@ export class InteractionController {
     }
     const byPress = event.pointerType !== 'mouse';
     const screen = target.closest<HTMLElement>('.sb-navscreen');
-    if (screen && screen.dataset['sbNavPosition'] === 'top' && Number(screen.dataset['sbDepth'] ?? '0') > 0 && !this.swipeBack) {
+    const browserSwipes = this.nativeBackGesture && event.pointerType !== 'mouse';
+    if (!browserSwipes && screen && screen.dataset['sbNavPosition'] === 'top' && Number(screen.dataset['sbDepth'] ?? '0') > 0 && !this.swipeBack) {
       const rect = screen.getBoundingClientRect();
       const id = Number(screen.dataset[ID_ATTR]);
       if (event.clientX - rect.left <= SWIPE_BACK_EDGE && Number.isInteger(id)) {

package/src/main.ts

@@ -14,6 +14,7 @@ import {
   type RendererEvent,
   type ScenePhase,
 } from './protocol';
+import { BrowserHistory } from './browserHistory';
 import { Renderer, RendererError } from './renderer';
 import { withBlockedHosts } from './blockedHosts';
 import { withCORSProxy } from './corsProxy';
@@ -97,6 +98,9 @@ function dispatch(event: RendererEvent): void {
 
 const renderer = new Renderer(screen, dispatch);
 
+// The browser's back pops the app's screens and dismisses its sheets (browserHistory.ts).
+new BrowserHistory(renderer, screen).enable();
+
 // On a phone the browser's status bar strip and safe areas take the color the
 // app draws at its top edge (chromeColor.ts).
 const chromeColor = deviceMode ? new ChromeColor(device, screen) : null;

package/src/renderer.ts

@@ -1242,6 +1242,15 @@ export class Renderer {
   /** Called after each layout pass (main.ts keeps the browser chrome's color in step). */
   afterLayout: (() => void) | null = null;
 
+  /**
+   * Sends a tap for an element, as a click on it would: a `navscreen` pops
+   * it (the back button's tap), a `sheet` asks to be dismissed (the scrim's).
+   * For the page's own controls, such as the browser's history (browserHistory.ts).
+   */
+  tap(id: ElementId): void {
+    this.onEvent({ type: 'tap', id });
+  }
+
   /**
    * Run the layout engine over the current tree and position every element.
    * Returns the elements whose box changed. Runs at every `commit`; call it