feat: coordinate sections signs and native navigation

src/journey/navigation-controller.ts

@@ -0,0 +1,321 @@
+import type { SectionId } from "@/content/types";
+import type { JourneySource } from "./types";
+
+export interface NavigationState {
+  epoch: number;
+  source: JourneySource;
+  destinationId: SectionId | null;
+}
+
+export interface NavigationRuntime {
+  getHash(): string;
+  pushHash(hash: string): void;
+  replaceHash(hash: string): void;
+  scrollTarget(target: HTMLElement, behavior: ScrollBehavior): void;
+  focusHeading(target: HTMLElement): void;
+  getScrollY(): number;
+  requestFrame(callback: FrameRequestCallback): number;
+  cancelFrame(id: number): void;
+  setTimer(callback: () => void, delay: number): number;
+  clearTimer(id: number): void;
+  supportsScrollEnd: boolean;
+  addScrollEndListener(listener: EventListener): void;
+  removeScrollEndListener(listener: EventListener): void;
+}
+
+export interface NavigationController {
+  navigate(id: SectionId, target: HTMLElement): number;
+  noteUserScrollIntent(): number;
+  notePassiveSection(id: SectionId): void;
+  initialize(id: SectionId, target: HTMLElement): number;
+  restore(id: SectionId, target: HTMLElement): number;
+  state(): NavigationState;
+  subscribe(listener: (state: NavigationState) => void): () => void;
+  dispose(): void;
+}
+
+const SETTLE_TIMEOUT_MS = 1500;
+const PASSIVE_REPLACE_DELAY_MS = 150;
+const STABLE_FRAME_COUNT = 3;
+const STABLE_SCROLL_DELTA_PX = 1;
+
+export function canonicalSectionIdFromHash(
+  hash: string,
+  canonicalIds: readonly SectionId[],
+): SectionId | null {
+  const encoded = hash.startsWith("#") ? hash.slice(1) : hash;
+  if (encoded === "") return canonicalIds[0] ?? null;
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(encoded);
+  } catch {
+    return null;
+  }
+  return canonicalIds.find((id) => id === decoded) ?? null;
+}
+
+export function validateSectionAnchor(
+  anchor: HTMLAnchorElement,
+  canonicalIds: readonly SectionId[],
+): { id: SectionId; target: HTMLElement } | null {
+  let url: URL;
+  try {
+    url = new URL(anchor.href, window.location.href);
+  } catch {
+    return null;
+  }
+  if (
+    url.origin !== window.location.origin ||
+    url.pathname !== window.location.pathname ||
+    url.search !== window.location.search
+  ) {
+    return null;
+  }
+
+  const id = canonicalSectionIdFromHash(url.hash, canonicalIds);
+  if (id === null) return null;
+  const target = document.getElementById(id);
+  if (!(target instanceof HTMLElement) || target.id !== id) return null;
+  const heading = target.querySelector<HTMLElement>(
+    ':scope > h2[tabindex="-1"]',
+  );
+  return heading === null ? null : { id, target };
+}
+
+const browserRuntime = (): NavigationRuntime => ({
+  getHash: () => window.location.hash,
+  pushHash: (hash) => window.history.pushState(window.history.state, "", hash),
+  replaceHash: (hash) =>
+    window.history.replaceState(window.history.state, "", hash),
+  scrollTarget: (target, behavior) =>
+    target.scrollIntoView({ behavior, block: "start" }),
+  focusHeading: (target) => {
+    target
+      .querySelector<HTMLElement>(':scope > h2[tabindex="-1"]')
+      ?.focus({ preventScroll: true });
+  },
+  getScrollY: () => window.scrollY,
+  requestFrame: (callback) => window.requestAnimationFrame(callback),
+  cancelFrame: (id) => window.cancelAnimationFrame(id),
+  setTimer: (callback, delay) => window.setTimeout(callback, delay),
+  clearTimer: (id) => window.clearTimeout(id),
+  supportsScrollEnd: "onscrollend" in window,
+  addScrollEndListener: (listener) =>
+    window.addEventListener("scrollend", listener),
+  removeScrollEndListener: (listener) =>
+    window.removeEventListener("scrollend", listener),
+});
+
+export function createNavigationController(
+  canonicalIds: readonly SectionId[],
+  runtime: NavigationRuntime = browserRuntime(),
+): NavigationController {
+  let currentState: NavigationState = {
+    epoch: 0,
+    source: "initial",
+    destinationId: null,
+  };
+  const subscribers = new Set<(state: NavigationState) => void>();
+  let frameId: number | undefined;
+  let settleTimerId: number | undefined;
+  let passiveTimerId: number | undefined;
+  let scrollEndListener: EventListener | undefined;
+
+  const emit = (): void => {
+    for (const subscriber of subscribers) subscriber({ ...currentState });
+  };
+
+  const cancelSettle = (): void => {
+    if (frameId !== undefined) {
+      runtime.cancelFrame(frameId);
+      frameId = undefined;
+    }
+    if (settleTimerId !== undefined) {
+      runtime.clearTimer(settleTimerId);
+      settleTimerId = undefined;
+    }
+    if (scrollEndListener !== undefined) {
+      runtime.removeScrollEndListener(scrollEndListener);
+      scrollEndListener = undefined;
+    }
+  };
+
+  const cancelPassiveReplace = (): void => {
+    if (passiveTimerId !== undefined) {
+      runtime.clearTimer(passiveTimerId);
+      passiveTimerId = undefined;
+    }
+  };
+
+  const cancelPending = (): void => {
+    cancelSettle();
+    cancelPassiveReplace();
+  };
+
+  const beginEpoch = (
+    source: JourneySource,
+    destinationId: SectionId | null,
+  ): number => {
+    cancelPending();
+    currentState = {
+      epoch: currentState.epoch + 1,
+      source,
+      destinationId,
+    };
+    emit();
+    return currentState.epoch;
+  };
+
+  const requireTarget = (id: SectionId, target: HTMLElement): void => {
+    if (!canonicalIds.includes(id) || target.id !== id) {
+      throw new Error(`Invalid canonical navigation target: ${id}`);
+    }
+  };
+
+  const settleExplicit = (
+    epoch: number,
+    id: SectionId,
+    target: HTMLElement,
+  ): void => {
+    if (
+      currentState.epoch !== epoch ||
+      currentState.source !== "explicit-navigation" ||
+      currentState.destinationId !== id
+    ) {
+      return;
+    }
+    cancelSettle();
+    frameId = runtime.requestFrame(() => {
+      frameId = undefined;
+      if (
+        currentState.epoch === epoch &&
+        currentState.source === "explicit-navigation" &&
+        currentState.destinationId === id
+      ) {
+        runtime.focusHeading(target);
+      }
+    });
+  };
+
+  const scheduleSettle = (
+    epoch: number,
+    id: SectionId,
+    target: HTMLElement,
+  ): void => {
+    settleTimerId = runtime.setTimer(() => {
+      settleTimerId = undefined;
+      if (
+        currentState.epoch !== epoch ||
+        currentState.source !== "explicit-navigation" ||
+        currentState.destinationId !== id
+      ) {
+        return;
+      }
+      runtime.scrollTarget(target, "instant");
+      settleExplicit(epoch, id, target);
+    }, SETTLE_TIMEOUT_MS);
+
+    if (runtime.supportsScrollEnd) {
+      scrollEndListener = (): void => settleExplicit(epoch, id, target);
+      runtime.addScrollEndListener(scrollEndListener);
+      return;
+    }
+
+    let previousScrollY = runtime.getScrollY();
+    let stableFrames = 0;
+    const inspectFrame = (): void => {
+      frameId = undefined;
+      if (
+        currentState.epoch !== epoch ||
+        currentState.source !== "explicit-navigation" ||
+        currentState.destinationId !== id
+      ) {
+        return;
+      }
+      const scrollY = runtime.getScrollY();
+      stableFrames =
+        Math.abs(scrollY - previousScrollY) < STABLE_SCROLL_DELTA_PX
+          ? stableFrames + 1
+          : 0;
+      previousScrollY = scrollY;
+      if (stableFrames >= STABLE_FRAME_COUNT) {
+        settleExplicit(epoch, id, target);
+      } else {
+        frameId = runtime.requestFrame(inspectFrame);
+      }
+    };
+    frameId = runtime.requestFrame(inspectFrame);
+  };
+
+  const alignWithoutFocus = (
+    source: "initial" | "history-restoration",
+    id: SectionId,
+    target: HTMLElement,
+  ): number => {
+    requireTarget(id, target);
+    const epoch = beginEpoch(source, id);
+    if (source === "initial") {
+      runtime.scrollTarget(target, "instant");
+    } else {
+      frameId = runtime.requestFrame(() => {
+        frameId = undefined;
+        if (
+          currentState.epoch === epoch &&
+          currentState.source === source &&
+          currentState.destinationId === id
+        ) {
+          runtime.scrollTarget(target, "instant");
+        }
+      });
+    }
+    return epoch;
+  };
+
+  return {
+    navigate(id, target) {
+      requireTarget(id, target);
+      const epoch = beginEpoch("explicit-navigation", id);
+      if (canonicalSectionIdFromHash(runtime.getHash(), canonicalIds) !== id) {
+        runtime.pushHash(`#${id}`);
+      }
+      scheduleSettle(epoch, id, target);
+      runtime.scrollTarget(target, "smooth");
+      return epoch;
+    },
+    noteUserScrollIntent() {
+      return beginEpoch("passive-scroll", null);
+    },
+    notePassiveSection(id) {
+      if (currentState.source !== "passive-scroll") return;
+      cancelPassiveReplace();
+      const epoch = currentState.epoch;
+      passiveTimerId = runtime.setTimer(() => {
+        passiveTimerId = undefined;
+        if (
+          currentState.epoch === epoch &&
+          currentState.source === "passive-scroll" &&
+          canonicalSectionIdFromHash(runtime.getHash(), canonicalIds) !== id
+        ) {
+          runtime.replaceHash(`#${id}`);
+        }
+      }, PASSIVE_REPLACE_DELAY_MS);
+    },
+    initialize(id, target) {
+      return alignWithoutFocus("initial", id, target);
+    },
+    restore(id, target) {
+      return alignWithoutFocus("history-restoration", id, target);
+    },
+    state: () => ({ ...currentState }),
+    subscribe(listener) {
+      subscribers.add(listener);
+      listener({ ...currentState });
+      return () => subscribers.delete(listener);
+    },
+    dispose() {
+      cancelPending();
+      currentState = { ...currentState, epoch: currentState.epoch + 1 };
+      subscribers.clear();
+    },
+  };
+}

