@graview/embed 0.1.10 → 0.1.14

package/README.md

@@ -49,14 +49,87 @@ const handle = mount(root, { app, face });  // drawn in this commit
 ```
 
 What this asks of the framework, and what it adds: the theme scopes to the
-element (`themeCss(scheme, brand, { scope })`) rather than the document, every
+element (`themeBaseCss(scheme, brand, { scope })`, and the scene's own rules,
+`sceneCss`, drawn by the scene face beside it) rather than the document, every
 rule of it held inside that element, so nothing of the host's is restyled; the
 panes size against the picture's own box (`cqh`) rather than the viewport;
 the routed face runs on a memory router, so the host page's address is never
-touched; the brand's fonts are fetched by the embed rather than assumed. The
+touched (unless the host's page is the app: see below); the brand's fonts are fetched by the embed rather than assumed. The
 store is in memory and starts from the seed on every mount, unless the host
 hands it one.
 
+## When the page is the app: the address bar
+
+A host whose whole page is the app — Graview Cloud's hosted app is one —
+hands the routed face the address bar, so a place, a record and the home can
+be linked, reloaded and shared:
+
+```ts
+const handle = mount(root, {
+  app, store,
+  face: innerWidth < 768 ? "pages" : "graview",  // where a bare address opens
+  routing: "address",                            // the default is "memory"
+  basePath: "/apps/a1/",                          // where the app is served; "/" by default
+});
+```
+
+The host answers every address under the base with the same page. The
+address then says which face is drawn and where on it, as the whole-page
+Shell spells it:
+
+| Address | Drawn |
+|---|---|
+| `/apps/a1/places/the-board`, `/apps/a1/tasks/t1` | the routed face, at that page |
+| `/apps/a1#overview=1`, `/apps/a1#focus=t1` | the scene, at that stop (the Graview at altitude) |
+| `/apps/a1` | the routed face's home, or on arrival the host's `face` |
+
+Each page the routed face opens is pushed, and Back returns. The scene
+keeps its stop in the fragment the way the Shell does: a step is pushed,
+moving the furniture replaces. The face toggle pushes the address of the
+face it goes to, so Back undoes it, and the page you left is where the
+toggle returns you. A reload stays where it was. `faceAtAddress(options)`
+is the face an address opens on, for a host that renders `<Embed>` itself.
+`placesOf(app)` gives each place's `address` within the app, and
+`addressOf(place, { basePath })` from `@graview/core` gives it under the
+base, spelled as the face's own links are (`pathWithin` reads one back).
+
+`routing: "memory"`, the default, is for somebody else's page: it never
+writes `history` and leaves `location` as it was. A host that keeps its
+own history stays on memory routing: `onNavigate(path, how)` is told each
+page the routed face opens (the path within the app, and `"push"`,
+`"replace"` or `"pop"`), and `handle.setPath(path)` sends it back to one
+when the host's own Back arrives.
+
+## When the declaration changes
+
+A chat that changes the app hands the host a new compiled app and a new
+store. `handle.setApp(app, store)` swaps them under the reader (or
+`setApp(app, remote)`, whose presence comes with it), and the reader stays
+where they were:
+
+```ts
+remote.onDeclaration((next) => handle.setApp(latestApp, next));
+```
+
+The face, the place or record open on Pages, and the scene's stop and
+focus are kept. What the change took away falls back to its nearest
+parent: a removed record to its kind's list (or, in the scene, its kind's
+group); a removed kind or place to the home; a lens gone from the scene to
+its kind's group, or the home when the kind went too. Under address
+routing the address stays the source of truth, and one that names
+something gone is replaced, not pushed. The seat, the seats, the people,
+the scheme, the brand and the notices stay; the faces are drawn again, so
+an open menu, a scroll position and a half-typed field do not. `drawn()`
+resolves once the new app is on the page.
+
+A host that must remount reads the place first and hands it back:
+
+```ts
+const at = handle.where();           // { face, path, stop, kind? }
+handle.unmount();
+handle = mount(root, { app, store, at });
+```
+
 ## What stands over what
 
 Every popover, menu and list of suggestions the embed draws — the profile,

package/dist/address.d.ts

