@satinhq/kit 0.0.0-stage → 0.1.0-beta.0

package/dist/focus/focusIntentMachine.js

@@ -0,0 +1,359 @@
+function assertIdentifier(value, label) {
+    if (value.trim().length === 0) {
+        throw new Error(`Focus intent ${label} must not be empty.`);
+    }
+}
+function assertScopeDefinition(scope) {
+    assertIdentifier(scope.key, 'scope key');
+    assertIdentifier(scope.initialTarget, `initial target for "${scope.key}"`);
+    assertIdentifier(scope.title, `title for "${scope.key}"`);
+}
+function createScopeState(scope) {
+    assertScopeDefinition(scope);
+    return {
+        ...scope,
+        failed: false,
+        focusTarget: scope.initialTarget,
+        ready: scope.readiness === 'ready',
+    };
+}
+function scopeLocation(scope) {
+    return { scopeKey: scope.key, target: scope.focusTarget };
+}
+function initialLocation(scope) {
+    return { scopeKey: scope.key, target: scope.initialTarget };
+}
+function findScope(state, scopeKey) {
+    return (state.presentations.find(scope => scope.key === scopeKey) ??
+        state.routes.find(scope => scope.key === scopeKey));
+}
+function assertUniqueScopeKey(state, scopeKey) {
+    if (findScope(state, scopeKey)) {
+        throw new Error(`Focus intent scope "${scopeKey}" already exists.`);
+    }
+}
+function assertUniqueTransitionId(state, transitionId) {
+    assertIdentifier(transitionId, 'transition id');
+    if (state.transitions.some(transition => transition.id === transitionId)) {
+        throw new Error(`Focus intent transition "${transitionId}" already exists.`);
+    }
+}
+function withoutPending(state) {
+    if (!state.pending)
+        return state;
+    return { ...state, pending: undefined };
+}
+function finishTransitions(state, transitionIds) {
+    if (transitionIds.size === 0)
+        return state;
+    const routes = state.routes.flatMap((route) => {
+        if (!route.transitionId || !transitionIds.has(route.transitionId))
+            return [route];
+        if (route.phase === 'exiting')
+            return [];
+        return [{ ...route, phase: 'settled', transitionId: undefined }];
+    });
+    return {
+        ...state,
+        pending: undefined,
+        routes,
+        transitions: state.transitions.filter(transition => !transitionIds.has(transition.id)),
+    };
+}
+function cancelTransition(state, transitionId) {
+    const routes = state.routes.flatMap((route) => {
+        if (route.transitionId !== transitionId)
+            return [route];
+        if (route.phase === 'entering')
+            return [];
+        return [{ ...route, phase: 'settled', transitionId: undefined }];
+    });
+    return {
+        ...state,
+        pending: undefined,
+        routes,
+        transitions: state.transitions.filter(transition => transition.id !== transitionId),
+    };
+}
+function finishAllTransitions(state) {
+    return finishTransitions(state, new Set(state.transitions.map(transition => transition.id)));
+}
+function finishEnteringTransitions(state) {
+    const enteringIds = new Set(state.routes.flatMap(route => route.phase === 'entering' && route.transitionId ? [route.transitionId] : []));
+    return finishTransitions(state, enteringIds);
+}
+function capture(state, scopeKey, activeFocus) {
+    if (!activeFocus || activeFocus.scopeKey !== scopeKey) {
+        return { commands: [], state };
+    }
+    assertIdentifier(activeFocus.target, `active target for "${scopeKey}"`);
+    const snapshots = new Map(state.snapshots);
+    snapshots.set(scopeKey, activeFocus.target);
+    return {
+        commands: [{ location: activeFocus, type: 'capture' }],
+        state: { ...state, snapshots },
+    };
+}
+function requestFocus(state, scopeKey, kind, reason) {
+    const scope = findScope(state, scopeKey);
+    if (!scope) {
+        throw new Error(`Focus intent scope "${scopeKey}" does not exist.`);
+    }
+    if (!scope.ready) {
+        return {
+            commands: [],
+            state: { ...state, pending: { kind, reason, scopeKey } },
+        };
+    }
+    const readyState = withoutPending(state);
+    const commandReason = scope.failed ? 'error' : reason;
+    if (kind === 'restore' && !scope.failed) {
+        const snapshot = state.snapshots.get(scopeKey);
+        if (snapshot) {
+            return {
+                commands: [
+                    {
+                        fallback: initialLocation(scope),
+                        location: { scopeKey, target: snapshot },
+                        reason: commandReason,
+                        type: 'restore',
+                    },
+                ],
+                state: readyState,
+            };
+        }
+    }
+    return {
+        commands: [{ location: scopeLocation(scope), reason: commandReason, type: 'move-to' }],
+        state: readyState,
+    };
+}
+function activeRoute(state) {
+    const route = state.routes.at(-1);
+    if (!route)
+        throw new Error('Focus intent route stack must not be empty.');
+    return route;
+}
+export function activeFocusScopeKey(state) {
+    const presentation = state.presentations.at(-1);
+    if (presentation)
+        return presentation.key;
+    if (state.transitions.length > 0)
+        return undefined;
+    return activeRoute(state).key;
+}
+export function createFocusIntentState(initial) {
+    const scope = createScopeState(initial);
+    return {
+        presentations: [],
+        routes: [{ ...scope, phase: 'settled' }],
+        snapshots: new Map(),
+        transitions: [],
+    };
+}
+function beginPush(state, event) {
+    if (state.presentations.length > 0) {
+        throw new Error('Focus intent cannot push while a presentation is active.');
+    }
+    let nextState = finishAllTransitions(state);
+    assertUniqueTransitionId(nextState, event.transitionId);
+    assertUniqueScopeKey(nextState, event.to.key);
+    const source = activeRoute(nextState);
+    if (source.key !== event.fromKey) {
+        throw new Error(`Focus intent push expected source "${source.key}", received "${event.fromKey}".`);
+    }
+    const captured = capture(nextState, source.key, event.activeFocus);
+    nextState = withoutPending(captured.state);
+    const entering = {
+        ...createScopeState(event.to),
+        phase: 'entering',
+        transitionId: event.transitionId,
+    };
+    return {
+        commands: captured.commands,
+        state: {
+            ...nextState,
+            routes: [...nextState.routes, entering],
+            transitions: [...nextState.transitions, { id: event.transitionId, kind: 'push' }],
+        },
+    };
+}
+function beginPop(state, event) {
+    if (state.presentations.length > 0) {
+        throw new Error('Focus intent cannot pop while a presentation is active.');
+    }
+    let nextState = finishEnteringTransitions(state);
+    assertUniqueTransitionId(nextState, event.transitionId);
+    const destinationIndex = nextState.routes.findIndex(route => route.key === event.toKey);
+    const destination = nextState.routes[destinationIndex];
+    if (destinationIndex < 0 || !destination || destination.phase !== 'settled') {
+        throw new Error(`Focus intent pop destination "${event.toKey}" is not a settled route.`);
+    }
+    const departing = nextState.routes
+        .slice(destinationIndex + 1)
+        .filter(route => route.phase !== 'exiting');
+    const captureScope = departing.at(-1);
+    if (!captureScope) {
+        throw new Error(`Focus intent pop destination "${event.toKey}" has no departing route.`);
+    }
+    const captured = capture(nextState, captureScope.key, event.activeFocus);
+    nextState = withoutPending(captured.state);
+    const departingKeys = new Set(departing.map(route => route.key));
+    return {
+        commands: captured.commands,
+        state: {
+            ...nextState,
+            routes: nextState.routes.map(route => departingKeys.has(route.key)
+                ? {
+                    ...route,
+                    phase: 'exiting',
+                    transitionId: event.transitionId,
+                }
+                : route),
+            transitions: [...nextState.transitions, { id: event.transitionId, kind: 'pop' }],
+        },
+    };
+}
+function settleNavigation(state, event) {
+    const transition = state.transitions.find(candidate => candidate.id === event.transitionId);
+    if (!transition)
+        return { commands: [], state };
+    const expectedKind = event.type === 'push-settle' ? 'push' : 'pop';
+    if (transition.kind !== expectedKind) {
+        throw new Error(`Focus intent transition "${event.transitionId}" is ${transition.kind}, not ${expectedKind}.`);
+    }
+    const nextState = event.outcome === 'completed'
+        ? finishTransitions(state, new Set([event.transitionId]))
+        : cancelTransition(state, event.transitionId);
+    if (nextState.presentations.length > 0 || nextState.transitions.length > 0) {
+        return { commands: [], state: nextState };
+    }
+    const reason = event.outcome === 'cancelled' ? 'transition-cancel' : transition.kind;
+    return requestFocus(nextState, activeRoute(nextState).key, transition.kind === 'push' && event.outcome === 'completed' ? 'initial' : 'restore', reason);
+}
+function present(state, event) {
+    if (state.transitions.length > 0) {
+        throw new Error('Focus intent cannot present during a navigation transition.');
+    }
+    assertUniqueScopeKey(state, event.presentation.key);
+    const sourceKey = activeFocusScopeKey(state);
+    if (!sourceKey) {
+        throw new Error('Focus intent presentation has no active source scope.');
+    }
+    const captured = capture(state, sourceKey, event.activeFocus);
+    const presentation = createScopeState(event.presentation);
+    const nextState = {
+        ...withoutPending(captured.state),
+        presentations: [...state.presentations, presentation],
+    };
+    const requested = requestFocus(nextState, presentation.key, 'initial', 'present');
+    return {
+        commands: [...captured.commands, ...requested.commands],
+        state: requested.state,
+    };
+}
+function dismiss(state, event) {
+    const top = state.presentations.at(-1);
+    if (!top || top.key !== event.presentationKey) {
+        throw new Error(`Focus intent can only dismiss the top presentation "${top?.key ?? 'none'}".`);
+    }
+    const nextState = {
+        ...withoutPending(state),
+        presentations: state.presentations.slice(0, -1),
+    };
+    const destinationKey = activeFocusScopeKey(nextState);
+    if (!destinationKey)
+        return { commands: [], state: nextState };
+    return requestFocus(nextState, destinationKey, 'restore', 'dismiss');
+}
+function updateScope(state, scopeKey, update) {
+    let found = false;
+    const presentations = state.presentations.map(scope => {
+        if (scope.key !== scopeKey)
+            return scope;
+        found = true;
+        return update(scope);
+    });
+    const routes = state.routes.map((scope) => {
+        if (scope.key !== scopeKey)
+            return scope;
+        found = true;
+        return { ...scope, ...update(scope) };
+    });
+    if (!found) {
+        throw new Error(`Focus intent scope "${scopeKey}" does not exist.`);
+    }
+    return { ...state, presentations, routes };
+}
+function lazyReady(state, event) {
+    const scope = findScope(state, event.scopeKey);
+    if (!scope) {
+        throw new Error(`Focus intent scope "${event.scopeKey}" does not exist.`);
+    }
+    if (scope.failed || scope.ready)
+        return { commands: [], state };
+    if (event.target) {
+        assertIdentifier(event.target, `lazy target for "${event.scopeKey}"`);
+    }
+    const nextState = updateScope(state, event.scopeKey, candidate => ({
+        ...candidate,
+        focusTarget: event.target ?? candidate.focusTarget,
+        ready: true,
+    }));
+    if (state.pending?.scopeKey !== event.scopeKey) {
+        return { commands: [], state: nextState };
+    }
+    return requestFocus(nextState, event.scopeKey, state.pending.kind, state.pending.reason);
+}
+function reportError(state, event) {
+    assertIdentifier(event.message, `error message for "${event.scopeKey}"`);
+    const scope = findScope(state, event.scopeKey);
+    if (!scope) {
+        throw new Error(`Focus intent scope "${event.scopeKey}" does not exist.`);
+    }
+    if (event.kind === 'status') {
+        return activeFocusScopeKey(state) === event.scopeKey
+            ? {
+                commands: [
+                    {
+                        message: event.message,
+                        politeness: 'assertive',
+                        scopeKey: event.scopeKey,
+                        type: 'announce',
+                    },
+                ],
+                state,
+            }
+            : { commands: [], state };
+    }
+    assertIdentifier(event.target, `error target for "${event.scopeKey}"`);
+    const nextState = updateScope(state, event.scopeKey, candidate => ({
+        ...candidate,
+        failed: true,
+        focusTarget: event.target,
+        ready: true,
+    }));
+    if (activeFocusScopeKey(nextState) !== event.scopeKey) {
+        return { commands: [], state: nextState };
+    }
+    return requestFocus(nextState, event.scopeKey, 'initial', 'error');
+}
+export function reduceFocusIntent(state, event) {
+    switch (event.type) {
+        case 'push-begin':
+            return beginPush(state, event);
+        case 'push-settle':
+        case 'pop-settle':
+            return settleNavigation(state, event);
+        case 'pop-begin':
+            return beginPop(state, event);
+        case 'present':
+            return present(state, event);
+        case 'dismiss':
+            return dismiss(state, event);
+        case 'lazy-ready':
+            return lazyReady(state, event);
+        case 'error':
+            return reportError(state, event);
+    }
+}

