@multiplatform.one/router 6.1.0 → 6.3.0

package/src/seam/oneAdapter.tsx

@@ -0,0 +1,166 @@
+// DOM one-shim — One's router API backed by the stack-navigation seam.
+//
+// Alias the `one` package to THIS module in a DOM target's vite config
+// (VS Code webview, webext views) and every consumer — feature screens,
+// @package/layouts, the @multiplatform.one/router facade (whose default
+// implementation re-exports from `one`) — rides the seam instead of One's
+// real router runtime, which needs an address bar + One server runtime
+// those hosts don't have. The GTK equivalent lives in
+// apps/one/gnome/shims/one.ts (it renders Link over a GTK pressable and
+// carries GJS probe instrumentation this DOM shim doesn't need).
+//
+// Exports beyond the router hooks exist to satisfy module resolution for
+// everything the shared graph imports from `one`:
+//   - useUserScheme & friends re-export from @vxrn/color-scheme — One's
+//     own implementation IS that package, and it's browser-safe
+//     (localStorage + matchMedia).
+//   - LoadProgressBar/useMatches/Slot are inert placeholders: webview
+//     entries never mount One's root layout, but the barrels that reach
+//     them must still resolve.
+
+import type { AnchorHTMLAttributes, MouseEvent, ReactNode } from "react";
+import { useContext, useSyncExternalStore } from "react";
+import {
+  RouteTagContext,
+  hrefToString,
+  stackNavigator,
+  useNavState,
+  useRouteParams,
+  type Href,
+  type NavParams,
+} from "./navigator";
+
+export {
+  getUserScheme,
+  onUserSchemeChange,
+  setUserScheme,
+  useUserScheme,
+} from "@vxrn/color-scheme";
+
+/** Loose stand-in for One's LoaderProps — loaders run through the seam's
+ *  loader bridge on these targets, with the same shape One passes. */
+export type LoaderProps<Params = Record<string, string | string[] | undefined>> = {
+  params: Params;
+  request?: Request;
+};
+
+export function useLoader<T>(_loader: (...args: never[]) => unknown): T | undefined {
+  const tag = useContext(RouteTagContext);
+  const fromRoute = useSyncExternalStore(stackNavigator.subscribe, () =>
+    stackNavigator.loaderSnapshot(tag),
+  );
+  return fromRoute as T | undefined;
+}
+
+// One's router object is referentially stable — consumers keep it in
+// useCallback/useEffect dep arrays, so this shim's must be too. The surface
+// matches the @multiplatform.one/router facade's Router contract (One's
+// real router is a superset of it).
+const ROUTER = {
+  push: stackNavigator.push,
+  navigate: stackNavigator.push,
+  replace: stackNavigator.replace,
+  back: stackNavigator.back,
+  canGoBack: () => stackNavigator.getSnapshot().canGoBack,
+  dismiss: (count?: number) => {
+    for (let i = 0; i < (count ?? 1); i++) stackNavigator.back();
+  },
+  dismissAll: () => {
+    const depth = stackNavigator.getSnapshot().depth;
+    for (let i = 1; i < depth; i++) stackNavigator.back();
+  },
+  canDismiss: () => stackNavigator.getSnapshot().canGoBack,
+  setParams: stackNavigator.setParams,
+  subscribe: (listener: (state: "success" | "error") => void) => {
+    listener("success");
+    return () => {};
+  },
+  onLoadState: (listener: (state: "loading" | "loaded") => void) => {
+    listener("loaded");
+    return () => {};
+  },
+};
+
+export function useRouter(): typeof ROUTER {
+  return ROUTER;
+}
+
+export interface LinkProps extends Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  "href" | "onClick"
+> {
+  href?: Href;
+  replace?: boolean;
+  children?: ReactNode;
+}
+
+/** Navigation Link: an anchor that pushes `href` through the seam.
+ *  Degrades to rendering children in place when no route manifest is
+ *  configured (single-screen entries — no route stack exists there). */
+export function Link({ href, replace, children, style, ...rest }: LinkProps): ReactNode {
+  if (!href || !stackNavigator.isConfigured) return children ?? null;
+  const hrefString = hrefToString(href);
+  const onClick = (event: MouseEvent<HTMLAnchorElement>) => {
+    event.preventDefault();
+    if (replace) stackNavigator.replace(href);
+    else stackNavigator.push(href);
+  };
+  return (
+    <a
+      href={hrefString}
+      onClick={onClick}
+      // display:contents — the anchor contributes no box, so wrapping
+      // arbitrary flex/grid children never disturbs layout (clicks still
+      // bubble through it).
+      style={{ display: "contents", color: "inherit", textDecoration: "none", ...style }}
+      data-seam-link={hrefString}
+      {...rest}
+    >
+      {children}
+    </a>
+  );
+}
+
+/** One's <Slot /> renders the active child route inside a layout. The seam
+ *  has no nested-layout mounting — every route is its own host page — so
+ *  layouts that render <Slot /> contribute chrome only; the child screen is
+ *  mounted by the navigation host instead. Renders nothing by design. */
+export function Slot(_props: Record<string, unknown>): null {
+  return null;
+}
+
+export function useParams(): NavParams {
+  return useRouteParams();
+}
+
+export function useLocalSearchParams(): NavParams {
+  return useRouteParams();
+}
+
+export function usePathname(): string {
+  return useNavState().pathname;
+}
+
+/** One's history-nav guard. The seam's hosts have no browser history to
+ *  block (in-app navigation confirms dirty transitions itself), so this is
+ *  a no-op that always reports "unblocked". Shape matches one/react-router's
+ *  useBlocker return. */
+export function useBlocker(_shouldBlock?: unknown): {
+  state: "unblocked" | "blocked" | "proceeding";
+  proceed: () => void;
+  reset: () => void;
+} {
+  return { state: "unblocked", proceed: () => {}, reset: () => {} };
+}
+
+/** Inert stand-in for One's route-transition progress bar (SSR-era chrome
+ *  with no meaning on a stack host). */
+export function LoadProgressBar(_props: Record<string, unknown>): null {
+  return null;
+}
+
+/** One's useMatches returns the matched route chain; the seam mounts one
+ *  page at a time, so consumers get an empty chain. */
+export function useMatches(): unknown[] {
+  return [];
+}