@@ -0,0 +1,34 @@
+import { type Place } from "@graview/core";
+import { type MutableRefObject } from "react";
+import type { EmbedFace, FrameOptions } from "./frame.js";
+/**
+ * THE FACE AN EMBED OPENS ON (FR-106): under memory routing, the host's
+ * (`face`, else the one its `stop` implies); under address routing, the one
+ * the address names — a page past the home is the routed face, a fragment
+ * at the home is the scene's stop — and the host's when it names none.
+ * `mount` asks this itself; a host that renders `<Embed>` passes it as `face`.
+ */
+export declare function faceAtAddress(options: Pick<FrameOptions, "routing" | "basePath"> & {
+    readonly face?: EmbedFace;
+    readonly stop?: string;
+}): EmbedFace;
+/** The stop the address holds for the scene on arrival, if it holds one. */
+export declare function stopAtAddress(basePath: string | undefined): string | undefined;
+/**
+ * Keeps the face in step with the address: Back and Forward move between
+ * the routed face and the scene, and the face toggle pushes the address of
+ * the face it goes to. Inside the provider; the scene's own fragment sync
+ * (`UrlSync`) is drawn by the scene face, so it is fetched with the scene.
+ */
+export declare function AddressBar({ basePath, pagesWere, shown, onFace, toggle, kinds, places, }: {
+    readonly basePath: string | undefined;
+    /** The page the routed face had before a new declaration (FR-116), for the toggle to go back to. */
+    readonly pagesWere?: string | undefined;
+    readonly shown: EmbedFace;
+    readonly onFace: ((face: EmbedFace) => void) | undefined;
+    /** Where the strip's toggle is handed this bar's way of changing face. */
+    readonly toggle: MutableRefObject<((face: EmbedFace) => void) | undefined>;
+    readonly kinds: readonly string[];
+    readonly places: readonly Place[];
+}): null;
+//# sourceMappingURL=address.d.ts.map

package/dist/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../src/address.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,KAAK,EAAE,MAAM,eAAe,CAAC;AAIlE,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,OAAO,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA+B1D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,UAAU,CAAC,GAAG;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAIpJ;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAG9E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,SAAS,EACT,KAAK,EACL,MAAM,EACN,MAAM,EACN,KAAK,EACL,MAAM,GACP,EAAE;IACD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,oGAAoG;IACpG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACzD,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC;IAC3E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;CACnC,QA8CA"}

package/dist/address.js

