@kestack/kabuki 0.0.0 → 0.0.2

package/dist/routing/router/router.js

@@ -0,0 +1,801 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Clock, Effect, Layer, Option, Queue, Schema, Stream } from 'effect';
+import { Actor, Command } from '../../core/index.js';
+import { View, lazyOf } from '../../react/index.js';
+import { Adapter, KEY } from '../adapter/index.js';
+import { Loading, Navigation, moveOptions } from '../capability/index.js';
+import { knownOf } from '../page/index.js';
+import { Scrolling, keyOf, restores, scriptFor } from '../scroll/index.js';
+import { linkOptions } from './context.js';
+import { dueRuns, holdingAt, holdingSchema, loadPlace, placeMessages, readyOf, settle, shownOf, } from './data.js';
+import { Frame } from './frame.js';
+const HOW = ['load', 'push', 'replace', 'back', 'forward'];
+/** How a pending move lands: `arrive` is a push the address already shows; `back` and `forward` go to an entry. */
+const LANDS = ['push', 'replace', 'load', 'arrive', 'back', 'forward'];
+/** Redirects followed in a row before a move gives up, as not found. */
+const HOPS = 8;
+/** What a landed move says about its scroll, of what its push or replace said. */
+const scrollOf = (said) => ({
+    ...(said?.resetScroll === undefined ? {} : { resetScroll: said.resetScroll }),
+    ...(said?.hashScrollIntoView === undefined
+        ? {}
+        : { hashScrollIntoView: said.hashScrollIntoView }),
+});
+/** What a Pushed or Replaced Message said besides where it goes. */
+const saidOf = ({ resetScroll, hash, hashScrollIntoView, }) => ({
+    ...(resetScroll === undefined ? {} : { resetScroll }),
+    ...(hash ? { hash } : {}),
+    ...(hashScrollIntoView === undefined ? {} : { hashScrollIntoView }),
+});
+/** An entry at `route`, with `hash` if there is one. */
+const entryOf = (key, route, hash) => hash ? { key, route, hash } : { key, route };
+/** Through the Adapter, if the Layer has one: in memory, nothing. */
+const adapter = (use) => Effect.serviceOption(Adapter).pipe(Effect.map(Option.map(use)), Effect.asVoid);
+const write = Command.make('write the address', {
+    args: Schema.Struct({
+        url: Schema.String,
+        key: Schema.String,
+        replace: Schema.Boolean,
+    }),
+    run: ({ url, key, replace }) => adapter((at) => (replace ? at.replace(url, key) : at.push(url, key))),
+});
+const go = Command.make('go', {
+    args: Schema.Struct({ by: Schema.Number }),
+    run: ({ by }) => adapter((at) => at.go(by)),
+});
+const leave = Command.make('leave', {
+    args: Schema.Struct({
+        url: Schema.String,
+        replace: Schema.optionalKey(Schema.Boolean),
+    }),
+    run: ({ url, replace }) => adapter((at) => at.leave(url, replace ? { replace } : undefined)),
+});
+const forget = Command.make('forget the Data cache', {
+    run: () => Effect.serviceOption(Loading).pipe(Effect.flatMap((found) => Option.isSome(found) && found.value.forget
+        ? found.value.forget
+        : Effect.void)),
+});
+/** The link a plain click landed on, unless the click asks for something else: a new tab, a download, a full load. */
+const linkOf = (event) => {
+    if (event.defaultPrevented || event.button !== 0)
+        return undefined;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+        return undefined;
+    const link = event.target?.closest?.('a');
+    if (!(link instanceof HTMLAnchorElement) || !link.href)
+        return undefined;
+    if (link.hasAttribute('download'))
+        return undefined;
+    if (link.target && link.target !== '_self')
+        return undefined;
+    if (link.relList.contains('external'))
+        return undefined;
+    return link;
+};
+/**
+ * The router of an app: one Actor, above the build of the app's root page,
+ * drawn with the root page's View. It holds the history, as entries and
+ * where it is in them, and hands the root page the current Route. Every
+ * move is one Message to it: a link click, a Request on Navigation, the
+ * Adapter's Back and Forward. A move to places whose data is not there yet
+ * waits up to its delay while a Worker loads it through `Loading`, so a
+ * quick answer, or a copy the Data cache kept, shows no loading screen;
+ * after that the move lands and each new place loads its own. It holds the
+ * data of every place on screen, `data.ts`, and hands each page its own as
+ * `status`, down through the pages above it. It draws the app, catches
+ * plain clicks on links inside it, preloads for links, and writes the
+ * Metadata. With no Adapter in the Layer it routes in memory; with one, it
+ * writes each move to the address with a Command, and hears the address
+ * with a Worker.
+ */
+export const app = (routes, view) => {
+    const { base, delay, scroll: scrolling } = routes.options;
+    const root = view.actor;
+    if (root.page !== routes.root)
+        throw new Error('[@kestack/kabuki/routing] the View handed to the Router does not draw a build of its root page');
+    // Named for devtools and errors, as every page is after its key.
+    if (root.name === 'Page') {
+        root.name = 'App';
+        root.definition.name = 'App';
+    }
+    const href = (route) => {
+        const path = routes.path(route);
+        return base && path === '/' ? base : `${base}${path}`;
+    };
+    /** A URL inside the base, without it; `undefined` for a URL outside. */
+    const inside = (url) => {
+        if (!base)
+            return url;
+        if (url === base)
+            return '/';
+        if (url.startsWith(`${base}/`))
+            return url.slice(base.length);
+        if (url.startsWith(`${base}?`))
+            return `/${url.slice(base.length)}`;
+        return undefined;
+    };
+    const same = (a, b) => routes.path(a) === routes.path(b);
+    /**
+     * Whether `url` is how `route` is written, give or take query params no
+     * page reads, like `?utm_source=`: such a URL is left in the address as
+     * it is, and every move the app makes writes its Route alone.
+     */
+    const shows = (url, route) => {
+        const written = routes.path(route);
+        if (url === written)
+            return true;
+        const [path, query = ''] = url.split('?');
+        const [want, wanted = ''] = written.split('?');
+        if (path !== want)
+            return false;
+        const reads = new URLSearchParams(wanted);
+        const read = new URLSearchParams(Array.from(new URLSearchParams(query)).filter(([name]) => reads.has(name)));
+        return read.toString() === reads.toString();
+    };
+    /** A URL inside the base, with it. */
+    const withBase = (url) => {
+        if (!base)
+            return url;
+        if (url === '/')
+            return base;
+        return url.startsWith('/?') ? `${base}${url.slice(1)}` : `${base}${url}`;
+    };
+    const start = () => routes.read('/').route;
+    const notFound = (route) => ({ _tag: 'NotFound', path: routes.path(route) });
+    const RouteSchema = routes.route;
+    /** What each place with data may start from, by dotted name, each with its own Schema. */
+    const KnownSchema = Schema.Struct(Object.fromEntries(routes.data.map(([name, data]) => [
+        name,
+        Schema.optionalKey(Schema.Union([
+            Schema.TaggedStruct('Ready', {
+                data,
+                stale: Schema.Boolean,
+                from: Schema.Literals(['server', 'browser', 'cache']),
+                at: Schema.Number,
+                took: Schema.NullOr(Schema.Number),
+            }),
+            Schema.TaggedStruct('Failed', {
+                reason: Schema.String,
+                notFound: Schema.Boolean,
+            }),
+        ])),
+    ])));
+    const actor = Actor.define('Router', {
+        input: Schema.UndefinedOr(Schema.Struct({
+            route: RouteSchema,
+            known: Schema.optionalKey(KnownSchema),
+        })),
+        model: Schema.Struct({
+            entries: Schema.Array(Schema.Struct({
+                key: Schema.String,
+                route: RouteSchema,
+                hash: Schema.optionalKey(Schema.String),
+            })),
+            at: Schema.Number,
+            session: Schema.String,
+            next: Schema.Number,
+            move: Schema.Struct({
+                from: Schema.NullOr(RouteSchema),
+                to: RouteSchema,
+                how: Schema.Literals(HOW),
+                resetScroll: moveOptions.resetScroll,
+                hashScrollIntoView: moveOptions.hashScrollIntoView,
+            }),
+            pending: Schema.NullOr(Schema.Struct({
+                id: Schema.Number,
+                to: RouteSchema,
+                how: Schema.Literals(LANDS),
+                wanted: Schema.Array(Schema.String),
+                hops: Schema.Number,
+                since: Schema.Number,
+                key: Schema.NullOr(Schema.String),
+                said: Schema.optionalKey(Schema.Struct(moveOptions)),
+            })),
+            holding: Schema.NullOr(RouteSchema),
+            loads: Schema.Number,
+            data: holdingSchema(routes),
+            reload: Schema.Number,
+            attached: Schema.Boolean,
+            loaded: Schema.Boolean,
+        }),
+        message: Schema.TaggedUnion({
+            Pushed: { route: RouteSchema, ...moveOptions },
+            Replaced: { route: RouteSchema, ...moveOptions },
+            Went: { by: Schema.Number },
+            WentBackTo: { route: RouteSchema },
+            Arrived: {
+                route: RouteSchema,
+                key: Schema.NullOr(Schema.String),
+                url: Schema.String,
+                hash: Schema.String,
+            },
+            Attached: { session: Schema.String },
+            Left: { url: Schema.String },
+            Waited: { id: Schema.Number },
+            Loaded: { id: Schema.Number, known: KnownSchema },
+            Redirected: { id: Schema.Number, route: RouteSchema },
+            Reloaded: {},
+            Preloading: { route: RouteSchema },
+            ...placeMessages(routes),
+        }),
+    });
+    const current = (model) => model.entries[model.at];
+    /** The Route drawn: the current entry's, or the one a held Back or Forward still draws. */
+    const shown = (model) => model.holding ?? current(model).route;
+    /** A key no entry has had, in this page load or any before it. */
+    const fresh = (model) => `${model.session}.${model.next}`;
+    /** Where an entry is in the address: its Route's URL, and its hash. */
+    const addressOf = (entry) => `${href(entry.route)}${entry.hash ? `#${entry.hash}` : ''}`;
+    const writing = (model, replace) => write({
+        url: addressOf(current(model)),
+        key: current(model).key,
+        replace,
+    });
+    /** The model with the data of the places on the Route it draws: each new place starts from what is known. */
+    const withData = (model, known) => ({
+        ...model,
+        data: holdingAt(routes, shown(model), model.data, known, model.reload),
+    });
+    /**
+     * A move landing, with what its new places start from. A Redirect or not
+     * found on the entry shown keeps the move that led to it, now to where it
+     * ends.
+     */
+    const land = (model, to, how, known, along = {}) => {
+        const out = landing(model, to, how, along);
+        return { ...out, model: withData(out.model, known) };
+    };
+    const landing = (model, to, how, { key = null, said } = {}) => {
+        const settled = { ...model, pending: null, holding: null };
+        const from = shown(model);
+        // Back and Forward are at their entry already: the move only lands.
+        if (how === 'back' || how === 'forward')
+            return { model: { ...settled, move: { from, to, how } } };
+        if (how === 'load') {
+            const changed = !same(to, from);
+            const next = {
+                ...settled,
+                entries: settled.entries.map((entry, at) => at === model.at ? entryOf(entry.key, to, entry.hash) : entry),
+                move: changed ? { ...model.move, to } : model.move,
+            };
+            return changed
+                ? { model: next, command: writing(next, true) }
+                : { model: next };
+        }
+        if (how === 'replace') {
+            // A new entry in the place of the one shown, with a key of its own:
+            // what was kept for the one before is not its.
+            const next = {
+                ...settled,
+                entries: settled.entries.map((entry, at) => at === model.at ? entryOf(fresh(model), to, said?.hash) : entry),
+                next: model.next + 1,
+                move: { from, to, how: 'replace', ...scrollOf(said) },
+            };
+            return { model: next, command: writing(next, true) };
+        }
+        // A URL the app did not write is an entry the address already holds,
+        // even at the Route shown: a redirect's is written over.
+        if (how !== 'arrive' &&
+            same(to, current(model).route) &&
+            (said?.hash ?? '') === (current(model).hash ?? ''))
+            return { model: settled };
+        const next = {
+            ...settled,
+            entries: [
+                ...model.entries.slice(0, model.at + 1),
+                entryOf(key ?? fresh(model), to, said?.hash),
+            ],
+            at: model.at + 1,
+            next: key === null ? model.next + 1 : model.next,
+            move: { from, to, how: 'push', ...scrollOf(said) },
+        };
+        return { model: next, command: writing(next, how === 'arrive') };
+    };
+    /**
+     * A move to `route`: it lands at once if every place it brings with data
+     * is already on screen; otherwise it waits, pending, while the `load`
+     * Worker loads the rest, at most `delay`.
+     */
+    const toward = (model, route, how, now, along = {}) => {
+        const drawn = new Set(routes.places(shown(model)).map((place) => place.key));
+        const wanted = routes
+            .places(route)
+            .filter((place) => place.input && !drawn.has(place.key))
+            .map((place) => place.name);
+        if (wanted.length === 0)
+            return land(model, route, how, {}, along);
+        const pending = {
+            id: model.loads,
+            to: route,
+            how,
+            wanted,
+            hops: along.hops ?? 0,
+            since: now,
+            key: along.key ?? null,
+            ...(along.said ? { said: along.said } : {}),
+        };
+        return { model: { ...model, pending, loads: model.loads + 1 } };
+    };
+    /**
+     * To entry `to` of the history, at `route`: the history moves at once, as
+     * the address does, and the Route shown stays drawn while the move is
+     * held, so anything that replaces the move starts from where the address is.
+     */
+    const reaching = (model, to, route, now) => toward({
+        ...model,
+        at: to,
+        entries: model.entries.map((entry, at) => at === to ? { key: entry.key, route } : entry),
+        holding: shown(model),
+    }, route, to < model.at ? 'back' : 'forward', now);
+    /** Back or Forward by `by` entries, the address too. */
+    const going = (model, by, now) => {
+        const to = Math.min(Math.max(model.at + by, 0), model.entries.length - 1);
+        if (to === model.at)
+            return {};
+        const moving = reaching(model, to, model.entries[to].route, now);
+        return {
+            ...moving,
+            command: [
+                ...[].concat(moving.command ?? []),
+                go({ by: to - model.at }),
+            ],
+        };
+    };
+    const firstModel = (from) => {
+        const route = from?.route ?? start();
+        return {
+            entries: [{ key: 'm.0', route }],
+            at: 0,
+            session: 'm',
+            next: 1,
+            move: { from: null, to: route, how: 'load' },
+            pending: null,
+            holding: null,
+            loads: 0,
+            data: holdingAt(routes, route, {}, from?.known ?? {}, 0),
+            reload: 0,
+            attached: false,
+            loaded: false,
+        };
+    };
+    /**
+     * Starts loading the code of the lazy View of every page on `route`, so it
+     * loads beside the page's data rather than after it. Code that fails to
+     * load is loaded again when it is drawn.
+     */
+    const preloadViews = (route) => Effect.sync(() => {
+        let build = root;
+        let value = route;
+        while (build && value) {
+            build = build.pages[value._tag];
+            if (build)
+                lazyOf(build)
+                    ?.preload()
+                    .catch(() => { });
+            value = value['page'];
+        }
+    });
+    /**
+     * Loads what the pending move wants, through `Loading`: with none, it
+     * lands without. The code of the lazy Views it will draw starts loading
+     * at the same time, so it is not a second wait after the data. A Redirect,
+     * the outermost first, moves on instead.
+     */
+    const load = (pending, send) => Effect.gen(function* () {
+        yield* preloadViews(pending.to);
+        const found = yield* Effect.serviceOption(Loading);
+        const { id } = pending;
+        if (Option.isNone(found))
+            return yield* send({ _tag: 'Loaded', id, known: {} });
+        const places = routes
+            .places(pending.to)
+            .filter((place) => pending.wanted.includes(place.name));
+        const answers = yield* found.value.load(places.map(({ name, params }) => ({ name, params })));
+        for (const { name } of places) {
+            const answer = answers[name];
+            if (answer?._tag === 'Redirect')
+                return yield* send(answer.href === undefined
+                    ? { _tag: 'Redirected', id, route: answer.route }
+                    : { _tag: 'RedirectedAway', href: answer.href, id });
+        }
+        const known = {};
+        const now = yield* Clock.currentTimeMillis;
+        for (const { name } of places) {
+            const each = answers[name] && knownOf(answers[name], now, 'browser');
+            if (each)
+                known[name] = each;
+        }
+        yield* send({ _tag: 'Loaded', id, known });
+    });
+    /** Warms the Data cache, and the code of the lazy Views, for a Route the app may move to. */
+    const preload = Command.make('preload', {
+        args: Schema.Struct({ route: RouteSchema }),
+        run: ({ route }) => Effect.gen(function* () {
+            yield* preloadViews(route);
+            const found = yield* Effect.serviceOption(Loading);
+            if (Option.isNone(found) || !found.value.preload)
+                return;
+            yield* found.value.preload(routes
+                .places(route)
+                .filter((place) => place.input)
+                .map(({ name, params }) => ({ name, params })));
+        }),
+    });
+    const reloading = (model) => ({
+        model: { ...model, reload: model.reload + 1 },
+        command: forget(),
+    });
+    const built = Actor.build(actor, {
+        init: (from) => ({
+            model: firstModel(from),
+        }),
+        children: {
+            page: {
+                actor: root,
+                props: ({ model }) => {
+                    const route = shown(model);
+                    const found = route._tag !== 'NotFound';
+                    return {
+                        params: {},
+                        query: {},
+                        route: {
+                            name: '',
+                            ...(found ? { page: route } : {}),
+                            params: {},
+                            notFound: found ? null : String(route['path']),
+                            data: shownOf(routes, shown(model), model.data, model.reload),
+                        },
+                    };
+                },
+            },
+        },
+        provides: (self) => Layer.succeed(Navigation, {
+            push: (to, options) => self.send({
+                _tag: 'Pushed',
+                route: to,
+                ...options,
+            }),
+            replace: (to, options) => self.send({
+                _tag: 'Replaced',
+                route: to,
+                ...options,
+            }),
+            back: self.send({ _tag: 'Went', by: -1 }),
+            forward: self.send({ _tag: 'Went', by: 1 }),
+            backTo: (to) => self.send({ _tag: 'WentBackTo', route: to }),
+            reload: self.send({ _tag: 'Reloaded' }),
+            preload: (to) => self.send({ _tag: 'Preloading', route: to }),
+        }),
+        on: {
+            Pushed: (message, { model, at }) => {
+                const { route } = message;
+                const said = saidOf(message);
+                if (model.pending && same(route, model.pending.to))
+                    return {};
+                // A link to the page shown loads it again: a failed page retries.
+                if (same(route, current(model).route) &&
+                    (said.hash ?? '') === (current(model).hash ?? ''))
+                    return reloading({ ...model, pending: null });
+                return toward(model, route, 'push', at, { said });
+            },
+            Replaced: (message, { model, at }) => toward(model, message.route, 'replace', at, { said: saidOf(message) }),
+            Went: ({ by }, { model, at }) => going(model, by, at),
+            WentBackTo: ({ route }, { model, at }) => {
+                const before = model.entries[model.at - 1];
+                if (before && same(before.route, route))
+                    return going(model, -1, at);
+                return toward(model, route, 'replace', at);
+            },
+            Arrived: ({ route, key, url, hash, }, { model, at: now }) => {
+                // A URL that is not how the Route is written, a redirect's or one
+                // with a stray slash, is replaced by the one that is. On the entry
+                // the app opened at or holds, one that only has a query no page
+                // reads is left as it is.
+                const kept = shows(url, route);
+                const known = key === null
+                    ? -1
+                    : model.entries.findIndex((entry) => entry.key === key);
+                if (known >= 0) {
+                    if (known === model.at && same(route, current(model).route))
+                        return kept ? {} : { command: writing(model, true) };
+                    const moving = reaching(model, known, route, now);
+                    return kept
+                        ? moving
+                        : {
+                            ...moving,
+                            command: [
+                                ...[].concat(moving.command ?? []),
+                                write({
+                                    url: addressOf(entryOf(key, route, hash)),
+                                    key: key,
+                                    replace: true,
+                                }),
+                            ],
+                        };
+                }
+                if (!model.loaded) {
+                    // The URL the app opened at: this entry, with the key the address
+                    // kept for it before a reload, else a new one.
+                    const opened = {
+                        ...model,
+                        loaded: true,
+                        entries: model.entries.map((entry, at) => at === model.at
+                            ? entryOf(key ?? fresh(model), entry.route, hash)
+                            : entry),
+                        next: key === null ? model.next + 1 : model.next,
+                    };
+                    if (same(route, current(opened).route))
+                        return {
+                            model: opened,
+                            command: kept
+                                ? write({
+                                    url: `${withBase(url)}${hash ? `#${hash}` : ''}`,
+                                    key: current(opened).key,
+                                    replace: true,
+                                })
+                                : writing(opened, true),
+                        };
+                    return toward(opened, route, 'load', now);
+                }
+                // A URL the app did not write this page load: typed in, a link from
+                // the rest of the site, or an entry from before a reload, whose key
+                // it keeps.
+                return toward(model, route, 'arrive', now, {
+                    key,
+                    ...(hash ? { said: { hash } } : {}),
+                });
+            },
+            Attached: ({ session }, { model }) => ({
+                model: { ...model, attached: true, session },
+            }),
+            Left: ({ url }) => ({
+                command: leave({ url }),
+            }),
+            // Still loading after the delay: the move lands without the data it
+            // waits on, and each new place shows it is loading, then loads it.
+            Waited: ({ id }, { model }) => {
+                const pending = model.pending;
+                if (pending?.id !== id)
+                    return {};
+                return land(model, pending.to, pending.how, {}, pending);
+            },
+            Loaded: ({ id, known, }, { model }) => {
+                const pending = model.pending;
+                if (pending?.id !== id)
+                    return {};
+                return land(model, pending.to, pending.how, known, pending);
+            },
+            Redirected: ({ id, route }, { model, at }) => {
+                const pending = model.pending;
+                if (pending?.id !== id)
+                    return {};
+                const settled = { ...model, pending: null };
+                const how = pending.how === 'back' || pending.how === 'forward'
+                    ? 'replace'
+                    : pending.how;
+                if (pending.hops < HOPS)
+                    return toward(settled, route, how, at, { hops: pending.hops + 1 });
+                return land(settled, notFound(pending.to), how, {});
+            },
+            Reloaded: (_, { model }) => reloading(model),
+            Preloading: ({ route }, { model }) => 
+            // The page shown, or the move held, is loading it already.
+            same(route, shown(model)) ||
+                (model.pending !== null && same(route, model.pending.to))
+                ? {}
+                : { command: preload({ route }) },
+            PlaceLoaded: (message, { model }) => ({ model: { ...model, data: settle(model.data, message) } }),
+            PlaceFailed: (message, { model }) => ({ model: { ...model, data: settle(model.data, message) } }),
+            // A Loader's Redirect for a page on screen replaces the entry.
+            PlaceRedirected: ({ route }, { model, at }) => toward(model, route, 'replace', at),
+            // A Loader's Redirect out of the app: the move it ends, if any, is
+            // dropped, and the URL takes the entry's place. In memory, nothing is
+            // left.
+            RedirectedAway: ({ href, id }, { model }) => ({
+                model: id !== undefined && model.pending?.id === id
+                    ? { ...model, pending: null }
+                    : model,
+                command: leave({ url: href, replace: true }),
+            }),
+        },
+        workers: {
+            // Loads the data of each place on screen whose data is due.
+            place: {
+                each: ({ model }) => dueRuns(routes, shown(model), model.data, model.reload),
+                run: (self, run) => loadPlace(routes, run, {
+                    send: self.send,
+                    get: Effect.map(self.get, ({ model }) => ({
+                        route: shown(model),
+                        holding: model.data,
+                        reload: model.reload,
+                    })),
+                    now: self.now,
+                }),
+            },
+            // Loads the data the pending move wants; a newer move stops it.
+            load: {
+                each: ({ model }) => model.pending ? [String(model.pending.id)] : [],
+                run: (self) => Effect.gen(function* () {
+                    const { pending } = (yield* self.get).model;
+                    if (pending)
+                        yield* load(pending, self.send);
+                }),
+            },
+            // Lands a move still loading after the delay.
+            wait: {
+                each: ({ model }) => model.pending ? [String(model.pending.id)] : [],
+                run: (self) => Effect.gen(function* () {
+                    const { pending } = (yield* self.get).model;
+                    if (!pending)
+                        return;
+                    const now = yield* self.now;
+                    yield* Effect.sleep(Math.max(0, pending.since + delay - now));
+                    yield* self.send({ _tag: 'Waited', id: pending.id });
+                }),
+            },
+            // Keeps what the pages drawn first were handed, as a server's page
+            // hands them, in the Data cache: Back to them is at once, as to a
+            // page loaded in the browser.
+            keep: {
+                run: (self) => Effect.gen(function* () {
+                    const found = yield* Effect.serviceOption(Loading);
+                    if (Option.isNone(found) || !found.value.keep)
+                        return;
+                    const { model } = yield* self.get;
+                    if (model.move.how !== 'load')
+                        return;
+                    for (const { name, params, input } of routes.places(shown(model))) {
+                        const status = model.data[name]?.status;
+                        // Arrived when the page says, so the copy goes stale when
+                        // the page says it does.
+                        if (input && status?._tag === 'Ready')
+                            yield* found.value.keep({ name, params }, status.data, status.info.arrivedAt);
+                    }
+                }),
+            },
+            // Hears the address, if an Adapter holds one: Back, Forward, a typed URL.
+            address: {
+                run: (self) => Effect.gen(function* () {
+                    const found = yield* Effect.serviceOption(Adapter);
+                    if (Option.isNone(found))
+                        return;
+                    const at = found.value;
+                    if (!(yield* self.get).model.attached)
+                        yield* self.send({
+                            _tag: 'Attached',
+                            session: Math.random().toString(36).slice(2, 10),
+                        });
+                    const changes = Stream.callback((queue) => Effect.acquireRelease(Effect.sync(() => {
+                        Queue.offerUnsafe(queue, null);
+                        return at.listen(() => void Queue.offerUnsafe(queue, null));
+                    }), (stop) => Effect.sync(stop)));
+                    yield* Stream.runForEach(changes, () => Effect.gen(function* () {
+                        const url = inside(at.url());
+                        if (url === undefined)
+                            return;
+                        const { model } = yield* self.get;
+                        const entry = current(model);
+                        const target = model.pending?.to;
+                        // The Router's own write coming back, or the address of a move still loading: nothing moved.
+                        if (at.key() === entry.key && shows(url, entry.route))
+                            return;
+                        if (target && url === routes.path(target))
+                            return;
+                        yield* self.send({
+                            _tag: 'Arrived',
+                            route: routes.read(url).route,
+                            key: at.key(),
+                            url,
+                            hash: at.hash?.() ?? '',
+                        });
+                    }));
+                }),
+            },
+        },
+    });
+    const routerView = View.make(built, (self) => {
+        const model = self.model;
+        const send = self.send;
+        const onClick = (event) => {
+            const link = linkOf(event);
+            if (!link)
+                return;
+            const url = new URL(link.href);
+            if (url.origin !== location.origin)
+                return;
+            const target = `${url.pathname}${url.search}`;
+            // A link to a spot on this page is the browser's to scroll to.
+            if (url.hash && target === `${location.pathname}${location.search}`)
+                return;
+            const within = inside(target);
+            if (within === undefined) {
+                // Outside the app: the Adapter hands it on; in memory, the browser goes.
+                if (!model.attached)
+                    return;
+                event.preventDefault();
+                send({ _tag: 'Left', url: target });
+                return;
+            }
+            event.preventDefault();
+            send({
+                _tag: 'Pushed',
+                route: routes.read(within).route,
+                ...linkOptions(link, url),
+            });
+        };
+        const drawn = shown(model);
+        // The Metadata follows the data of the pages drawn, not only the move.
+        const metadata = routes.metadata(drawn, readyOf(shownOf(routes, drawn, model.data, model.reload)));
+        return (_jsx(Frame, { drawing: {
+                href: href,
+                entries: model.entries,
+                at: model.at,
+                move: model.move,
+                pending: model.pending
+                    ? {
+                        to: model.pending.to,
+                        how: model.pending.how === 'arrive' ? 'push' : model.pending.how,
+                    }
+                    : null,
+                metadata,
+                go: (by) => send({ _tag: 'Went', by }),
+                reload: () => send({ _tag: 'Reloaded' }),
+                preload: (route) => send({ _tag: 'Preloading', route: route }),
+                linkPreload: routes.options.preload,
+            }, attached: model.attached, root: self.root, onClick: onClick, children: _jsx(Scrolling, { options: scrolling, at: {
+                    route: drawn,
+                    path: routes.path(drawn),
+                    key: current(model).key,
+                }, hash: current(model).hash, move: model.move, pending: model.pending !== null, attached: model.attached, loaded: model.loaded, children: (() => {
+                    const RootView = view;
+                    return (_jsx(RootView, { instance: self.children
+                            .page }));
+                })() }) }));
+    });
+    /**
+     * The Router's Input at a URL, with what its places already start from:
+     * for `toReact`'s `input`, so an app on an Adapter is drawn at the right
+     * page from the first frame, and for a server, which draws a URL from what
+     * its Loaders gave. With no URL, the browser's, if there is one. Places
+     * that start from nothing load once the Runtime starts.
+     */
+    const startAt = (url, known) => {
+        const at = url ??
+            (typeof location === 'undefined'
+                ? undefined
+                : `${location.pathname}${location.search}`);
+        if (at === undefined)
+            return undefined;
+        const within = inside(at);
+        if (within === undefined)
+            return undefined;
+        const route = routes.read(within).route;
+        return known ? { route, known } : { route };
+    };
+    /** A key the Router never gives: what a custom key gives back when it keeps the entry's own. */
+    const ENTRY = '\u0000entry';
+    /**
+     * The script a server writes in a page at `route`, run before the app
+     * hydrates, that puts its scroll back from the tab's session storage, as
+     * TanStack Start's does; `null` where scroll restoration is off.
+     */
+    const restoreScroll = (route) => {
+        if (!restores(scrolling, route))
+            return null;
+        const key = keyOf(scrolling, {
+            route,
+            path: routes.path(route),
+            key: ENTRY,
+        });
+        return scriptFor(KEY, key === ENTRY ? undefined : key);
+    };
+    return {
+        actor: built,
+        view: routerView,
+        startAt,
+        href,
+        restoreScroll,
+        /** The Routes it serves: what Start reads a URL and serves the Loaders with. */
+        routes,
+    };
+};