package/types/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useSearchParams, useUrlState, useShareableUrl, useTypedSearchParams, type SearchParams, type SetSearchParamsOptions, } from "./useUrlState";
+//# sourceMappingURL=index.d.ts.map

package/types/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,WAAW,EACX,eAAe,EACf,oBAAoB,EACpB,KAAK,YAAY,EACjB,KAAK,sBAAsB,GAC5B,MAAM,eAAe,CAAC"}

package/types/hooks/useUrlState.d.ts

@@ -0,0 +1,36 @@
+export type SearchParams = Record<string, string | string[] | undefined>;
+export interface SetSearchParamsOptions {
+    replace?: boolean;
+    debounceMs?: number;
+}
+/**
+ * Cross-platform hook for managing URL search parameters
+ * Works with both React Router (web) and React Navigation (native)
+ */
+export declare function useSearchParams(): [
+    SearchParams,
+    (params: SearchParams | ((prev: SearchParams) => SearchParams), options?: SetSearchParamsOptions) => void
+];
+/**
+ * Hook for syncing form state with URL parameters
+ * Provides automatic serialization/deserialization and debouncing
+ */
+export declare function useUrlState<T extends Record<string, any>>(defaultValues: T, options?: {
+    debounceMs?: number;
+    serialize?: (value: T) => SearchParams;
+    deserialize?: (params: SearchParams) => T;
+}): [T, (newState: Partial<T> | ((prev: T) => Partial<T>)) => void];
+/**
+ * Hook for creating shareable URLs with current state
+ */
+export declare function useShareableUrl(): string;
+/**
+ * Hook for parsing URL parameters with type safety
+ */
+export declare function useTypedSearchParams<T extends Record<string, any>>(schema: {
+    [K in keyof T]: {
+        default: T[K];
+        parse?: (value: string | string[] | undefined) => T[K];
+    };
+}): T;
+//# sourceMappingURL=useUrlState.d.ts.map