@@ -0,0 +1,109 @@
+import { addressOf, pathWithin } from "@graview/core";
+import { aggregateId, fromUrl, toUrl, withFocus, withOverview } from "@graview/layout/view";
+import { descentTarget } from "@graview/primitives/frame";
+import { useNavigation } from "@graview/react/provider";
+import { useEffect, useRef } from "react";
+/*
+ * THE ADDRESS BAR, FOR A HOST WHOSE PAGE IS THE APP (FR-106).
+ *
+ * Under `routing: "address"` the address says which face is drawn and
+ * where on it, the way the whole-page Shell spells it:
+ *
+ *   <base>/places/the-board, <base>/tasks/t1   a page: the routed face, on its router
+ *   <base>#overview=1, <base>#focus=t1         a stop: the scene (the Graview at altitude),
+ *                                              its view state in the fragment
+ *   <base>                                     the routed face's home — or, on arrival
+ *                                              with no entry the router wrote, the host's face
+ *
+ * The scene always writes a fragment, even an empty `#`, so an address
+ * without one past arrival is a page. The face toggle is a step like any
+ * other: it pushes the address of the face it goes to, and Back undoes it.
+ */
+/** The router's own mark on an entry it wrote: `{ idx }` (react-router), kept across a reload. */
+const routerWrote = (state) => typeof state === "object" && state !== null && "idx" in state;
+/** The face an address names, or null when it names none: a bare home the router did not write, or outside the base. */
+function faceNamed(basePath) {
+    const path = pathWithin(window.location.pathname, basePath);
+    if (path === null)
+        return null;
+    if (path !== "/")
+        return "pages";
+    if (window.location.href.includes("#"))
+        return fromUrl(window.location.hash).overview ? "graview" : "scene";
+    return routerWrote(window.history.state) ? "pages" : null;
+}
+/**
+ * THE FACE AN EMBED OPENS ON (FR-106): under memory routing, the host's
+ * (`face`, else the one its `stop` implies); under address routing, the one
+ * the address names — a page past the home is the routed face, a fragment
+ * at the home is the scene's stop — and the host's when it names none.
+ * `mount` asks this itself; a host that renders `<Embed>` passes it as `face`.
+ */
+export function faceAtAddress(options) {
+    const asked = options.face ?? (options.stop && fromUrl(options.stop).overview ? "graview" : "scene");
+    if (options.routing !== "address" || typeof window === "undefined")
+        return asked;
+    return faceNamed(options.basePath) ?? asked;
+}
+/** The stop the address holds for the scene on arrival, if it holds one. */
+export function stopAtAddress(basePath) {
+    if (typeof window === "undefined")
+        return undefined;
+    return pathWithin(window.location.pathname, basePath) === "/" && window.location.href.includes("#") ? window.location.hash || "#" : undefined;
+}
+/**
+ * Keeps the face in step with the address: Back and Forward move between
+ * the routed face and the scene, and the face toggle pushes the address of
+ * the face it goes to. Inside the provider; the scene's own fragment sync
+ * (`UrlSync`) is drawn by the scene face, so it is fetched with the scene.
+ */
+export function AddressBar({ basePath, pagesWere, shown, onFace, toggle, kinds, places, }) {
+    const { view, go } = useNavigation();
+    const latest = useRef({ shown, view, onFace });
+    latest.current = { shown, view, onFace };
+    // The page the routed face was on when the scene was asked for, to go back to by the toggle.
+    const pagesAt = useRef(pagesWere ?? "/");
+    const leaving = () => {
+        pagesAt.current = `${pathWithin(window.location.pathname, basePath) ?? "/"}${window.location.search}`;
+    };
+    toggle.current = (next) => {
+        const { shown: from, view: here, onFace: tell } = latest.current;
+        if (next === "pages" && from !== "pages") {
+            window.history.pushState(null, "", addressOf(pagesAt.current, { basePath }));
+        }
+        else if (next !== "pages" && from === "pages") {
+            leaving();
+            // The view the scene will draw, decided here so the fragment pushed is the one it lands on.
+            const stop = next === "graview" ? withOverview(here, true) : here.overview ? withFocus(withOverview(here, false), descentTarget(here, kinds)) : here;
+            go(stop);
+            window.history.pushState(null, "", `${addressOf("/", { basePath })}${toUrl(stop)}`);
+        }
+        tell?.(next);
+    };
+    useEffect(() => {
+        const onPop = () => {
+            if (pathWithin(window.location.pathname, basePath) === null)
+                return;
+            // Past arrival, a bare home is the routed face's.
+            const named = faceNamed(basePath) ?? "pages";
+            const { shown: from, onFace: tell } = latest.current;
+            if (named === "pages") {
+                if (from !== "pages")
+                    tell?.("pages");
+                return;
+            }
+            // Between the scene and the Graview the fragment sync follows by itself; from the pages, the scene comes back where the fragment says.
+            if (from !== "pages")
+                return;
+            const parsed = fromUrl(window.location.hash);
+            const name = parsed.within?.["view"];
+            const place = name !== undefined && !parsed.focusId ? places.find((candidate) => candidate.as === name) : undefined;
+            go(place ? { ...parsed, focusId: aggregateId(place.kind) } : parsed);
+            tell?.(named);
+        };
+        window.addEventListener("popstate", onPop);
+        return () => window.removeEventListener("popstate", onPop);
+    }, [basePath, go, places]);
+    return null;
+}
+//# sourceMappingURL=address.js.map

package/dist/address.js.map

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

package/dist/embed.d.ts

@@ -1,9 +1,10 @@
-import type { AnySchema, Brand, Person, Principal, Store } from "@graview/core";
+import { type AnySchema, type Brand, type GraviewApp, type Person, type Principal, type Store } from "@graview/core";
 import type { StudioOffered, StudioOnApply, StudioPlace as StudioPlaceType } from "@graview/studio";
 import type { CompanionMode } from "@graview/primitives";
 import { type Notice, type NoticeHandle } from "@graview/primitives/frame";
 import { type Scheme } from "@graview/react/provider";
