@hearthlog/runtime 0.0.0-stage → 0.1.0

package/src/pwa/registration.ts

@@ -0,0 +1,169 @@
+import {
+    checkOfflineReadiness,
+    markOfflineReadinessFailed,
+    markOfflineReadinessInstalling,
+} from '../store/offline-readiness.svelte.js';
+import { notify, type NotificationAction } from '@hearthlog/ui/state/notifications.svelte.js';
+
+const BOOTSTRAP_WAIT_MS = 3_000;
+const IDLE_WAIT_MS = 1_000;
+const UPDATE_CHECK_INTERVAL_MS = 60 * 60 * 1_000;
+
+type RegisterPwa = () => void | Promise<void>;
+
+export interface PwaRegistrationSchedulerDependencies {
+    register: RegisterPwa;
+    setTimeout: typeof globalThis.setTimeout;
+    clearTimeout: typeof globalThis.clearTimeout;
+    requestIdleCallback?: (
+        callback: () => void,
+        options: { timeout: number },
+    ) => number;
+    requestAnimationFrame?: (callback: () => void) => number;
+}
+
+type PwaUpdateNotifier = (
+    message: string,
+    action?: NotificationAction,
+) => unknown;
+
+export function createPwaUpdatePrompt(
+    notifyInfo: PwaUpdateNotifier,
+    reload: () => void,
+): () => void {
+    let shown = false;
+
+    return () => {
+        if (shown) return;
+        shown = true;
+        notifyInfo('A new version of the app is available.', {
+            label: 'Reload',
+            run: reload,
+        });
+    };
+}
+
+function waitForBootstrap(
+    bootstrapPromise: Promise<unknown>,
+    dependencies: PwaRegistrationSchedulerDependencies,
+): Promise<void> {
+    return new Promise((resolve) => {
+        let finished = false;
+        const finish = () => {
+            if (finished) return;
+            finished = true;
+            dependencies.clearTimeout(timeoutId);
+            resolve();
+        };
+        const timeoutId = dependencies.setTimeout(finish, BOOTSTRAP_WAIT_MS);
+        void bootstrapPromise.then(finish, finish);
+    });
+}
+
+function waitForIdle(dependencies: PwaRegistrationSchedulerDependencies): Promise<void> {
+    return new Promise((resolve) => {
+        if (dependencies.requestIdleCallback) {
+            dependencies.requestIdleCallback(resolve, { timeout: IDLE_WAIT_MS });
+            return;
+        }
+        if (dependencies.requestAnimationFrame) {
+            dependencies.requestAnimationFrame(resolve);
+            return;
+        }
+        resolve();
+    });
+}
+
+export function createPwaRegistrationScheduler(
+    dependencies: PwaRegistrationSchedulerDependencies,
+): (bootstrapPromise: Promise<unknown>) => Promise<void> {
+    let scheduled: Promise<void> | null = null;
+
+    return (bootstrapPromise) => {
+        scheduled ??= waitForBootstrap(bootstrapPromise, dependencies)
+            .then(() => waitForIdle(dependencies))
+            .then(() => dependencies.register());
+        return scheduled;
+    };
+}
+
+async function registerPwa(): Promise<void> {
+    if (typeof window === 'undefined' || !('serviceWorker' in navigator)) return;
+
+    markOfflineReadinessInstalling();
+
+    try {
+        const showUpdatePrompt = createPwaUpdatePrompt(
+            notify.info,
+            () => window.location.reload(),
+        );
+        const handleWorkerActivated = () => {
+            showUpdatePrompt();
+            void checkOfflineReadiness();
+        };
+
+        // A controller present before registration means any new worker is an
+        // update; otherwise the first install is the offline-ready moment.
+        const hadController = Boolean(navigator.serviceWorker.controller);
+        const registration = await navigator.serviceWorker.register('/service-worker.js', {
+            type: 'module',
+            scope: '/',
+        });
+
+        registration.addEventListener('updatefound', () => {
+            const worker = registration.installing;
+            worker?.addEventListener('statechange', () => {
+                if (worker.state !== 'activated') return;
+                if (hadController) handleWorkerActivated();
+                else void checkOfflineReadiness();
+            });
+        });
+        scheduleServiceWorkerUpdateChecks(registration);
+        void navigator.serviceWorker.ready.then(() => checkOfflineReadiness());
+
+        // The replacement worker claims this page immediately. The current
+        // document already has its chunks in memory, so let the user choose
+        // when to reload after the replacement worker has activated.
+        navigator.serviceWorker.addEventListener('controllerchange', () => {
+            void checkOfflineReadiness();
+        }, { once: true });
+    } catch (error) {
+        markOfflineReadinessFailed(error);
+    }
+}
+
+function scheduleServiceWorkerUpdateChecks(registration: ServiceWorkerRegistration): void {
+    const checkForUpdate = () => {
+        if (!navigator.onLine || document.visibilityState !== 'visible') return;
+        void registration.update().catch((error) => {
+            console.debug('[PWA] Service worker update check failed:', error);
+        });
+    };
+
+    window.setInterval(checkForUpdate, UPDATE_CHECK_INTERVAL_MS);
+    document.addEventListener('visibilitychange', checkForUpdate);
+    window.addEventListener('online', checkForUpdate);
+}
+
+const requestIdleCallback = typeof window !== 'undefined'
+    ? (window as Window & {
+          requestIdleCallback?: (
+              callback: () => void,
+              options: { timeout: number },
+          ) => number;
+      }).requestIdleCallback?.bind(window)
+    : undefined;
+
+const scheduleRegistration = createPwaRegistrationScheduler({
+    register: registerPwa,
+    setTimeout: globalThis.setTimeout.bind(globalThis),
+    clearTimeout: globalThis.clearTimeout.bind(globalThis),
+    requestIdleCallback,
+    requestAnimationFrame: typeof window !== 'undefined'
+        ? window.requestAnimationFrame.bind(window)
+        : undefined,
+});
+
+export function schedulePwaRegistration(bootstrapPromise: Promise<unknown>): Promise<void> {
+    return scheduleRegistration(bootstrapPromise);
+}