package/types/hooks/useUrlState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUrlState.d.ts","sourceRoot":"","sources":["../../src/hooks/useUrlState.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAEzE,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAuBD;;;GAGG;AACH,wBAAgB,eAAe,IAAI;IACjC,YAAY;IACZ,CACE,MAAM,EAAE,YAAY,GAAG,CAAC,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY,CAAC,EAC7D,OAAO,CAAC,EAAE,sBAAsB,KAC7B,IAAI;CACV,CAiEA;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACvD,aAAa,EAAE,CAAC,EAChB,OAAO,GAAE;IACP,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,YAAY,CAAC;IACvC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,CAAC,CAAC;CACtC,GACL,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CA0EjE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAyBxC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE;KACzE,CAAC,IAAI,MAAM,CAAC,GAAG;QACd,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACd,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;KACxD;CACF,GAAG,CAAC,CAsBJ"}

package/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./router/index";
+export * from "./types";
+export * from "./hooks";
+//# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}

package/types/index.storybook.d.ts

@@ -0,0 +1,4 @@
+export { useRouter, usePathname, useParams, Link } from "./router/EmptyRouter";
+export * from "./types";
+export * from "./hooks";
+//# sourceMappingURL=index.storybook.d.ts.map

package/types/index.storybook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.storybook.d.ts","sourceRoot":"","sources":["../src/index.storybook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC/E,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}

package/types/router/EmptyRouter.d.ts

@@ -0,0 +1,7 @@
+import type { LinkComponent, Router } from "../types";
+export declare const useRouter: () => Router;
+export declare const usePathname: () => string;
+export declare const useParams: () => {};
+export declare const Link: LinkComponent;
+export declare function useUrlState<T extends Record<string, any>>(defaultValues: T): [T, (newState: Partial<T> | ((prev: T) => Partial<T>)) => void];
+//# sourceMappingURL=EmptyRouter.d.ts.map

package/types/router/EmptyRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmptyRouter.d.ts","sourceRoot":"","sources":["../../src/router/EmptyRouter.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,aAAa,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAI5D,eAAO,MAAM,SAAS,QAAO,MAoB5B,CAAC;AAEF,eAAO,MAAM,WAAW,QAAO,MAAa,CAAC;AAE7C,eAAO,MAAM,SAAS,UAAa,CAAC;AAEpC,eAAO,MAAM,IAAI,EAAE,aAUlB,CAAC;AAIF,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACvD,aAAa,EAAE,CAAC,GACf,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAGjE"}

package/types/router/ReactRouter.d.ts

@@ -0,0 +1,6 @@
+import type { LinkComponent, Router } from "../types";
+export declare const useRouter: () => Router;
+export declare const usePathname: () => string;
+export declare const useParams: () => Record<string, string | string[] | undefined>;
+export declare const Link: LinkComponent;
+//# sourceMappingURL=ReactRouter.d.ts.map

package/types/router/ReactRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactRouter.d.ts","sourceRoot":"","sources":["../../src/router/ReactRouter.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAIV,aAAa,EACb,MAAM,EACP,MAAM,UAAU,CAAC;AAElB,eAAO,MAAM,SAAS,QAAO,MAoC5B,CAAC;AAEF,eAAO,MAAM,WAAW,QAAO,MAAgC,CAAC;AAGhE,eAAO,MAAM,SAAS,qDAwBrB,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,aAIlB,CAAC"}

package/types/router/index.d.ts

@@ -0,0 +1,2 @@
+export { Link, useParams, usePathname, useRouter } from "one";
+//# sourceMappingURL=index.d.ts.map

package/types/router/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC"}

package/types/router/index.storybook-expo.d.ts

@@ -0,0 +1,2 @@
+export * from "./EmptyRouter";
+//# sourceMappingURL=index.storybook-expo.d.ts.map

package/types/router/index.storybook-expo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.storybook-expo.d.ts","sourceRoot":"","sources":["../../src/router/index.storybook-expo.tsx"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}

package/types/router/index.storybook.d.ts

@@ -0,0 +1,2 @@
+export * from "./EmptyRouter";
+//# sourceMappingURL=index.storybook.d.ts.map

package/types/router/index.storybook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.storybook.d.ts","sourceRoot":"","sources":["../../src/router/index.storybook.tsx"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}

package/types/router/index.webext.d.ts

@@ -0,0 +1,2 @@
+export * from "./ReactRouter";
+//# sourceMappingURL=index.webext.d.ts.map

package/types/router/index.webext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.webext.d.ts","sourceRoot":"","sources":["../../src/router/index.webext.tsx"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}

package/types/seam/DomNavigationHost.d.ts