-import { AUTO_SCENE_HEIGHT, type EmbedFace, type EmbedHostContext, type FrameOptions } from "./frame.js";
+import type { EmbedWhere } from "./where.js";
+import { AUTO_SCENE_HEIGHT, type EmbedFace, type EmbedHostContext, type EmbedRemote, type FrameOptions } from "./frame.js";
 /**
  * FETCH A FACE BEFORE IT IS DRAWN (FR-57). A host that knows which face it
  * will open on — Graview Cloud's shell knows from the window's width before
@@ -20,7 +21,8 @@ export declare function preload(...faces: readonly EmbedFace[]): Promise<void>;
  * one element. So the theme is scoped to that element, the panes size
  * against the picture's own box, the routed face runs on a memory router,
  * the store lives in memory and starts from the seed, and the view state is
- * a prop rather than a URL. Everything else — the scene, the rails, the
+ * a prop rather than a URL — unless the host's page IS the app and it hands
+ * over the address bar (`routing: "address"`, FR-106). Everything else — the scene, the rails, the
  * inspector, the pages — is the framework's own, unchanged.
  */
 export { AUTO_SCENE_HEIGHT };
@@ -65,6 +67,13 @@ export interface EmbedOptions<S extends AnySchema = AnySchema> extends FrameOpti
      * `"hidden"`, which is the host's to say.
      */
     readonly companion?: CompanionMode;