package/src/recovery/local-recovery.ts

@@ -0,0 +1,59 @@
+import { bootstrapLocalStore, type LocalStoreBootstrapResult } from '../db/bootstrap.js';
+import { db, requireActiveContext, sqlocalDb } from '../db/index.js';
+import { shutdownSynchronization } from '../store/sync.svelte.js';
+import { executeLocalReset, type ResetDependencies } from './reset-sequence.js';
+
+export type { ResetDependencies } from './reset-sequence.js';
+
+export interface LocalRecoverySummary {
+    pending: number | null;
+    blocked: number | null;
+}
+
+export async function getLocalRecoverySummary(): Promise<LocalRecoverySummary> {
+    try {
+        const context = await requireActiveContext();
+        const [pending, blocked] = await Promise.all([
+            db.selectFrom('raw_events').select((eb) => eb.fn.count('id').as('count'))
+                .where('tenant_id', '=', context.tenantId).where('log_id', '=', context.logId)
+                .where('sync_state', 'in', ['pending', 'conflicted']).executeTakeFirst(),
+            db.selectFrom('outbox_operations').select((eb) => eb.fn.count('id').as('count'))
+                .where('tenant_id', '=', context.tenantId).where('log_id', '=', context.logId)
+                .where('status', '=', 'needs_attention').executeTakeFirst(),
+        ]);
+        return { pending: Number(pending?.count ?? 0), blocked: Number(blocked?.count ?? 0) };
+    } catch {
+        return { pending: null, blocked: null };
+    }
+}
+
+export async function getLocalDatabaseFile(): Promise<Blob> {
+    return await sqlocalDb.getDatabaseFile() as unknown as Blob;
+}
+
+export async function downloadLocalDatabase(): Promise<void> {
+    const file = await getLocalDatabaseFile();
+    const url = URL.createObjectURL(file);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = `stor-${new Date().toISOString().slice(0, 10)}.sqlite3`;
+    document.body.appendChild(link);
+    link.click();
+    link.remove();
+    URL.revokeObjectURL(url);
+}
+
+export function retryLocalMigration(): Promise<LocalStoreBootstrapResult> {
+    return bootstrapLocalStore();
+}
+
+export async function resetLocalDataFromLedger(
+    dependencies: ResetDependencies = {
+        stopSynchronization: shutdownSynchronization,
+        deleteDatabase: () => sqlocalDb.deleteDatabaseFile(),
+        markReset: () => sessionStorage.setItem('databaseReset', 'true'),
+        hardReload: () => location.reload(),
+    },
+): Promise<void> {
+    await executeLocalReset(dependencies);
+}