@@ -0,0 +1,33 @@
+import type { CSSProperties, ReactNode } from "react";
+import { type Href, type NavStackAdapter, type RouteDef } from "./navigator";
+/** In-memory implementation of the host-stack protocol (the seam's
+ *  NavStackAdapter mirrors Adw.NavigationView's method surface — see
+ *  navigator.ts). */
+export declare class DomStackAdapter implements NavStackAdapter {
+    private stack;
+    private readonly onChanged;
+    constructor(rootTag: string, onChanged: () => void);
+    push_by_tag(tag: string): void;
+    pop(): boolean;
+    pop_to_tag(tag: string): boolean;
+    replace_with_tags(tags: string[]): void;
+    get_navigation_stack(): {
+        get_n_items(): number;
+        get_item(index: number): {
+            get_tag(): string | null;
+        } | null;
+    };
+}
+export interface DomRouteEntry extends RouteDef {
+    element: ReactNode;
+}
+export interface DomNavigationHostProps {
+    routes: DomRouteEntry[];
+    /** Restore a previous route on mount (e.g. from vscode.getState()) —
+     *  applied as a root replace, matching MemoryRouter initialEntries
+     *  semantics (no back stack to it). */
+    initialHref?: Href;
+    style?: CSSProperties;
+}
+export declare function DomNavigationHost({ routes, initialHref, style, }: DomNavigationHostProps): ReactNode;
+//# sourceMappingURL=DomNavigationHost.d.ts.map

package/types/seam/DomNavigationHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DomNavigationHost.d.ts","sourceRoot":"","sources":["../../src/seam/DomNavigationHost.tsx"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEtD,OAAO,EAIL,KAAK,IAAI,EACT,KAAK,eAAe,EACpB,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AAErB;;qBAEqB;AACrB,qBAAa,eAAgB,YAAW,eAAe;IACrD,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;gBAE3B,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI;IAKlD,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK9B,GAAG,IAAI,OAAO;IAOd,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQhC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAKvC,oBAAoB,IAAI;QACtB,WAAW,IAAI,MAAM,CAAC;QACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG;YAAE,OAAO,IAAI,MAAM,GAAG,IAAI,CAAA;SAAE,GAAG,IAAI,CAAC;KAC9D;CAQF;AAED,MAAM,WAAW,aAAc,SAAQ,QAAQ;IAC7C,OAAO,EAAE,SAAS,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB;;2CAEuC;IACvC,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAUD,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,WAAW,EACX,KAAK,GACN,EAAE,sBAAsB,GAAG,SAAS,CAwCpC"}

package/types/seam/index.d.ts

@@ -0,0 +1,7 @@
+export { RouteTagContext, StackNavigator, hrefToString, stackNavigator, useNavState, useRouteParams, } from "./navigator";
+export type { Href, NavParams, NavSnapshot, NavStackAdapter, RouteDef, RouteLoader, RouteLoaderProps, } from "./navigator";
+export { DomNavigationHost, DomStackAdapter } from "./DomNavigationHost";
+export type { DomNavigationHostProps, DomRouteEntry } from "./DomNavigationHost";
+export { Link, LoadProgressBar, Slot, useBlocker, useLoader, useLocalSearchParams, useMatches, useParams, usePathname, useRouter, } from "./oneAdapter";
+export type { LinkProps, LoaderProps } from "./oneAdapter";
+//# sourceMappingURL=index.d.ts.map

package/types/seam/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/seam/index.ts"],"names":[],"mappings":"AASA,OAAO,EACL,eAAe,EACf,cAAc,EACd,YAAY,EACZ,cAAc,EACd,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,IAAI,EACJ,SAAS,EACT,WAAW,EACX,eAAe,EACf,QAAQ,EACR,WAAW,EACX,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,YAAY,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EACL,IAAI,EACJ,eAAe,EACf,IAAI,EACJ,UAAU,EACV,SAAS,EACT,oBAAoB,EACpB,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/types/seam/navigator.d.ts