package/dist/focus/navigationFocus.d.ts

@@ -0,0 +1,42 @@
+import type { FocusReason } from './focusIntentMachine.js';
+import type { NavigatorState } from '../navigation/types.js';
+export type FocusScope = {
+    element: HTMLElement;
+    title: string;
+    heading?: HTMLElement;
+    chromeExpected?: boolean;
+    contentFirst?: boolean;
+};
+type ChromeScope = {
+    element: HTMLElement;
+    heading: HTMLElement | null;
+    back: HTMLElement | null;
+};
+type NavigationFocusReason = FocusReason | 'select-detail' | 'replace';
+/** Eligibility is shared by route and modal restoration. Geometry is checked
+ * separately at the point of focus; DOM membership alone is not visibility. */
+export declare function canReceiveFocus(element: HTMLElement | null | undefined, scope?: HTMLElement): element is HTMLElement;
+/** Reject clipped, transparent, offscreen and empty accessibility cursor frames.
+ * Intersect overflow clips as well as the viewport (retained scroll positions). */
+export declare function hasVisibleFocusFrame(element: HTMLElement): boolean;
+export declare function visibleFocusTarget(element: HTMLElement | null | undefined): element is HTMLElement;
+export declare function visibleHeading(scope: HTMLElement): HTMLElement | undefined;
+export declare function firstVisibleControl(scope: HTMLElement): HTMLElement | undefined;
+/** Native pushes start at readable screen content. Walk in reading order,
+ * treating named controls and semantic text blocks as single elements. Plain
+ * text also works without requiring app authors to add a heading or Tab stop. */
+export declare function firstVisibleContent(scope: HTMLElement): HTMLElement | undefined;
+/** Activating a tab keeps its cursor on the tab. Programmatic switches whose
+ * old content became inert still need a destination focus target. */
+export declare function hasFocusedTab(document: Document): boolean;
+/** Store settlement is the transaction boundary. Chrome has explicit ownership
+ * because it is a sibling of the retained screen, not a descendant. */
+export declare function createNavigationFocusRuntime(): {
+    bind(key: string, scope: FocusScope): () => void;
+    bindChrome(key: string, scope: ChromeScope): () => void;
+    capture(keys: readonly string[]): void;
+    request(key: string | undefined, reason: NavigationFocusReason): void;
+    flush(state: NavigatorState, key: string, active: boolean): void;
+};
+export declare const navigatorFocusRuntime: unique symbol;
+export {};