src/journey/section-controller.ts

@@ -0,0 +1,78 @@
+import type { SectionId } from "@/content/types";
+import type { EnvironmentChapter } from "./types";
+
+export interface SectionHeadingGeometry {
+  id: SectionId;
+  top: number;
+}
+
+export interface ActiveSectionInput {
+  headings: readonly SectionHeadingGeometry[];
+  activationY: number;
+  atDocumentEnd: boolean;
+}
+
+export interface DerivedSectionState {
+  activeSectionId: SectionId;
+  chapter: EnvironmentChapter;
+  arrived: boolean;
+}
+
+export interface ActivationLineInput {
+  scrollY: number;
+  visualViewportOffsetTop: number;
+  visualViewportHeight: number;
+}
+
+export const activationLineDocumentY = (input: ActivationLineInput): number =>
+  input.scrollY +
+  input.visualViewportOffsetTop +
+  input.visualViewportHeight * 0.35;
+
+export interface DocumentEndInput {
+  scrollY: number;
+  scrollHeight: number;
+  visualViewportHeight: number;
+}
+
+export const isAtDocumentEnd = (input: DocumentEndInput): boolean =>
+  Math.max(0, input.scrollHeight - input.visualViewportHeight) -
+    input.scrollY <=
+  2;
+
+export function selectActiveSection(input: ActiveSectionInput): SectionId {
+  const first = input.headings[0];
+  if (first === undefined) {
+    throw new Error("At least one canonical section heading is required.");
+  }
+  if (input.atDocumentEnd) {
+    return input.headings[input.headings.length - 1]?.id ?? first.id;
+  }
+
+  let active = first.id;
+  for (const heading of input.headings) {
+    if (heading.top <= input.activationY) active = heading.id;
+  }
+  return active;
+}
+
+const chapters: Readonly<Record<SectionId, EnvironmentChapter>> = {
+  start: "deep-night",
+  profile: "deep-night",
+  experience: "systems",
+  infrastructure: "infrastructure",
+  "selected-builds": "builds",
+  "additional-work": "builds",
+  toolkit: "pre-dawn",
+  contact: "destination",
+};
+
+export function deriveSectionState(
+  activeSectionId: SectionId,
+): DerivedSectionState {
+  return {
+    activeSectionId,
+    chapter: chapters[activeSectionId],
+    arrived: activeSectionId === "contact",
+  };
+}