@@ -0,0 +1,133 @@
+export type NavParams = Record<string, string | string[] | undefined>;
+export interface RouteLoaderProps {
+    /** Resolved pathname, e.g. "/pokemon/bulbasaur". */
+    path: string;
+    /** Route params (dynamic segments + query). */
+    params: NavParams;
+}
+/** One-style route loader. On web, One resolves a route's loader before the
+ *  client navigation completes; the seam mirrors that contract — see
+ *  StackNavigator.navigate(). */
+export type RouteLoader = (props: RouteLoaderProps) => unknown | Promise<unknown>;
+export interface RouteDef {
+    /** One-style pattern: "/", "/pokemon", "/pokemon/[id]". */
+    pattern: string;
+    /** Host page tag AND stable route id. */
+    tag: string;
+    /** Page title (host chrome, e.g. the GTK header bar). */
+    title: string;
+    /** Optional data loader — resolved BEFORE the page mounts/shows (the
+     *  loader bridge). Its result is what `useLoader` returns on this
+     *  route's page. */
+    loader?: RouteLoader;
+}
+export type Href = string | {
+    pathname: string;
+    params?: Record<string, string | number>;
+};
+interface CompiledRoute extends RouteDef {
+    segments: {
+        literal?: string;
+        param?: string;
+    }[];
+}
+export interface NavSnapshot {
+    pathname: string;
+    tag: string;
+    depth: number;
+    canGoBack: boolean;
+    generation: number;
+}
+/** Structural view of the host navigation stack — everything the seam
+ *  calls. The method names deliberately mirror Adw.NavigationView so the
+ *  GTK target passes its widget straight through; DOM hosts implement the
+ *  same protocol over an array (see DomNavigationHost). */
+export interface NavStackAdapter {
+    push_by_tag(tag: string): void;
+    pop(): boolean;
+    pop_to_tag(tag: string): boolean;
+    replace_with_tags(tags: string[]): void;
+    get_navigation_stack(): {
+        get_n_items(): number;
+        get_item(index: number): {
+            get_tag(): string | null;
+        } | null;
+    };
+}
+export declare function hrefToString(href: Href): string;
+export declare class StackNavigator {
+    private routes;
+    private host;
+    private listeners;
+    /** Stack mirror rebuilt from the host on every pushed/popped/replaced
+     *  signal. */
+    private stackTags;
+    private paramsByTag;
+    private pathnameByTag;
+    /** Tags whose page content has been navigated to at least once. The host
+     *  gates each page's React content on this (lazy mounting) — a tag enters
+     *  the set right before its first host push and never leaves (backgrounded
+     *  pages stay alive, same as One keeping stack screens mounted). */
+    private visitedTags;
+    /** Route-loader results, per tag (the loader bridge's store). */
+    private loaderDataByTag;
+    /** Monotonic navigation sequence — a loader that resolves after a NEWER
+     *  navigation started must not perform its (stale) host action. */
+    private navSeq;
+    private generation;
+    private snapshot;
+    get isConfigured(): boolean;
+    /** Register the route manifest. The FIRST route is the root page. */
+    configure(defs: RouteDef[]): void;
+    /** Has this route's page been navigated to (⇒ its content may mount)? */
+    isVisited(tag: string | null): boolean;
+    /** The route's last loader result (stable identity until the loader runs
+     *  again). undefined when the route has no loader / hasn't resolved. */
+    loaderSnapshot(tag: string | null): unknown;
+    /** Resolve a route's loader WITHOUT navigating. For the initial page:
+     *  entries can `await stackNavigator.preload("/")` during top-level await
+     *  (where GJS reliably drains promise jobs) so even the root page's first
+     *  paint has loader data. */
+    preload(href: Href): Promise<void>;
+    /** Bind the live host stack (an Adw.NavigationView widget on GTK, a
+     *  DomStackAdapter on DOM targets). */
+    attach(host: NavStackAdapter): void;
+    detach(): void;
+    subscribe: (fn: () => void) => (() => void);
+    getSnapshot: () => NavSnapshot;
+    paramsSnapshot(tag: string | null): NavParams;
+    match(href: Href): {
+        route: CompiledRoute;
+        pathname: string;
+        params: NavParams;
+    } | null;
+    push: (href: Href) => void;
+    replace: (href: Href) => void;
+    /** Shared push/replace flow, incl. the loader bridge. When the target
+     *  route has no loader the whole body runs SYNCHRONOUSLY (an async
+     *  function only yields at its first await), preserving the original
+     *  timing. With a loader, the host action waits for the loader to resolve
+     *  — same contract as One on web, where client navigation completes only
+     *  after the route's loader data arrived — so the page's first paint has
+     *  its data (and the lazily-mounted content mounts with it). */
+    private navigate;
+    back: () => void;
+    setParams: (params: Record<string, string>) => void;
+    /** Re-read the host navigation stack (called from pushed/popped/replaced
+     *  signal handlers and attach). The host is the source of truth. */
+    syncFromHost: () => void;
+    private setRouteState;
+    private rebuildSnapshot;
+}
+/** The per-bundle navigator singleton. Every target build (GNOME entry,
+ *  VS Code webview, webext view) is its own bundle, so module state is
+ *  naturally per-target. */
+export declare const stackNavigator: StackNavigator;
+/** Set per page by the navigation host — useParams/useLocalSearchParams
+ *  read the params of the page they render INSIDE, not the top of the
+ *  stack. */
+export declare const RouteTagContext: import("react").Context<string | null>;
+export declare function useNavState(): NavSnapshot;
+export declare function useRouteParams(): NavParams;
+export {};
+//# sourceMappingURL=navigator.d.ts.map