package/dist/focus/navigationFocus.js

@@ -0,0 +1,241 @@
+import { focusFromFramework, trackInputModality } from './programmaticFocus.js';
+/** Eligibility is shared by route and modal restoration. Geometry is checked
+ * separately at the point of focus; DOM membership alone is not visibility. */
+export function canReceiveFocus(element, scope) {
+    if (!element?.isConnected ||
+        (scope && !scope.contains(element)) ||
+        element.closest('[inert], [hidden], [aria-hidden="true"], :disabled') ||
+        !element.matches('button, input, select, textarea, a[href], [tabindex], [contenteditable="true"]'))
+        return false;
+    for (let current = element; current; current = current.parentElement) {
+        const style = current.ownerDocument.defaultView?.getComputedStyle(current);
+        if (style?.display === 'none' || style?.visibility === 'hidden')
+            return false;
+    }
+    return true;
+}
+/** Reject clipped, transparent, offscreen and empty accessibility cursor frames.
+ * Intersect overflow clips as well as the viewport (retained scroll positions). */
+export function hasVisibleFocusFrame(element) {
+    const view = element.ownerDocument.defaultView;
+    if (!view)
+        return false;
+    const rect = element.getBoundingClientRect();
+    let left = Math.max(0, rect.left), top = Math.max(0, rect.top);
+    let right = Math.min(view.innerWidth, rect.right), bottom = Math.min(view.innerHeight, rect.bottom);
+    for (let current = element; current; current = current.parentElement) {
+        const style = view.getComputedStyle(current);
+        if (style.opacity === '0' ||
+            style.clipPath === 'inset(50%)' ||
+            style.clip === 'rect(0px, 0px, 0px, 0px)')
+            return false;
+        if (current !== element) {
+            const bounds = current.getBoundingClientRect();
+            if (/(hidden|clip|scroll|auto)/.test(style.overflowX || style.overflow)) {
+                left = Math.max(left, bounds.left);
+                right = Math.min(right, bounds.right);
+            }
+            if (/(hidden|clip|scroll|auto)/.test(style.overflowY || style.overflow)) {
+                top = Math.max(top, bounds.top);
+                bottom = Math.min(bottom, bounds.bottom);
+            }
+        }
+    }
+    return right - left > 1 && bottom - top > 1;
+}
+export function visibleFocusTarget(element) {
+    // Restoring a pinned search field would start a new search and summon its keyboard.
+    // It remains in the user's Tab order; only automatic framework focus skips it.
+    return (canReceiveFocus(element) &&
+        !element.closest('[data-satin-search]:not([data-satin-search-presented])') &&
+        hasVisibleFocusFrame(element));
+}
+export function visibleHeading(scope) {
+    return [
+        ...scope.querySelectorAll('h1, h2, [role="heading"], [data-satin-modal-heading]'),
+    ].find(element => {
+        // Static headings become programmatic targets, never extra Tab stops.
+        if (!element.hasAttribute('tabindex'))
+            element.tabIndex = -1;
+        return visibleFocusTarget(element);
+    });
+}
+export function firstVisibleControl(scope) {
+    return [
+        ...scope.querySelectorAll('button, input, select, textarea, a[href], [tabindex]'),
+    ].find(element => element.tabIndex >= 0 && visibleFocusTarget(element));
+}
+/** Conservative content eligibility, not a replacement for the browser's name
+ * computation. Never promote an empty/decorative node into the focus order. */
+function hasMeaningfulContent(element) {
+    const style = element.ownerDocument.defaultView.getComputedStyle(element);
+    if (style.display === 'none' || style.visibility === 'hidden')
+        return false;
+    if (element instanceof element.ownerDocument.defaultView.HTMLImageElement &&
+        (!element.alt.trim() || element.matches('[role="presentation"], [role="none"]')))
+        return false;
+    const labelled = element.getAttribute('aria-labelledby')?.trim();
+    if (labelled &&
+        labelled.split(/\s+/).some(id => element.ownerDocument.getElementById(id)?.textContent?.trim()))
+        return true;
+    if (element.getAttribute('aria-label')?.trim() || element.getAttribute('title')?.trim())
+        return true;
+    if ('labels' in element &&
+        [...(element.labels ?? [])].some(label => label.textContent?.trim()))
+        return true;
+    if (element.matches('img[alt]') && element.getAttribute('alt')?.trim())
+        return true;
+    if (element.matches('input[type="button"], input[type="submit"], input[type="reset"]') &&
+        element.value.trim())
+        return true;
+    return [...element.childNodes].some(child => child.nodeType === 3
+        ? Boolean(child.textContent?.trim())
+        : child instanceof element.ownerDocument.defaultView.HTMLElement &&
+            !child.matches('script, style, [hidden], [aria-hidden="true"]') &&
+            hasVisibleFocusFrame(child) &&
+            hasMeaningfulContent(child));
+}
+/** Native pushes start at readable screen content. Walk in reading order,
+ * treating named controls and semantic text blocks as single elements. Plain
+ * text also works without requiring app authors to add a heading or Tab stop. */
+export function firstVisibleContent(scope) {
+    const document = scope.ownerDocument, view = document.defaultView;
+    if (!view)
+        return;
+    const walker = document.createTreeWalker(scope, 1);
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+        if (!(node instanceof view.HTMLElement))
+            continue;
+        if (node.closest('script, style, svg, canvas, [inert], [hidden], [aria-hidden="true"], :disabled'))
+            continue;
+        if (node.matches('[role="presentation"], [role="none"]'))
+            continue;
+        const control = node.matches('button, input, select, textarea, a[href], [role="button"], [role="switch"], [role="checkbox"], [role="radio"], [role="tab"], [role="slider"], img[alt]');
+        const textBlock = node.matches('p, h1, h2, h3, h4, h5, h6, [role="heading"]') && node.textContent?.trim();
+        const directText = [...node.childNodes].some(child => child.nodeType === 3 && child.textContent?.trim());
+        if ((!control && !textBlock && !directText) ||
+            !hasVisibleFocusFrame(node) ||
+            !hasMeaningfulContent(node))
+            continue;
+        if (!node.hasAttribute('tabindex') && !node.matches('button, input, select, textarea, a[href]'))
+            node.tabIndex = -1;
+        if (visibleFocusTarget(node))
+            return node;
+    }
+}
+/** Activating a tab keeps its cursor on the tab. Programmatic switches whose
+ * old content became inert still need a destination focus target. */
+export function hasFocusedTab(document) {
+    const active = document.activeElement;
+    return (active instanceof document.defaultView.HTMLElement &&
+        active.matches('[data-satin-tab-item], [role="tab"][data-tab-index]') &&
+        visibleFocusTarget(active));
+}
+/** Store settlement is the transaction boundary. Chrome has explicit ownership
+ * because it is a sibling of the retained screen, not a descendant. */
+export function createNavigationFocusRuntime() {
+    if (typeof document !== 'undefined')
+        trackInputModality(document);
+    const scopes = new Map();
+    const chrome = new Map();
+    const saved = new Map();
+    let pending;
+    let revision = 0;
+    const owns = (key, target) => scopes.get(key)?.element.contains(target) || chrome.get(key)?.element.contains(target);
+    return {
+        bind(key, scope) {
+            scopes.set(key, scope);
+            return () => {
+                if (scopes.get(key) === scope)
+                    scopes.delete(key);
+            };
+        },
+        bindChrome(key, scope) {
+            chrome.set(key, scope);
+            return () => {
+                if (chrome.get(key) === scope)
+                    chrome.delete(key);
+            };
+        },
+        capture(keys) {
+            for (const key of keys) {
+                const scope = scopes.get(key);
+                const active = scope?.element.ownerDocument.activeElement;
+                if (scope &&
+                    active instanceof scope.element.ownerDocument.defaultView.HTMLElement &&
+                    owns(key, active) &&
+                    visibleFocusTarget(active))
+                    saved.set(key, active);
+            }
+        },
+        request(key, reason) {
+            pending = key ? { key, reason } : undefined;
+            revision++;
+        },
+        flush(state, key, active) {
+            if (!active ||
+                !pending ||
+                pending.key !== key ||
+                state.entries.some(entry => entry.transition.phase !== 'settled'))
+                return;
+            const scope = scopes.get(key);
+            if (!scope || (scope.chromeExpected && !chrome.has(key)))
+                return;
+            if ([...scope.element.ownerDocument.querySelectorAll('dialog[open]')].some(dialog => !dialog.contains(scope.element)))
+                return;
+            const restore = pending.reason === 'pop' ||
+                pending.reason === 'transition-cancel' ||
+                pending.reason === 'dismiss';
+            const snapshot = saved.get(key), bar = chrome.get(key);
+            // Physical iPadOS 27: split selection retains the sidebar invoker;
+            // pushes land on the first content element. A button pop can retain the
+            // still-visible Back control, while scrub restores the screen invoker.
+            const activeElement = scope.element.ownerDocument.activeElement;
+            // An entering screen may focus an editor before its push settles. That editing intent
+            // wins over the default heading/Back target; keyboard avoidance reveals it after motion.
+            // Do not require an unclipped frame here: the keyboard may still cover this editor.
+            const editingTarget = activeElement instanceof scope.element.ownerDocument.defaultView.HTMLElement &&
+                activeElement.matches('input, textarea, [contenteditable="true"]') &&
+                canReceiveFocus(activeElement, scope.element)
+                ? activeElement
+                : undefined;
+            const selectedInvoker = pending.reason === 'select-detail' &&
+                activeElement instanceof scope.element.ownerDocument.defaultView.HTMLElement &&
+                state.entries.some(entry => entry.key !== key && owns(entry.key, activeElement)) &&
+                visibleFocusTarget(activeElement)
+                ? activeElement
+                : undefined;
+            const retainedBack = pending.reason === 'pop' && activeElement === bar?.back && visibleFocusTarget(bar?.back)
+                ? bar.back
+                : undefined;
+            const restored = restore && snapshot && owns(key, snapshot) && visibleFocusTarget(snapshot)
+                ? snapshot
+                : undefined;
+            const contentPush = scope.contentFirst && pending.reason === 'push';
+            const target = editingTarget ??
+                selectedInvoker ??
+                retainedBack ??
+                restored ??
+                (contentPush
+                    ? ((visibleFocusTarget(scope.heading) ? scope.heading : undefined) ??
+                        firstVisibleContent(scope.element))
+                    : undefined) ??
+                // Unmeasured scopes/reasons retain the pre-12j2 fallback order.
+                [bar?.back, scope.heading, bar?.heading].find(visibleFocusTarget) ??
+                visibleHeading(scope.element) ??
+                firstVisibleControl(scope.element);
+            if (!target)
+                return; // Remain pending until an actual visible target is ready.
+            const version = revision;
+            focusFromFramework(target, { preventScroll: true });
+            scope.element.ownerDocument.title = scope.title;
+            if (version === revision)
+                pending = undefined;
+            const retained = new Set(state.entries.map(entry => entry.key));
+            for (const savedKey of saved.keys())
+                if (!retained.has(savedKey))
+                    saved.delete(savedKey);
+        },
+    };
+}
+export const navigatorFocusRuntime = Symbol('satin.navigator.focus-runtime');

package/dist/focus/programmaticFocus.d.ts

@@ -0,0 +1,15 @@
+export declare function trackInputModality(document: Document): void;
+/** Test hook: force or re-detect `focusVisible` option support. */
+export declare function setFocusVisibleOptionSupportForTesting(value: boolean | undefined): void;
+export declare function lastInputWasKeyboard(document: Document): boolean;
+/** True while `focusFromFramework` is moving focus to this element (its focus events included). */
+export declare function isFrameworkFocus(element: Element): boolean;
+/** Use for every focus move Satin makes on the user's behalf (route, tab and
+ * modal targets, restoration). Keyboard-driven traversal may call focus() directly. */
+export declare function focusFromFramework(element: HTMLElement, options?: {
+    preventScroll?: boolean;
+}): void;
+/** A modal's UA focusing steps (showModal) can focus a descendant before Satin
+ * has a visible target (a sheet still entering). After touch, quiet that UA
+ * focus the same way; keyboard users keep the ring. */
+export declare function quietUserAgentFocus(scope: Element): void;