package/src/recovery/reset-sequence.ts

@@ -0,0 +1,13 @@
+export interface ResetDependencies {
+    stopSynchronization: () => Promise<void>;
+    deleteDatabase: () => Promise<void>;
+    markReset: () => void;
+    hardReload: () => void;
+}
+
+export async function executeLocalReset(dependencies: ResetDependencies): Promise<void> {
+    await dependencies.stopSynchronization();
+    dependencies.markReset();
+    await dependencies.deleteDatabase();
+    dependencies.hardReload();
+}

package/src/runtime/clock.ts

@@ -0,0 +1,43 @@
+import { invalidateAll } from '$app/navigation';
+import { isSameDay, startOfTomorrow } from 'date-fns';
+import { advanceReadTargetClock } from './read-coordinator.js';
+import { appClock } from './view.js';
+
+/**
+ * Keeps the workspace clock current while a tab stays open: it advances when
+ * the tab becomes visible and at local midnight, and pages reload their data
+ * when the date changes so "today" moves with it.
+ */
+export function startWorkspaceClock(): () => void {
+    let midnight: ReturnType<typeof setTimeout> | undefined;
+
+    async function advance(): Promise<void> {
+        const previous = appClock.now();
+        const now = new Date();
+        if (!await advanceReadTargetClock(now)) return;
+        if (!isSameDay(previous, now)) await invalidateAll();
+    }
+
+    function scheduleMidnight(): void {
+        clearTimeout(midnight);
+        // A second past midnight, so the new date is certain.
+        midnight = setTimeout(() => {
+            void advance();
+            scheduleMidnight();
+        }, startOfTomorrow().getTime() - Date.now() + 1_000);
+    }
+
+    function handleVisibility(): void {
+        if (document.visibilityState !== 'visible') return;
+        void advance();
+        // Timers in hidden tabs are throttled; re-arm from the real time.
+        scheduleMidnight();
+    }
+
+    document.addEventListener('visibilitychange', handleVisibility);
+    scheduleMidnight();
+    return () => {
+        clearTimeout(midnight);
+        document.removeEventListener('visibilitychange', handleVisibility);
+    };
+}

package/src/runtime/kept-page-data.svelte.ts

@@ -0,0 +1,42 @@
+import { untrack } from 'svelte';
+import type { PageResource } from './page-data.svelte.js';
+
+/**
+ * The data a page last showed, kept on screen while the next load runs, so a
+ * save or a change of address swaps the page atomically instead of flashing
+ * skeletons. Skeletons show only before the first paint. Call it while the
+ * component initialises.
+ */
+export function keepPageData<T>(resource: () => PageResource<T>) {
+    let kept = $state.raw<T | null>(null);
+    /** Counts applied loads; endless lists read the blocks on screen again when it changes. */
+    let revision = $state(0);
+
+    $effect(() => {
+        const current = resource();
+        if (current.loading) return;
+        const next = current.data;
+        untrack(() => {
+            kept = next;
+            revision += 1;
+        });
+    });
+
+    return {
+        get data(): T {
+            return kept ?? resource().data;
+        },
+        /** True only until the first load has been applied. */
+        get loading(): boolean {
+            return kept === null && resource().loading;
+        },
+        get revision(): number {
+            return revision;
+        },
+        /** What `providePageResource` hands to `CommandOnly`, `DataValue` and `PageDataStatus`. */
+        get display(): { loading: boolean; error: unknown; measurement: PageResource<T>['measurement'] } {
+            const current = resource();
+            return { loading: kept === null && current.loading, error: current.error, measurement: current.measurement };
+        },
+    };
+}