+    /**
+     * WHERE TO OPEN, AS `handle.where()` SAID IT (FR-116): the face, the page
+     * on Pages and the scene's stop, over `face`, `path` and `stop`, settled
+     * in this app — what it no longer has falls back to its nearest parent. A
+     * host that must remount on a new declaration hands the old place back here.
+     */
+    readonly at?: EmbedWhere;
 }
 /** The studio an embed offers, for a host that keeps the declaration itself. */
 export interface EmbedStudio {
@@ -110,8 +119,28 @@ export interface EmbedProps<S extends AnySchema = AnySchema> extends EmbedOption
 export declare function faceOf(stop: string | undefined): EmbedFace;
 export declare function Embed<S extends AnySchema>(props: EmbedProps<S>): import("react").JSX.Element;
 export interface EmbedHandle {
+    /**
+     * WHERE THE READER IS (FR-116): the face, the page on Pages (or the one it
+     * last had) and the scene's stop — for a host that must remount to hand
+     * back as `mount(…, { at })`.
+     */
+    where(): EmbedWhere;
+    /**
+     * A NEW DECLARATION UNDER THE READER (FR-116): the app and its store — or a
+     * remote, whose presence comes with it — swapped in place. The face, the
+     * page on Pages and the scene's stop are kept; what the app no longer has
+     * falls back to its nearest parent. The seat, the seats, the people, the
+     * scheme, the brand asked for and the notices stay; what is drawn is drawn
+     * again, so an open menu, a scroll and a half-typed field do not.
+     */
+    setApp(app: GraviewApp<AnySchema>, store: Store<AnySchema> | EmbedRemote<AnySchema>): void;
     setFace(face: EmbedFace): void;
     setStop(stop: string): void;
+    /**
+     * Sends the routed face to a path within the app's own routes (FR-106): a
+     * host that keeps its own history hands back the path its Back arrived at.
+     */
+    setPath(path: string): void;
     setScheme(scheme: Scheme): void;
     /** Put another principal at the keyboard; the store and its history stay. */
     setSeat(principal: Principal): void;

package/dist/embed.d.ts.map

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

package/dist/embed.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { EMPTY_VIEW, aggregateId, fromUrl, withFocus, withOverview } from "@graview/layout/view";
+import { pathWithin } from "@graview/core";
+import { EMPTY_VIEW, aggregateId, fromUrl, toUrl, withFocus, withOverview } from "@graview/layout/view";
 import { VISUALLY_HIDDEN, descentTarget, fetchFrameworkViews, frameworkViewDoors, useWidth } from "@graview/primitives/frame";
 import { createNoticeBoard } from "@graview/primitives/frame";
 import { ErrorReportContext, GraviewProvider, openingView, useNavigation } from "@graview/react/provider";
-import { createElement, lazy, Suspense, useCallback, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { AddressBar, faceAtAddress, stopAtAddress } from "./address.js";
+import { createContext, createElement, lazy, Suspense, useCallback, useContext, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
 import { flushSync } from "react-dom";
 import { AUTO_SCENE_HEIGHT, FaceBoundary, FrameNotices, providerProps, storeOf, Strip, useErrorReport, useFrame, useIntrinsicHeight, useReady, useViews, } from "./frame.js";
@@ -82,7 +84,8 @@ const StudioPlace = lazy(() => import("@graview/studio").then((studio) => ({ def
  * one element. So the theme is scoped to that element, the panes size
  * against the picture's own box, the routed face runs on a memory router,
  * the store lives in memory and starts from the seed, and the view state is
- * a prop rather than a URL. Everything else — the scene, the rails, the
+ * a prop rather than a URL — unless the host's page IS the app and it hands
+ * over the address bar (`routing: "address"`, FR-106). Everything else — the scene, the rails, the
  * inspector, the pages — is the framework's own, unchanged.
  */
 export { AUTO_SCENE_HEIGHT };
@@ -113,12 +116,40 @@ export function faceOf(stop) {
     return stop && fromUrl(stop).overview ? "graview" : "scene";
 }
 export function Embed(props) {
-    const { app, face = faceOf(props.stop), stop, toggle = true, standing = "Everything is in order", principal, heading = 2 } = props;
+    const [, ready] = useState(false);
+    const arrived = useCallback(() => ready(true), []);
+    // A place handed back is settled before the embed draws: until the rules for it are here, nothing stands in the element.
+    return props.at && !settling ? _jsx(Settling, { onReady: arrived }) : _jsx(Drawing, { ...props });
+}
+function Drawing(props) {
+    const { app, face = props.at?.face ?? faceOf(props.stop), stop, toggle = true, standing = "Everything is in order", principal, heading = 2 } = props;
     const { rootRef, scope, css, scheme, store, presence, brand, auto, height } = useFrame(props);
     const views = useViews(props, frameworkViewDoors);
     const kinds = app.schema.kinds;
-    // The first view only: after it, where the reader goes is theirs.
-    const initialView = useMemo(() => viewFor(face, stop, kinds, views.places(), openingView(views, app.schema)), []);
+    const address = props.routing === "address";
+    const at = useMemo(() => (props.at ? settling.settleAt(props, store.seenBy(principal ?? { kind: "human" }), views.places()) : undefined), []);
+    // The first view only: after it, where the reader goes is theirs. Under address routing, a stop in the fragment is where it starts.
+    const initialView = useMemo(() => viewFor(face, at?.stop ?? (address ? stopAtAddress(props.basePath) : undefined) ?? stop, kinds, views.places(), openingView(views, app.schema)), []);
+    /*
+     * THE PAGE ON PAGES, KEPT (FR-116): where the routed face is, or last was,
+     * so the scene and back is the same page, and `where()` can say it. Under
+     * memory routing the routed face opens on it; under address routing the
+     * address is where it is.
+     */
+    const pagesAt = useRef(undefined);
+    pagesAt.current ??= { path: at?.path ?? (address ? (face === "pages" ? (pathWithin(window.location.pathname, props.basePath) ?? "/") + window.location.search : "/") : (props.path ?? "/")), asked: props.path };
+    if (props.path !== pagesAt.current.asked)
+        pagesAt.current = { path: props.path ?? "/", asked: props.path };
+    const told = useRef(props.onNavigate);
+    told.current = props.onNavigate;
+    const onNavigate = useCallback((path, how) => {
+        pagesAt.current.path = path;
+        told.current?.(path, how);
+    }, []);
+    const whereabouts = useContext(Whereabouts);
+    if (whereabouts)
+        whereabouts.pages = () => pagesAt.current.path;
+    const toggled = useRef(undefined);
     /*
      * NARROW, THE PAGES (FR-13). Below `pagesBelow` the scene and the Graview
      * give way to the routed face, and come back when there is room: the
@@ -130,11 +161,11 @@ export function Embed(props) {
     useIntrinsicHeight(rootRef, shown, props.onIntrinsicHeight);
     const report = useErrorReport(props.onError, shown);
     const ready = useReady(props.onReady, shown);
-    const told = useRef(props.onDrawn);
-    told.current = props.onDrawn;
+    const drawnTold = useRef(props.onDrawn);
+    drawnTold.current = props.onDrawn;
     const drawn = useCallback((asked, drew) => {
         ready(drew);
-        told.current?.(asked);
+        drawnTold.current?.(asked);
     }, [ready]);
     /*
      * THE EMBED IS ITSELF A LANDMARK.
@@ -150,7 +181,25 @@ export function Embed(props) {
      * the docs warn about, said out loud by `landmark-unique` instead of
      * silently.
      */
-    return (_jsxs("section", { ref: rootRef, className: scope, "aria-label": props.label ?? app.name, "data-graview-embed": shown, "data-graview-scheme": scheme, ...(narrow ? { "data-graview-embed-narrow": "" } : {}), style: { position: "relative", height, minHeight: auto ? 0 : 320, display: "flex", flexDirection: "column", overflow: "hidden", borderRadius: "var(--graview-radius, 12px)" }, children: [_jsx("style", { children: css }), heading !== false && shown !== "pages" ? _jsx(HeadingAt, { level: heading, children: props.label ?? app.name }) : null, _jsxs(ErrorReportContext.Provider, { value: report, children: [_jsx(FrameNotices, { rootRef: rootRef, board: props.notices }), _jsx(FaceBoundary, { module: "@graview/react", report: report, content: true, children: _jsxs(GraviewProvider, { store: store, views: views, initialView: initialView, scheme: scheme, ...providerProps(props, presence, brand), children: [_jsx(Faces, { face: shown, stop: stop, kinds: kinds, places: views.places() }), toggle && shown !== "picture" ? (_jsx(FaceBoundary, { module: "@graview/embed", report: report, children: _jsx(EmbedStrip, { app: app, studio: props.studio, face: shown, narrow: narrow, onFace: props.onFace, standing: standing, seats: props.seats, principal: principal, onSeat: props.onSeat, hostActions: props.hostActions, report: report }) })) : null, _jsx(FaceBoundary, { module: shown === "pages" || shown === "picture" ? "@graview/pages" : "@graview/react", report: report, content: true, children: _jsxs(Suspense, { fallback: _jsx(Arriving, { auto: auto, scene: shown !== "pages" && shown !== "picture" }), children: [shown === "picture" ? (_jsx(PictureFace, { store: store, views: views, as: (stop ? fromUrl(stop).within?.["view"] : undefined) ?? "" })) : shown === "pages" ? (_jsx(PagesContent, { store: store, views: views, presence: presence, auto: auto, brand: brand, props: props })) : (_jsx(SceneFace, { auto: auto, rememberAs: app.name, ...(props.companion ? { companion: props.companion } : {}) })), _jsx(Drawn, { asked: face, shown: shown, onDrawn: drawn })] }) }, shown)] }) })] })] }));
+    return (_jsxs("section", { ref: rootRef, className: scope, "aria-label": props.label ?? app.name, "data-graview-embed": shown, "data-graview-scheme": scheme, ...(narrow ? { "data-graview-embed-narrow": "" } : {}), style: { position: "relative", height, minHeight: auto ? 0 : 320, display: "flex", flexDirection: "column", overflow: "hidden", borderRadius: "var(--graview-radius, 12px)" }, children: [_jsx("style", { children: css }), heading !== false && shown !== "pages" ? _jsx(HeadingAt, { level: heading, children: props.label ?? app.name }) : null, _jsxs(ErrorReportContext.Provider, { value: report, children: [_jsx(FrameNotices, { rootRef: rootRef, board: props.notices }), _jsx(FaceBoundary, { module: "@graview/react", report: report, content: true, children: _jsxs(GraviewProvider, { store: store, views: views, initialView: initialView, scheme: scheme, ...providerProps(props, presence, brand), children: [_jsx(Faces, { face: shown, stop: stop, kinds: kinds, places: views.places() }), whereabouts ? _jsx(Watch, { into: whereabouts }) : null, address ? _jsx(AddressBar, { pagesWere: at?.path, basePath: props.basePath, shown: shown, onFace: props.onFace, toggle: toggled, kinds: kinds, places: views.places() }) : null, toggle && shown !== "picture" ? (_jsx(FaceBoundary, { module: "@graview/embed", report: report, children: _jsx(EmbedStrip, { app: app, studio: props.studio, face: shown, narrow: narrow, onFace: address ? (next) => toggled.current?.(next) : props.onFace, standing: standing, seats: props.seats, principal: principal, onSeat: props.onSeat, hostActions: props.hostActions, report: report }) })) : null, _jsx(FaceBoundary, { module: shown === "pages" || shown === "picture" ? "@graview/pages" : "@graview/react", report: report, content: true, children: _jsxs(Suspense, { fallback: _jsx(Arriving, { auto: auto, scene: shown !== "pages" && shown !== "picture" }), children: [shown === "picture" ? (_jsx(PictureFace, { store: store, views: views, as: (stop ? fromUrl(stop).within?.["view"] : undefined) ?? "" })) : shown === "pages" ? (_jsx(PagesContent, { store: store, views: views, presence: presence, auto: auto, brand: brand, props: { ...props, onNavigate, ...(address ? {} : { path: pagesAt.current.path }) } })) : (_jsx(SceneFace, { address: address, auto: auto, rememberAs: app.name, scheme: scheme, scope: scope, ...(props.companion ? { companion: props.companion } : {}) })), _jsx(Drawn, { asked: face, shown: shown, onDrawn: drawn })] }) }, shown)] }) })] })] }));
+}
+const Whereabouts = createContext(null);
+/** Keeps the scene's view where `where()` can read it. */
+function Watch({ into }) {
+    into.view = useNavigation().view;
+    return null;
+}
+/*
+ * SETTLING A PLACE IN A NEW APP, fetched when one is handed over (FR-116):
+ * a declaration changes rarely, and a page that never swaps one never loads
+ * the rules for what falls back to what.
+ */
+let settling;
+const fetchSettling = () => import("./where.js").then((module) => void (settling = module));
+/** Stands in for the embed while the rules for a handed-back place arrive, then draws it. */
+function Settling({ onReady }) {
+    useLayoutEffect(() => void fetchSettling().then(onReady), [onReady]);
+    return null;
 }
 /** A heading at a level the host chose, heard and not seen. */
 function HeadingAt({ level, children }) {
@@ -202,7 +251,8 @@ function EmbedStrip({ app, studio, face, narrow = false, onFace, standing, seats
                 fontSize: "0.875rem",
                 borderWidth: 1,
                 borderStyle: "solid",
-                borderColor: candidate.pressed ? "var(--graview-accent)" : "var(--graview-edge)",
+                // The face you are on wears the capsule; the other is a word to press (FR-117).
+                borderColor: candidate.pressed ? "var(--graview-accent)" : "transparent",
                 color: candidate.pressed ? "var(--graview-accent)" : "var(--graview-ink-muted)",
                 background: candidate.pressed ? "var(--graview-panel)" : "transparent",
             }, children: candidate.label }, candidate.id))), scene: face === "pages"
@@ -226,16 +276,26 @@ function StudioOnTheStrip({ app, studio }) {
         return _jsx(Handed, { ...props });
     return (_jsx(Suspense, { fallback: null, children: _jsx(StudioPlace, { ...props }) }));
 }
+/** The options with a new declaration in them: where the reader was stands for the path and the stop the host first gave. */
+function swapped({ path: _path, stop: _stop, ...options }, swap) {
+    return { ...options, app: swap.app, at: swap.at, ...(swap.remote.presence ? { presence: swap.remote.presence } : {}) };
+}
 /**
  * Mounts an app into an element and hands back the controls. The first
  * render is synchronous, so what comes back is already on the page.
  */
 export function mount(element, options) {
-    const store = options.store ?? options.remote?.store ?? storeOf(options.app, options.seed);
+    let store = (options.store ?? options.remote?.store ?? storeOf(options.app, options.seed));
     const board = options.notices ?? createNoticeBoard();
     let setters = null;
+    const here = {};
+    let swaps = 0;
+    // A new declaration on its way (FR-116): `drawn()` waits for it.
+    let swapping = Promise.resolve();
     // Which face is asked for, which is drawn, and who is waiting for the one asked for.
-    let asked = options.face ?? faceOf(options.stop);
+    // Under address routing, the face the address names (FR-106).
+    const opening = faceAtAddress({ ...options, ...(options.at ? { face: options.at.face } : {}) });
+    let asked = opening;
     let drawnFace = null;
     let waiting = [];
     const onDrawn = (face) => {
@@ -249,29 +309,60 @@ export function mount(element, options) {
             resolve();
     };
     function Host() {
-        const [face, setFace] = useState(options.face ?? faceOf(options.stop));
+        const [face, setFace] = useState(opening);
         const [stop, setStop] = useState(options.stop);
+        const [path, setPath] = useState(options.path);
         const [scheme, setScheme] = useState(options.scheme ?? "auto");
         const [principal, setSeat] = useState(options.principal);
         const [seats, setSeats] = useState(options.seats);
         const [people, setPeople] = useState(options.people);
         const [hostContext, setHostContext] = useState(options.hostContext);
         const [brand, setBrand] = useState(options.brand);
-        setters = { face: setFace, stop: setStop, scheme: setScheme, seat: setSeat, seats: setSeats, people: setPeople, hostContext: setHostContext, brand: setBrand };
-        return (_jsx(Embed, { ...options, store: store, notices: board, face: face, ...(stop !== undefined ? { stop } : {}), ...(principal ? { principal } : {}), ...(seats ? { seats } : {}), ...(people ? { people } : {}), ...(hostContext ? { hostContext } : {}), ...(brand ? { brand } : {}), scheme: scheme, onFace: (next) => {
-                asked = next;
-                setFace(next);
-            }, onSeat: setSeat, onDrawn: onDrawn }));
+        const [swap, setSwap] = useState(undefined);
+        setters = {
+            app: (next) => {
+                setSwap(next);
+                setPath(undefined);
+                setStop(undefined);
+            },
+            face: setFace, stop: setStop, path: setPath, scheme: setScheme, seat: setSeat, seats: setSeats, people: setPeople, hostContext: setHostContext, brand: setBrand
+        };
+        return (_jsx(Whereabouts.Provider, { value: here, children: _jsx(Embed, { ...(swap ? swapped(options, swap) : options), store: store, notices: board, face: face, ...(stop !== undefined ? { stop } : {}), ...(path !== undefined ? { path } : {}), ...(principal ? { principal } : {}), ...(seats ? { seats } : {}), ...(people ? { people } : {}), ...(hostContext ? { hostContext } : {}), ...(brand ? { brand } : {}), scheme: scheme, onFace: (next) => {
+                    asked = next;
+                    setFace(next);
+                }, onSeat: setSeat, onDrawn: onDrawn }, swap?.n ?? 0) }));
     }
+    const where = () => {
+        const focus = here.view?.focusId;
+        const kind = focus ? store.graph.getNode(focus)?.kind : undefined;
+        return { face: asked, path: here.pages?.() ?? options.path ?? "/", stop: here.view ? toUrl(here.view) : (options.stop ?? "#"), ...(kind ? { kind } : {}) };
+    };
     const root = createRoot(element);
     flushSync(() => root.render(_jsx(Host, {})));
     return {
-        store: store,
+        get store() {
+            return store;
+        },
+        where,
+        setApp: (app, given) => {
+            const remote = "graph" in given ? { store: given } : given;
+            // The app on the page stays drawn until the rules for settling the place in the new one are here.
+            const swap = () => {
+                const at = where();
+                store = remote.store;
+                flushSync(() => setters?.app({ app, remote, at, n: ++swaps }));
+            };
+            if (settling)
+                swap();
+            else
+                swapping = swapping.then(fetchSettling).then(swap);
+        },
         setFace: (face) => {
             asked = face;
             flushSync(() => setters?.face(face));
         },
         setStop: (stop) => flushSync(() => setters?.stop(stop)),
+        setPath: (path) => flushSync(() => setters?.path(path)),
         setScheme: (scheme) => flushSync(() => setters?.scheme(scheme)),
         setSeat: (principal) => flushSync(() => setters?.seat(principal)),
         setSeats: (seats) => flushSync(() => setters?.seats(seats)),
@@ -279,7 +370,7 @@ export function mount(element, options) {
         setHostContext: (context) => flushSync(() => setters?.hostContext(context)),
         setBrand: (brand) => flushSync(() => setters?.brand(brand)),
         /* Drawn is the face asked for — below `pagesBelow`, drawn as the pages that stand in for it. */
-        drawn: () => (drawnFace === asked ? Promise.resolve() : new Promise((resolve) => waiting.push(resolve))),
+        drawn: () => swapping.then(() => (drawnFace === asked ? undefined : new Promise((resolve) => waiting.push(resolve)))),
         notify: (notice) => {
             let said;
             flushSync(() => {