ignotum 0.0.13 → 0.0.15

package/src/client/router-store.ts

@@ -0,0 +1,644 @@
+import type {
+  AppModuleId,
+  LayoutDefinition,
+  ModuleExportReference,
+  RouteDefinition,
+} from "@ignotum/contracts/app-definition";
+import { ExecutionSelection } from "@ignotum/contracts/platform";
+import { RouterHistory, type HistoryPosition } from "./router-history.js";
+import {
+  compilePatterns,
+  matchLocation,
+  resolveMetadata,
+  type RouteOutcome,
+  type UrlValue,
+  type UrlIssue,
+} from "@ignotum/shared/routing";
+import { Deferred, Effect, Predicate, Schema } from "effect";
+import type { ComponentChildren, ComponentType } from "preact";
+import type { NavigationResult, RouteLocation } from "./routes.js";
+
+export interface RegisteredClientModule {
+  readonly load: () => Promise<object>;
+  readonly styles?: readonly string[];
+}
+
+/** Executable registration produced by the compiler, separate from the immutable declaration. */
+export interface ClientRegistration {
+  readonly applicationName: string;
+  readonly routes: readonly RouteDefinition[];
+  readonly layouts: readonly LayoutDefinition[];
+  readonly modules: ReadonlyMap<AppModuleId, RegisteredClientModule>;
+  readonly styles?: readonly string[];
+}
+
+export interface RouterPageProps {
+  readonly params: Readonly<Record<string, UrlValue>>;
+  readonly searchParams: Readonly<Record<string, UrlValue>>;
+}
+export interface RouterLayoutProps {
+  readonly children: ComponentChildren;
+}
+export interface ErrorBoundaryProps {
+  readonly error: unknown;
+  readonly retry: () => void;
+}
+export interface InvalidBoundaryProps {
+  readonly location: RouteLocation;
+  readonly issues: readonly UrlIssue[];
+}
+export interface NotFoundBoundaryProps {
+  readonly location: RouteLocation;
+}
+const ErrorComponent = Schema.declare((value): value is ComponentType<ErrorBoundaryProps> =>
+  Predicate.isFunction(value),
+);
+const InvalidComponent = Schema.declare((value): value is ComponentType<InvalidBoundaryProps> =>
+  Predicate.isFunction(value),
+);
+const NotFoundComponent = Schema.declare((value): value is ComponentType<NotFoundBoundaryProps> =>
+  Predicate.isFunction(value),
+);
+const PageModule = Schema.Struct({
+  error: Schema.optional(ErrorComponent),
+  invalid: Schema.optional(InvalidComponent),
+  component: Schema.declare((value): value is ComponentType<RouterPageProps> =>
+    Predicate.isFunction(value),
+  ),
+});
+const LayoutModule = Schema.Struct({
+  error: Schema.optional(ErrorComponent),
+  invalid: Schema.optional(InvalidComponent),
+  notFound: Schema.optional(NotFoundComponent),
+  component: Schema.declare((value): value is ComponentType<RouterLayoutProps> =>
+    Predicate.isFunction(value),
+  ),
+});
+const ModuleExports = Schema.Record(Schema.String, Schema.Unknown);
+
+export interface LoadedBranch {
+  readonly outcome: RouteOutcome;
+  readonly layouts: readonly {
+    readonly id: LayoutDefinition["id"];
+    readonly component: ComponentType<RouterLayoutProps>;
+    readonly error?: ComponentType<ErrorBoundaryProps>;
+    readonly invalid?: ComponentType<InvalidBoundaryProps>;
+    readonly notFound?: ComponentType<NotFoundBoundaryProps>;
+  }[];
+  readonly page: ComponentType<RouterPageProps> | undefined;
+  readonly pageBoundaries?: {
+    readonly error?: ComponentType<ErrorBoundaryProps>;
+    readonly invalid?: ComponentType<InvalidBoundaryProps>;
+  };
+}
+export class BranchLoadError extends Schema.TaggedError<BranchLoadError>()("BranchLoadError", {
+  error: Schema.Unknown,
+  branch: Schema.declare((value): value is LoadedBranch => Predicate.isObject(value)),
+}) {}
+export type BlockerState =
+  | { readonly status: "idle" }
+  | {
+      readonly status: "blocked";
+      readonly from: RouteLocation;
+      readonly to: RouteLocation;
+      readonly proceed: () => void;
+      readonly reset: () => void;
+    };
+export type NavigationState =
+  | { readonly status: "idle" }
+  | { readonly status: "loading"; readonly to: RouteLocation };
+export interface RouterSnapshot {
+  readonly location: RouteLocation | undefined;
+  readonly branch: LoadedBranch | undefined;
+  readonly navigation: NavigationState;
+  readonly failure:
+    | { readonly error: unknown; readonly retry: () => void; readonly branch?: LoadedBranch }
+    | undefined;
+  readonly commit: number;
+}
+export interface NavigationOptions {
+  readonly replace?: boolean;
+  readonly scroll?: "auto" | "preserve";
+}
+interface Transition {
+  readonly id: number;
+  readonly href: string;
+  readonly location: RouteLocation;
+  readonly kind: "initial" | "push" | "replace" | "traverse";
+  readonly completion: Deferred.Deferred<NavigationResult>;
+  readonly position: HistoryPosition;
+  readonly scroll: "auto" | "preserve";
+  readonly searchOnly: boolean;
+  readonly sourceScroll: { readonly x: number; readonly y: number };
+}
+
+const locationOf = (href: string, key: string, origin: string): RouteLocation => {
+  const parsed = new URL(href, origin);
+  let hash = parsed.hash.slice(1);
+  try {
+    hash = decodeURIComponent(hash);
+  } catch {
+    // Invalid fragments still need a readable location for the invalid-URL view.
+  }
+  return { pathname: parsed.pathname, search: parsed.search, hash, key };
+};
+
+/** One store per mount. Load caches contain code and CSS only, never component/query state. */
+export class RouterStore {
+  readonly selection: ExecutionSelection;
+  private readonly patterns;
+  private readonly listeners = new Set<() => void>();
+  private readonly modules = new Map<AppModuleId, Promise<typeof ModuleExports.Type>>();
+  private readonly styles = new Map<string, Promise<void>>();
+  private readonly styleCleanups = new Set<() => void>();
+  private readonly redirects = new Set<string>();
+  private history: RouterHistory | undefined;
+  private readonly blockers = new Set<symbol>();
+  private blocked: { transition: Transition; remaining: Set<symbol> } | undefined;
+  private upgrading = false;
+  private admission:
+    | { readonly validate: () => Promise<boolean>; readonly recoverLoad: () => Promise<void> }
+    | undefined;
+  private serial = 0;
+  private transition: Transition | undefined;
+  private committedHref: string | undefined;
+  private disposed = false;
+  private started = false;
+  private snapshot: RouterSnapshot = {
+    location: undefined,
+    branch: undefined,
+    navigation: { status: "idle" },
+    failure: undefined,
+    commit: 0,
+  };
+
+  constructor(
+    private readonly registration: ClientRegistration,
+    selection: ExecutionSelection,
+    readonly browser: Window,
+  ) {
+    this.selection = Schema.decodeSync(ExecutionSelection)(selection);
+    this.patterns = Effect.runSync(compilePatterns(registration.routes, registration.layouts));
+    for (const reference of [
+      ...registration.routes.map((route) => route.page),
+      ...registration.layouts.map((layout) => layout.module),
+    ]) {
+      if (!registration.modules.has(reference.module))
+        throw new Error(`Client module '${reference.module}' is missing from registration.`);
+    }
+  }
+
+  getSnapshot = (): RouterSnapshot => this.snapshot;
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  private update(snapshot: RouterSnapshot): void {
+    this.snapshot = snapshot;
+    for (const listener of this.listeners) listener();
+  }
+
+  start(): Promise<NavigationResult> {
+    if (this.started) throw new Error("The Ignotum router has already started.");
+    this.started = true;
+    this.history = new RouterHistory(this.browser, this.onTraversal);
+    this.browser.addEventListener("beforeunload", this.onBeforeUnload);
+    const position = this.history.committed;
+    return this.transitionTo(position.href, "initial", position.key, {}, position);
+  }
+
+  private onTraversal = (position: HistoryPosition): void => {
+    this.redirects.clear();
+    // Native traversal already changed the address. Restore the source while confirmation/code waits.
+    void this.history?.seek(this.history.committed);
+    void this.transitionTo(position.href, "traverse", position.key, {}, position);
+  };
+  back = (): void => this.history?.back();
+  forward = (): void => this.history?.forward();
+  private onBeforeUnload = (event: BeforeUnloadEvent): void => {
+    if (this.upgrading || this.blockers.size === 0) return;
+    event.preventDefault();
+    event.returnValue = "";
+  };
+  /** Internal platform upgrade entry; route confirmation never delays this reload. */
+  stopForUpgrade = (): void => {
+    if (this.disposed) return;
+    this.upgrading = true;
+    this.browser.removeEventListener("beforeunload", this.onBeforeUnload);
+    this.blockers.clear();
+    this.cancelPending();
+  };
+  upgrade = (): void => {
+    if (this.disposed) return;
+    this.stopForUpgrade();
+    this.browser.location.reload();
+  };
+  setAdmission(admission: NonNullable<RouterStore["admission"]>): void {
+    this.admission = admission;
+  }
+  setBlocker(id: symbol, when: boolean): void {
+    if (when) this.blockers.add(id);
+    else this.blockers.delete(id);
+    if (!when && this.blocked?.remaining.delete(id) === true) this.releaseBlocked();
+  }
+  getBlocker(id: symbol): BlockerState {
+    const blocked = this.blocked;
+    const from = this.snapshot.location;
+    if (blocked === undefined || from === undefined || !blocked.remaining.has(id))
+      return { status: "idle" };
+    return {
+      status: "blocked",
+      from,
+      to: blocked.transition.location,
+      proceed: () => {
+        if (this.blocked !== blocked) return;
+        blocked.remaining.delete(id);
+        this.releaseBlocked();
+      },
+      reset: () => {
+        if (this.blocked !== blocked) return;
+        this.cancelPending();
+        this.update({ ...this.snapshot, navigation: { status: "idle" } });
+      },
+    };
+  }
+  private releaseBlocked(): void {
+    const blocked = this.blocked;
+    if (blocked === undefined) return;
+    if (blocked.remaining.size === 0) {
+      this.blocked = undefined;
+      this.loadTransition(blocked.transition);
+    } else this.update({ ...this.snapshot });
+  }
+
+  navigate(
+    href: string,
+    options: NavigationOptions = {},
+    redirect = false,
+  ): Promise<NavigationResult> {
+    if (this.disposed || this.upgrading) return Promise.resolve({ status: "cancelled" });
+    if (!redirect) this.redirects.clear();
+    if (href === this.committedHref) {
+      this.cancelPending();
+      this.update({ ...this.snapshot, navigation: { status: "idle" }, failure: undefined });
+      return Promise.resolve({ status: "committed" });
+    }
+    if (redirect) {
+      if (this.committedHref !== undefined) this.redirects.add(this.committedHref);
+      if (this.redirects.has(href) || this.redirects.size >= 32) {
+        const error = new Error(`Ignotum redirect loop at '${href}'.`);
+        this.cancelPending();
+        this.update({
+          ...this.snapshot,
+          navigation: { status: "idle" },
+          failure: {
+            error,
+            retry: () => {
+              this.redirects.clear();
+              void this.navigate(href, options, true);
+            },
+          },
+        });
+        return Promise.resolve({ status: "failed", error });
+      }
+    }
+    const key =
+      options.replace === true
+        ? (this.snapshot.location?.key ?? this.browser.crypto.randomUUID())
+        : this.browser.crypto.randomUUID();
+    return this.transitionTo(href, options.replace === true ? "replace" : "push", key, options);
+  }
+
+  preload = async (href: string): Promise<void> => {
+    if (
+      this.disposed ||
+      this.upgrading ||
+      (this.admission !== undefined && !(await this.admission.validate()))
+    )
+      return;
+    const outcome = Effect.runSync(matchLocation(this.patterns, href));
+    await this.loadBranch(outcome, false);
+  };
+
+  private cancelPending(): void {
+    if (this.history !== undefined) void this.history.seek(this.history.committed);
+    this.blocked = undefined;
+    if (this.transition !== undefined)
+      Effect.runSync(Deferred.succeed(this.transition.completion, { status: "cancelled" }));
+    this.transition = undefined;
+  }
+
+  private transitionTo(
+    href: string,
+    kind: Transition["kind"],
+    key: string,
+    options: NavigationOptions = {},
+    historyPosition?: HistoryPosition,
+  ): Promise<NavigationResult> {
+    if (this.disposed || this.upgrading) return Promise.resolve({ status: "cancelled" });
+    const sourceScroll = this.history?.captureScroll() ?? {
+      x: this.browser.scrollX,
+      y: this.browser.scrollY,
+    };
+    this.cancelPending();
+    const location = locationOf(href, key, this.browser.location.origin);
+    const previous = this.snapshot.location;
+    const searchOnly =
+      previous !== undefined &&
+      previous.pathname === location.pathname &&
+      previous.hash === location.hash;
+    const completion = Deferred.makeUnsafe<NavigationResult>();
+    const position = historyPosition ?? {
+      key,
+      href,
+      index: (this.history?.committed.index ?? 0) + (kind === "push" ? 1 : 0),
+    };
+    const transition: Transition = {
+      id: ++this.serial,
+      href,
+      location,
+      kind,
+      completion,
+      position,
+      scroll: options.scroll ?? (searchOnly ? "preserve" : "auto"),
+      searchOnly,
+      sourceScroll,
+    };
+    this.transition = transition;
+    if (kind !== "initial" && this.blockers.size > 0 && this.snapshot.location !== undefined) {
+      this.blocked = { transition, remaining: new Set(this.blockers) };
+      this.update({ ...this.snapshot, navigation: { status: "idle" }, failure: undefined });
+    } else this.loadTransition(transition);
+    return Effect.runPromise(Deferred.await(completion));
+  }
+
+  private loadTransition(transition: Transition): void {
+    const { href, location, kind } = transition;
+    const outcome = Effect.runSync(matchLocation(this.patterns, href));
+    this.update({
+      ...this.snapshot,
+      navigation: { status: "loading", to: location },
+      failure: undefined,
+    });
+    const load = async () => {
+      if (this.admission !== undefined && !(await this.admission.validate()))
+        throw new Error("The app must verify its current selection before navigating.");
+      if (this.upgrading || this.disposed) throw new Error("The app is updating.");
+      return this.loadBranch(outcome);
+    };
+    void load().then(
+      async (branch) => {
+        if (this.transition !== transition || this.disposed) return;
+        try {
+          const history = this.history;
+          if (history !== undefined) {
+            const restored = await history.seek(history.committed);
+            if (!restored || this.transition !== transition || this.disposed) return;
+            if (kind === "traverse") {
+              const arrived = await history.seek(transition.position);
+              if (!arrived || this.transition !== transition || this.disposed) return;
+            }
+            history.commit(transition.position, kind);
+          }
+          this.applyMetadata(outcome);
+          this.committedHref = href;
+          this.update({
+            location,
+            branch,
+            navigation: { status: "idle" },
+            failure: undefined,
+            commit: transition.id,
+          });
+        } catch (error) {
+          this.fail(transition, error);
+        }
+      },
+      (error) => {
+        this.fail(transition, error);
+        if (!this.upgrading) void this.admission?.recoverLoad();
+      },
+    );
+  }
+
+  /** Called by the mounted view after Preact has committed the destination DOM. */
+  rendered(commit: number): void {
+    if (this.transition?.id !== commit || this.snapshot.commit !== commit) {
+      if (this.snapshot.navigation.status === "idle" && this.blocked === undefined)
+        this.history?.restoreSourceScroll();
+      return;
+    }
+    const transition = this.transition;
+    const document = this.browser.document;
+    if (!transition.searchOnly) {
+      const target =
+        document.querySelector<HTMLElement>("#app main, #app [role=main]") ??
+        document.getElementById("app");
+      if (target !== null) {
+        const hadTabIndex = target.hasAttribute("tabindex");
+        if (!hadTabIndex) target.setAttribute("tabindex", "-1");
+        target.focus({ preventScroll: true });
+      }
+    }
+    const saved = this.history?.scroll.get(transition.location.key);
+    if (transition.kind === "traverse" && saved !== undefined)
+      this.browser.scrollTo(saved.x, saved.y);
+    else if (transition.scroll === "auto") {
+      const target =
+        transition.location.hash === "" ? null : document.getElementById(transition.location.hash);
+      if (target !== null) target.scrollIntoView();
+      else this.browser.scrollTo(0, 0);
+    } else this.browser.scrollTo(transition.sourceScroll.x, transition.sourceScroll.y);
+    this.history?.finishScroll();
+    Effect.runSync(Deferred.succeed(this.transition.completion, { status: "committed" }));
+    this.transition = undefined;
+  }
+
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Module loaders and DOM APIs can throw arbitrary values; NavigationResult preserves the original error.
+  private fail(transition: Transition, error: unknown): void {
+    if (this.transition !== transition || this.disposed) return;
+    this.transition = undefined;
+    const loadFailure = error instanceof BranchLoadError ? error : undefined;
+    const originalError = loadFailure === undefined ? error : loadFailure.error;
+    this.update({
+      ...this.snapshot,
+      navigation: { status: "idle" },
+      failure: {
+        error: originalError,
+        branch: transition.kind === "initial" ? undefined : loadFailure?.branch,
+        retry: () => {
+          void this.transitionTo(
+            transition.href,
+            transition.kind,
+            transition.location.key,
+            { scroll: transition.scroll },
+            transition.position,
+          );
+        },
+      },
+    });
+    Effect.runSync(
+      Deferred.succeed(transition.completion, { status: "failed", error: originalError }),
+    );
+  }
+
+  private loadStyle(href: string): Promise<void> {
+    const absolute = new URL(href, this.browser.location.origin).href;
+    const cached = this.styles.get(absolute);
+    if (cached !== undefined) return cached;
+    const document = this.browser.document;
+    const existing = Array.from(
+      document.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]'),
+    ).find((link) => link.href === absolute);
+    if (existing?.sheet !== null && existing?.sheet !== undefined) return Promise.resolve();
+    const link = existing ?? document.createElement("link");
+    const promise = Effect.runPromise(
+      Effect.callback<void, Error>((resume) => {
+        const cleanup = () => {
+          link.removeEventListener("load", onLoad);
+          link.removeEventListener("error", onError);
+          this.styleCleanups.delete(cancel);
+        };
+        const onLoad = () => {
+          cleanup();
+          resume(Effect.void);
+        };
+        const onError = () => {
+          cleanup();
+          link.remove();
+          resume(Effect.fail(new Error(`Could not load route stylesheet '${href}'.`)));
+        };
+        const cancel = () => {
+          cleanup();
+          if (existing === undefined) link.remove();
+          resume(Effect.fail(new Error("Router disposed.")));
+        };
+        this.styleCleanups.add(cancel);
+        link.addEventListener("load", onLoad);
+        link.addEventListener("error", onError);
+        if (existing === undefined) {
+          link.rel = "stylesheet";
+          link.crossOrigin = "anonymous";
+          link.href = absolute;
+          document.head.append(link);
+        }
+        return Effect.sync(cleanup);
+      }),
+    ).catch((error) => {
+      this.styles.delete(absolute);
+      throw error;
+    });
+    this.styles.set(absolute, promise);
+    return promise;
+  }
+
+  private loadModule(id: AppModuleId): Promise<typeof ModuleExports.Type> {
+    const cached = this.modules.get(id);
+    if (cached !== undefined) return cached;
+    const module = this.registration.modules.get(id);
+    if (module === undefined)
+      return Promise.reject(new Error(`Client module '${id}' is not registered.`));
+    const loaded = Promise.resolve()
+      .then(module.load)
+      .then(Schema.decodeUnknownSync(ModuleExports))
+      .catch((error) => {
+        this.modules.delete(id);
+        throw error;
+      });
+    this.modules.set(id, loaded);
+    return loaded;
+  }
+  private async loadExport(reference: ModuleExportReference): Promise<typeof Schema.Unknown.Type> {
+    const exports = await this.loadModule(reference.module);
+    if (!Object.hasOwn(exports, reference.exportName))
+      throw new Error(`Module '${reference.module}' has no '${reference.exportName}' export.`);
+    return exports[reference.exportName];
+  }
+  private async loadBranch(outcome: RouteOutcome, withStyles = true): Promise<LoadedBranch> {
+    const route = outcome._tag === "NotFound" ? undefined : outcome.route;
+    const available = new Map<LayoutDefinition["id"], LoadedBranch["layouts"][number]>();
+    try {
+      const [layouts, page] = await Promise.all([
+        Promise.all(
+          outcome.layouts.map(async (layout) => {
+            const [loaded] = await Promise.all([
+              this.loadExport(layout.module).then(Schema.decodeUnknownSync(LayoutModule)),
+              withStyles
+                ? Promise.all(
+                    (this.registration.modules.get(layout.module.module)?.styles ?? []).map(
+                      (href) => this.loadStyle(href),
+                    ),
+                  )
+                : undefined,
+            ]);
+            const result = { id: layout.id, ...loaded };
+            available.set(layout.id, result);
+            return result;
+          }),
+        ),
+        route === undefined
+          ? undefined
+          : this.loadExport(route.page).then(Schema.decodeUnknownSync(PageModule)),
+        Promise.all(
+          withStyles
+            ? [
+                ...(this.registration.styles ?? []),
+                ...(route === undefined
+                  ? []
+                  : (this.registration.modules.get(route.page.module)?.styles ?? [])),
+              ].map(async (href) => this.loadStyle(href))
+            : [],
+        ),
+      ]);
+      return { outcome, layouts, page: page?.component, pageBoundaries: page };
+    } catch (error) {
+      const layouts: Array<LoadedBranch["layouts"][number]> = [];
+      for (const definition of outcome.layouts) {
+        const loaded = available.get(definition.id);
+        if (loaded === undefined) break;
+        layouts.push(loaded);
+      }
+      throw BranchLoadError.make({ error, branch: { outcome, layouts, page: undefined } });
+    }
+  }
+
+  setRenderError(error: boolean): void {
+    if (this.snapshot.branch !== undefined) this.applyMetadata(this.snapshot.branch.outcome, error);
+  }
+
+  private applyMetadata(outcome: RouteOutcome, renderError = false): void {
+    const resolved = Effect.runSync(
+      resolveMetadata({
+        applicationName: this.registration.applicationName,
+        layouts: outcome.layouts.map((layout) => layout.metadata),
+        page: outcome._tag === "NotFound" ? undefined : outcome.route?.metadata,
+        outcome: renderError ? "Invalid" : outcome._tag,
+      }),
+    );
+    const document = this.browser.document;
+    document.title = resolved.title;
+    for (const name of ["description", "robots"] as const) {
+      const tags = Array.from(
+        document.head.querySelectorAll<HTMLMetaElement>(`meta[name="${name}"]`),
+      );
+      const value = resolved.meta[name];
+      if (value === undefined) {
+        for (const tag of tags) tag.remove();
+        continue;
+      }
+      const tag = tags.shift() ?? document.createElement("meta");
+      for (const duplicate of tags) duplicate.remove();
+      tag.name = name;
+      tag.content = value;
+      if (!tag.isConnected) document.head.append(tag);
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.cancelPending();
+    this.history?.dispose();
+    this.browser.removeEventListener("beforeunload", this.onBeforeUnload);
+    for (const cleanup of this.styleCleanups) cleanup();
+    this.listeners.clear();
+  }
+}