package/src/runtime/page-data.svelte.ts

@@ -0,0 +1,160 @@
+import type { LoadEvent } from '@sveltejs/kit';
+import { get } from 'svelte/store';
+import { workspaceReadiness } from '@hearthlog/ui/state/readiness.js';
+import { recordTiming, measurementMetadata, getNavigationTiming } from '../utils/perf.js';
+import type { WorkspaceTicket } from './workspace.js';
+
+type RouteEvent = Pick<LoadEvent, 'url' | 'params' | 'depends' | 'parent'>;
+export type PagePublisher<T> = (update: Partial<T>, region?: string) => void;
+type Measurement = { id: string; navigationId: string; kind: 'startup' | 'navigation' | 'refresh'; start: number; finish: () => void };
+const pendingRenders = new Set<Promise<void>>();
+let activeResource: PageResource<any> | undefined;
+let hasRenderedPage = false;
+
+export class PageResource<T> {
+    value = $state.raw<T>();
+    error = $state.raw<unknown>(null);
+    pending = $state(true);
+    revision = $state(0);
+    scope = $state('');
+    promise!: Promise<T>;
+    measurement = $state.raw<Measurement>(undefined!);
+    #request = 0;
+    #recordedMeasurement = '';
+    #readiness = $state(get(workspaceReadiness));
+    #unsubscribe?: () => void;
+    #partial = $state.raw<Partial<T>>({});
+    #partialScope = $state('');
+    #regions = $state.raw(new Set<string>());
+
+    constructor(public key: string, readonly route: string, readonly initial: T, readonly requiresWorkspace = true) {}
+
+    get usable(): boolean {
+        return this.value !== undefined && (!this.requiresWorkspace || (this.#readiness.ready && this.scope === this.#readiness.key));
+    }
+    get data(): T {
+        if (this.usable) return this.value!;
+        return this.#readiness.ready && this.#partialScope === this.#readiness.key
+            ? { ...this.initial, ...this.#partial } : this.initial;
+    }
+    get loading(): boolean { return !this.usable; }
+    get refreshing(): boolean { return this.usable && this.pending; }
+    isRegionLoading(region: string): boolean {
+        return !this.usable && !(this.#readiness.ready && this.#partialScope === this.#readiness.key && this.#regions.has(region));
+    }
+
+    attach(): () => void {
+        this.#unsubscribe?.();
+        this.#unsubscribe = workspaceReadiness.subscribe((state) => this.#readiness = state);
+        return () => {
+            this.#unsubscribe?.();
+            this.measurement.finish();
+        };
+    }
+
+    load(callback: (publish: PagePublisher<T>) => Promise<T>): void {
+        const request = ++this.#request;
+        this.measurement?.finish();
+        let finish!: () => void;
+        const rendered = new Promise<void>((resolve) => finish = resolve);
+        pendingRenders.add(rendered);
+        void rendered.then(() => pendingRenders.delete(rendered));
+        const navigation = getNavigationTiming();
+        const kind = this.value !== undefined ? 'refresh' : navigation.start || hasRenderedPage ? 'navigation' : 'startup';
+        this.measurement = {
+            id: crypto.randomUUID(),
+            navigationId: navigation.id,
+            kind,
+            start: kind === 'startup' ? 0 : kind === 'navigation' ? navigation.start || performance.now() : performance.now(),
+            finish,
+        };
+        this.pending = true;
+        this.error = null;
+        this.#partial = {};
+        this.#regions = new Set();
+        this.promise = callback((update, region) => {
+            if (request !== this.#request || activeResource !== this) return;
+            this.#partialScope = get(workspaceReadiness).key;
+            this.#partial = { ...this.#partial, ...update };
+            if (region) this.#regions = new Set([...this.#regions, region]);
+        }).then((value) => {
+            if (request !== this.#request || activeResource !== this) return value;
+            this.scope = get(workspaceReadiness).key;
+            if (this.requiresWorkspace) this.key = `${this.scope}:${this.route}`;
+            this.value = value;
+            this.pending = false;
+            this.revision += 1;
+            return value;
+        }).catch((error) => {
+            if (request === this.#request) {
+                this.error = error;
+                this.pending = false;
+                finish();
+            }
+            throw error;
+        });
+        void this.promise.catch(() => undefined);
+    }
+
+    rendered(measurement: Measurement): void {
+        if (measurement !== this.measurement || this.pending || !this.usable || this.error || this.#recordedMeasurement === measurement.id) return;
+        this.#recordedMeasurement = measurement.id;
+        recordTiming(measurement.kind === 'startup' ? 'startup' : 'ui', 'pageContentReady', performance.now() - measurement.start, {
+            ...measurementMetadata(), baselineMetric: 'pageContentReady', route: this.route,
+            navigationId: measurement.navigationId, loadId: measurement.id, kind: measurement.kind, outcome: 'success',
+        });
+        hasRenderedPage = true;
+        measurement.finish();
+    }
+}
+
+/** Load functions finish immediately; only their resource waits for local data. */
+export function deferPage<T>(event: RouteEvent, initial: NoInfer<T>, loader: (publish: PagePublisher<NoInfer<T>>) => Promise<T>): { pageResource: PageResource<T> } {
+    // Snapshot tracked URL properties before deferring work. Action-only queries
+    // must not discard a loaded page or an open drawer.
+    const url = new URL(event.url.href);
+    for (const key of [...url.searchParams.keys()]) {
+        if (key.startsWith('new')) url.searchParams.delete(key);
+    }
+    const route = `${url.pathname}${url.search}`;
+    const key = `${get(workspaceReadiness).key}:${route}`;
+    if (activeResource?.key !== key) {
+        activeResource?.measurement.finish();
+        activeResource = new PageResource<T>(key, route, initial);
+    }
+    const resource = activeResource as PageResource<T>;
+    // parent() itself is immediate; never await the parent's deferred payload
+    // before returning from a load function.
+    const parent = event.parent() as Promise<{ workspace: WorkspaceTicket }>;
+    resource.load(async (publish) => {
+        const data = await parent;
+        await data.workspace.ready;
+        const scope = get(workspaceReadiness).key;
+        const result = await loader((update, region) => {
+            if (scope === get(workspaceReadiness).key) publish(update, region);
+        });
+        if (scope !== get(workspaceReadiness).key) throw new DOMException('Workspace changed', 'AbortError');
+        return result;
+    });
+    return { pageResource: resource };
+}
+
+/** Wait for data AND its visible consumer, rather than merely invalidate(). */
+export async function waitForPageUpdates(): Promise<void> {
+    while (pendingRenders.size) await Promise.all([...pendingRenders]);
+    if (activeResource?.error) throw activeResource.error;
+}
+
+export { providePageResource } from '@hearthlog/ui/state/page-context.js';
+
+export function deferLocalPage<T>(url: URL, initial: NoInfer<T>, loader: () => Promise<T>): { pageResource: PageResource<T> } {
+    const route = `${url.pathname}${url.search}`;
+    const key = `local:${route}`;
+    if (activeResource?.key !== key) {
+        activeResource?.measurement.finish();
+        activeResource = new PageResource<T>(key, route, initial, false);
+    }
+    const resource = activeResource as PageResource<T>;
+    resource.load(loader);
+    return { pageResource: resource };
+}

package/src/runtime/phone-header.svelte.ts

@@ -0,0 +1,17 @@
+import type { Snippet } from 'svelte';
+
+/**
+ * What the page puts in the phone top bar (below 768 px): one glance figure
+ * that opens the page's summary sheet, an optional context line such as the
+ * day in view, and whether the bar needs the log button's room. The shell
+ * owns the bar; `PhoneGlance` fills these while its page is mounted.
+ */
+class PhoneHeader {
+    glance = $state<Snippet | null>(null);
+    context = $state<string | null>(null);
+    hideLog = $state(false);
+    /** While rows are being selected the bar names the count and offers Select all and Cancel. */
+    selection = $state<{ label: string; onSelectAll?: () => void; onCancel: () => void } | null>(null);
+}
+
+export const phoneHeader = new PhoneHeader();

package/src/runtime/read-coordinator.ts

@@ -0,0 +1,103 @@
+import { beginWorkspaceTransition, completeWorkspaceTransition, failWorkspaceTransition } from '@hearthlog/ui/state/readiness.js';
+import { db, requireActiveContext } from '../db/index.js';
+import type { Kysely } from 'kysely';
+import {
+    beginApplicationViewTransition,
+    cancelApplicationViewTransition,
+    updateApplicationView,
+} from './view.js';
+import { createReadModelSession, type ReadModelDatabase, type ReadModelSession, type ReadScope, type ReadView } from '../db/read-session.js';
+
+type ActiveReadTarget = { scope: ReadScope; view: ReadView };
+type CoordinatorState = {
+    activeTarget: ActiveReadTarget | null;
+    activationQueue: Promise<void>;
+    waiters: Array<{ resolve: (target: ActiveReadTarget) => void; reject: (error: unknown) => void }>;
+    error: unknown;
+    transitioning: boolean;
+};
+
+const globalForCoordinator = globalThis as unknown as { storReadCoordinator?: CoordinatorState };
+const coordinatorState = globalForCoordinator.storReadCoordinator ?? {
+    activeTarget: null,
+    activationQueue: Promise.resolve(),
+    waiters: [],
+    error: null,
+    transitioning: false,
+};
+globalForCoordinator.storReadCoordinator = coordinatorState;
+
+export async function activateCurrentReadTarget(now = new Date()): Promise<void> {
+    const context = await requireActiveContext();
+    const scope = { tenantId: context.tenantId, logId: context.logId };
+    const view = { effectiveNow: now.toISOString() };
+    const activation = coordinatorState.activationQueue.then(() => {
+        coordinatorState.activeTarget = { scope, view };
+        coordinatorState.transitioning = false;
+        coordinatorState.error = null;
+        completeWorkspaceTransition(JSON.stringify([scope.tenantId, scope.logId]));
+        for (const waiter of coordinatorState.waiters.splice(0)) waiter.resolve(coordinatorState.activeTarget);
+        updateApplicationView({ effectiveNow: view.effectiveNow });
+    });
+    coordinatorState.activationQueue = activation.catch(() => undefined);
+    await activation;
+}
+
+/**
+ * Moves the active read target's clock forward. A log transition in progress
+ * sets its own clock when it activates, so it is left alone.
+ */
+export async function advanceReadTargetClock(now = new Date()): Promise<boolean> {
+    let advanced = false;
+    const advance = coordinatorState.activationQueue.then(() => {
+        const target = coordinatorState.activeTarget;
+        if (!target || coordinatorState.transitioning) return;
+        const view = { effectiveNow: now.toISOString() };
+        coordinatorState.activeTarget = { scope: target.scope, view };
+        updateApplicationView(view);
+        advanced = true;
+    });
+    coordinatorState.activationQueue = advance.catch(() => undefined);
+    await advance;
+    return advanced;
+}
+
+export async function runActiveRead<T>(callback: (session: ReadModelSession) => Promise<T>): Promise<T> {
+    const target = coordinatorState.activeTarget && !coordinatorState.transitioning
+        ? coordinatorState.activeTarget
+        : await waitForActiveTarget();
+    return callback(createReadModelSession(db as unknown as Kysely<ReadModelDatabase>, {
+        schema: 'main', scope: target.scope, view: target.view,
+    }));
+}
+
+export function beginReadTargetTransition(): void {
+    coordinatorState.error = null;
+    beginWorkspaceTransition();
+    coordinatorState.transitioning = true;
+    beginApplicationViewTransition();
+}
+
+export function cancelReadTargetTransition(): void {
+    coordinatorState.transitioning = false;
+    cancelApplicationViewTransition();
+    if (!coordinatorState.activeTarget) return;
+    const { scope } = coordinatorState.activeTarget;
+    completeWorkspaceTransition(JSON.stringify([scope.tenantId, scope.logId]));
+    for (const waiter of coordinatorState.waiters.splice(0)) waiter.resolve(coordinatorState.activeTarget);
+}
+
+export function failReadTargetTransition(error: unknown): void {
+    coordinatorState.error = error;
+    coordinatorState.transitioning = true;
+    failWorkspaceTransition(error);
+    for (const waiter of coordinatorState.waiters.splice(0)) waiter.reject(error);
+}
+
+function waitForActiveTarget(): Promise<ActiveReadTarget> {
+    if (coordinatorState.error) return Promise.reject(coordinatorState.error);
+    if (coordinatorState.activeTarget && !coordinatorState.transitioning) {
+        return Promise.resolve(coordinatorState.activeTarget);
+    }
+    return new Promise((resolve, reject) => coordinatorState.waiters.push({ resolve, reject }));
+}

package/src/runtime/refresh.ts

@@ -0,0 +1,15 @@
+import { invalidate } from '$app/navigation';
+import { waitForPageUpdates } from './page-data.svelte.js';
+import { measurementMetadata, withTiming } from '../utils/perf.js';
+
+/** Public refreshes include both deferred queries and the resulting paint. */
+export async function refreshPageData(...targets: string[]): Promise<void> {
+    await withTiming('ui', 'refreshPage', async () => {
+        await Promise.all(targets.map(target => invalidate(target)));
+        await waitForPageUpdates();
+    }, {
+        ...measurementMetadata(), kind: 'refresh', baselineMetric: 'invalidationCost',
+        route: typeof location === 'undefined' ? '' : `${location.pathname}${location.search}`,
+        targetCount: targets.length,
+    });
+}

package/src/runtime/start-page.ts

@@ -0,0 +1,56 @@
+import { buildNavigation } from '@hearthlog/contracts/features/navigation';
+import { DEVELOPER_PATH, ENTITIES_PATH, featureForPath } from '@hearthlog/contracts/features/registry';
+import type { TenantConfig } from '@hearthlog/contracts/tenant/config';
+
+function storageKey(tenantId: string): string {
+    return `stor:last-section:${tenantId}`;
+}
+
+/** Keep only the feature's entry page, never a date, filter, or drawer. */
+export function sectionForPath(pathname: string, tenant: TenantConfig): string | null {
+    if (pathname === DEVELOPER_PATH && tenant.developerNavVisible) return DEVELOPER_PATH;
+    if (pathname === ENTITIES_PATH || pathname.startsWith(`${ENTITIES_PATH}/`)) {
+        return tenant.entitiesNavVisible ? ENTITIES_PATH : null;
+    }
+
+    const feature = featureForPath(pathname);
+    if (!feature || !tenant.features.has(feature.id)) return null;
+    return feature.page?.path ?? null;
+}
+
+export function defaultSection(tenant: TenantConfig): string {
+    const configured = sectionForPath(tenant.home, tenant);
+    if (configured) return configured;
+    return buildNavigation(tenant).destinations[0]?.path ?? DEVELOPER_PATH;
+}
+
+export function startSection(tenant: TenantConfig, storage: Pick<Storage, 'getItem'> | null): string {
+    try {
+        const saved = storage?.getItem(storageKey(tenant.id));
+        if (saved) {
+            const section = sectionForPath(saved, tenant);
+            if (section) return section;
+        }
+    } catch {
+        // A blocked browser store still has a usable start route.
+    }
+    return defaultSection(tenant);
+}
+
+export function startTarget(_url: URL, tenant: TenantConfig, storage: Pick<Storage, 'getItem'> | null): string {
+    return startSection(tenant, storage);
+}
+
+export function rememberSection(
+    url: { pathname: string },
+    tenant: TenantConfig,
+    storage: Pick<Storage, 'setItem'> | null,
+): void {
+    const section = sectionForPath(url.pathname, tenant);
+    if (!section) return;
+    try {
+        storage?.setItem(storageKey(tenant.id), section);
+    } catch {
+        // Navigation remains usable when browser storage is unavailable.
+    }
+}