package/types/seam/navigator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigator.d.ts","sourceRoot":"","sources":["../../src/seam/navigator.ts"],"names":[],"mappings":"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"}

package/types/seam/oneAdapter.d.ts

@@ -0,0 +1,57 @@
+import type { AnchorHTMLAttributes, ReactNode } from "react";
+import { type Href, type NavParams } from "./navigator";
+export { getUserScheme, onUserSchemeChange, setUserScheme, useUserScheme, } from "@vxrn/color-scheme";
+/** Loose stand-in for One's LoaderProps — loaders run through the seam's
+ *  loader bridge on these targets, with the same shape One passes. */
+export type LoaderProps<Params = Record<string, string | string[] | undefined>> = {
+    params: Params;
+    request?: Request;
+};
+export declare function useLoader<T>(_loader: (...args: never[]) => unknown): T | undefined;
+declare const ROUTER: {
+    push: (href: Href) => void;
+    navigate: (href: Href) => void;
+    replace: (href: Href) => void;
+    back: () => void;
+    canGoBack: () => boolean;
+    dismiss: (count?: number) => void;
+    dismissAll: () => void;
+    canDismiss: () => boolean;
+    setParams: (params: Record<string, string>) => void;
+    subscribe: (listener: (state: "success" | "error") => void) => () => void;
+    onLoadState: (listener: (state: "loading" | "loaded") => void) => () => void;
+};
+export declare function useRouter(): typeof ROUTER;
+export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "onClick"> {
+    href?: Href;
+    replace?: boolean;
+    children?: ReactNode;
+}
+/** Navigation Link: an anchor that pushes `href` through the seam.
+ *  Degrades to rendering children in place when no route manifest is
+ *  configured (single-screen entries — no route stack exists there). */
+export declare function Link({ href, replace, children, style, ...rest }: LinkProps): ReactNode;
+/** One's <Slot /> renders the active child route inside a layout. The seam
+ *  has no nested-layout mounting — every route is its own host page — so
+ *  layouts that render <Slot /> contribute chrome only; the child screen is
+ *  mounted by the navigation host instead. Renders nothing by design. */
+export declare function Slot(_props: Record<string, unknown>): null;
+export declare function useParams(): NavParams;
+export declare function useLocalSearchParams(): NavParams;
+export declare function usePathname(): string;
+/** One's history-nav guard. The seam's hosts have no browser history to
+ *  block (in-app navigation confirms dirty transitions itself), so this is
+ *  a no-op that always reports "unblocked". Shape matches one/react-router's
+ *  useBlocker return. */
+export declare function useBlocker(_shouldBlock?: unknown): {
+    state: "unblocked" | "blocked" | "proceeding";
+    proceed: () => void;
+    reset: () => void;
+};
+/** Inert stand-in for One's route-transition progress bar (SSR-era chrome
+ *  with no meaning on a stack host). */
+export declare function LoadProgressBar(_props: Record<string, unknown>): null;
+/** One's useMatches returns the matched route chain; the seam mounts one
+ *  page at a time, so consumers get an empty chain. */
+export declare function useMatches(): unknown[];
+//# sourceMappingURL=oneAdapter.d.ts.map