src/journey/sign-controller.ts

@@ -0,0 +1,53 @@
+import type { SectionId } from "@/content/types";
+import type { JourneySource, SignSnapshot } from "./types";
+
+export interface SignSample {
+  source: JourneySource;
+  deltaY: number;
+  viewportHeight: number;
+  crossedBoundaries: number;
+  candidateId: SectionId | null;
+  distanceVh: number;
+  motionAllowed: boolean;
+}
+
+const clamp01 = (value: number): number => Math.min(1, Math.max(0, value));
+
+export function nextSign(
+  current: SignSnapshot | null,
+  input: SignSample,
+): SignSnapshot | null {
+  const eligible =
+    input.motionAllowed &&
+    input.source === "passive-scroll" &&
+    Number.isFinite(input.deltaY) &&
+    Number.isFinite(input.viewportHeight) &&
+    Number.isFinite(input.distanceVh) &&
+    input.viewportHeight > 0 &&
+    input.deltaY > 0 &&
+    input.deltaY <= input.viewportHeight * 0.75 &&
+    input.crossedBoundaries <= 1;
+
+  if (!eligible || input.distanceVh > 1.2 || input.distanceVh <= -0.25) {
+    return null;
+  }
+
+  const targetId = current?.targetId ?? input.candidateId;
+  if (targetId === null) return null;
+
+  if (input.distanceVh > 0.55) {
+    return {
+      targetId,
+      phase: "approach",
+      progress: clamp01((1.2 - input.distanceVh) / 0.65),
+    };
+  }
+  if (input.distanceVh > 0.15) {
+    return { targetId, phase: "stabilized", progress: 1 };
+  }
+  return {
+    targetId,
+    phase: "pass",
+    progress: clamp01((0.15 - input.distanceVh) / 0.4),
+  };
+}

src/journey/types.ts

@@ -1,3 +1,5 @@
+import type { SectionId } from "@/content/types";
+
 export interface ScrollDriveSample {
   scrollY: number;
   now: number;
@@ -16,3 +18,27 @@ export interface ScrollDriveController {
   sample(input: ScrollDriveSample): ScrollDriveSnapshot;
   reset(input?: ScrollDriveSample): ScrollDriveSnapshot;
 }
+
+export type JourneySource =
+  "initial" | "explicit-navigation" | "passive-scroll" | "history-restoration";
+
+export type EnvironmentChapter =
+  | "deep-night"
+  | "systems"
+  | "infrastructure"
+  | "builds"
+  | "pre-dawn"
+  | "destination";
+
+export interface SignSnapshot {
+  targetId: SectionId;
+  phase: "approach" | "stabilized" | "pass";
+  progress: number;
+}
+
+export interface JourneySnapshot extends ScrollDriveSnapshot {
+  activeSectionId: SectionId;
+  chapter: EnvironmentChapter;
+  sign: SignSnapshot | null;
+  arrived: boolean;
+}