package/types/seam/oneAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oneAdapter.d.ts","sourceRoot":"","sources":["../../src/seam/oneAdapter.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,oBAAoB,EAAc,SAAS,EAAE,MAAM,OAAO,CAAC;AAEzE,OAAO,EAML,KAAK,IAAI,EACT,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,aAAa,GACd,MAAM,oBAAoB,CAAC;AAE5B;sEACsE;AACtE,MAAM,MAAM,WAAW,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GAAG,CAAC,GAAG,SAAS,CAMlF;AAMD,QAAA,MAAM,MAAM;;;;;;sBAMQ,MAAM;;;;0BASF,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,KAAK,IAAI;4BAIlC,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,KAAK,IAAI;CAI9D,CAAC;AAEF,wBAAgB,SAAS,IAAI,OAAO,MAAM,CAEzC;AAED,MAAM,WAAW,SAAU,SAAQ,IAAI,CACrC,oBAAoB,CAAC,iBAAiB,CAAC,EACvC,MAAM,GAAG,SAAS,CACnB;IACC,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;wEAEwE;AACxE,wBAAgB,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE,SAAS,GAAG,SAAS,CAsBtF;AAED;;;yEAGyE;AACzE,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE1D;AAED,wBAAgB,SAAS,IAAI,SAAS,CAErC;AAED,wBAAgB,oBAAoB,IAAI,SAAS,CAEhD;AAED,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;;yBAGyB;AACzB,wBAAgB,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG;IAClD,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,YAAY,CAAC;IAC9C,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAEA;AAED;wCACwC;AACxC,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAErE;AAED;uDACuD;AACvD,wBAAgB,UAAU,IAAI,OAAO,EAAE,CAEtC"}

package/types/types.d.ts

@@ -0,0 +1,40 @@
+import type { OneRouter } from "one";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+export type Href = OneRouter.Href<{
+    __branded__: any;
+}>;
+export type LoadingState = "loading" | "loaded" | "error";
+export type ResultState = "success" | "error";
+export type RootStateListener = (state: ResultState) => void;
+export type LoadingStateListener = (state: LoadingState) => void;
+export type InputRouteParamsBlank = OneRouter.InputRouteParamsBlank;
+export type InputRouteParams<T extends string> = OneRouter.InputRouteParams<T>;
+export interface Router {
+    back: () => void;
+    canGoBack: () => boolean;
+    push: (href: Href) => void;
+    navigate: (href: Href) => void;
+    replace: (href: Href) => void;
+    dismiss: (count?: number) => void;
+    dismissAll: () => void;
+    canDismiss: () => boolean;
+    setParams: <T extends string = "">(params?: T extends "" ? InputRouteParamsBlank : InputRouteParams<T>) => void;
+    subscribe: (listener: RootStateListener) => () => void;
+    onLoadState: (listener: LoadingStateListener) => () => void;
+}
+export type UseRouter = () => Router;
+export type UsePathname = () => string;
+export type UseParams = () => Record<string, string | string[] | undefined>;
+export interface LinkProps {
+    href: Href;
+    replace?: boolean;
+    children?: ReactNode;
+    style?: CSSProperties;
+    className?: string;
+    [key: string]: any;
+}
+export interface LinkComponent {
+    (props: LinkProps): ReactElement;
+    resolveHref: (href: Href) => string;
+}
+//# sourceMappingURL=types.d.ts.map

package/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEpE,MAAM,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;IAAE,WAAW,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AACxD,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC1D,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAC9C,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;AAC7D,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AAEjE,MAAM,MAAM,qBAAqB,GAAG,SAAS,CAAC,qBAAqB,CAAC;AACpE,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,IAAI,SAAS,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;AAE/E,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAC3B,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAC/B,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAC9B,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,SAAS,EAAE,CAAC,CAAC,SAAS,MAAM,GAAG,EAAE,EAC/B,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,qBAAqB,GAAG,gBAAgB,CAAC,CAAC,CAAC,KAChE,IAAI,CAAC;IACV,SAAS,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,MAAM,IAAI,CAAC;IACvD,WAAW,EAAE,CAAC,QAAQ,EAAE,oBAAoB,KAAK,MAAM,IAAI,CAAC;CAC7D;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC;AACrC,MAAM,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC;AACvC,MAAM,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAE5E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CAAC;IACjC,WAAW,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC;CACrC"}