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

package/dist/media/systemMedia.js

@@ -0,0 +1,200 @@
+const owners = new WeakMap();
+const actions = [
+    'play',
+    'pause',
+    'nexttrack',
+    'previoustrack',
+    'seekto',
+    'seekforward',
+    'seekbackward',
+];
+/** Media Session is document-global. A retired root must not clear its successor. */
+export function createSystemMedia(controller, readState, readElement) {
+    const session = typeof navigator === 'undefined' ? undefined : navigator.mediaSession;
+    const owner = Symbol('satin-media-session');
+    if (session)
+        owners.set(session, owner);
+    const installed = new Map();
+    const unavailable = new Set();
+    let metadataEntry;
+    let positionKey;
+    let playbackState;
+    let disposed = false;
+    const ownsSession = () => session && !disposed && owners.get(session) === owner;
+    function attempt(feature, write) {
+        if (unavailable.has(feature))
+            return;
+        try {
+            write();
+        }
+        catch (error) {
+            unavailable.add(feature);
+            console.warn(`Satin system media ${feature} is unavailable.`, error);
+        }
+    }
+    function available(action, state) {
+        if (!state.currentEntryId || state.status === 'idle')
+            return false;
+        const index = state.playbackOrder.indexOf(state.currentEntryId);
+        if (action === 'nexttrack')
+            return index + 1 < state.playbackOrder.length || state.repeat === 'all';
+        if (action === 'previoustrack')
+            return index > 0 || state.repeat === 'all';
+        if ((action === 'seekforward' || action === 'seekbackward') &&
+            (available('nexttrack', state) || available('previoustrack', state)))
+            return false;
+        if (action.startsWith('seek'))
+            return (state.seekable.length > 0 ||
+                (state.duration.kind === 'finite' && state.duration.seconds > 0));
+        return true;
+    }
+    function dispatch(details) {
+        const state = readState();
+        switch (details.action) {
+            case 'play':
+                void controller.play();
+                break;
+            case 'pause':
+                controller.pause();
+                break;
+            case 'nexttrack':
+                void controller.next();
+                break;
+            case 'previoustrack':
+                void controller.previous();
+                break;
+            case 'seekto':
+                if (details.seekTime !== undefined)
+                    void controller.seek(details.seekTime);
+                break;
+            case 'seekforward':
+            case 'seekbackward': {
+                const offset = details.seekOffset ?? 10;
+                if (!Number.isFinite(offset) || offset < 0)
+                    break;
+                const direction = details.action === 'seekforward' ? 1 : -1;
+                void controller.seek(Math.max(0, state.position + direction * offset));
+                break;
+            }
+        }
+    }
+    function artwork(src) {
+        if (!src)
+            return [];
+        try {
+            return [{ src: new URL(src, document.baseURI).href, sizes: 'any' }];
+        }
+        catch {
+            // A bad catalog image must not suppress the title or future track metadata.
+            if (!unavailable.has('artwork')) {
+                console.warn('Satin system media artwork URL is invalid.');
+                unavailable.add('artwork');
+            }
+            return [];
+        }
+    }
+    function sync(force = false) {
+        if (!ownsSession())
+            return;
+        const state = readState();
+        const element = readElement();
+        for (const action of actions) {
+            const enabled = available(action, state);
+            const previous = installed.get(action);
+            if (previous?.generation === state.generation && previous.enabled === enabled)
+                continue;
+            const generation = state.generation;
+            attempt(action, () => {
+                session.setActionHandler(action, enabled
+                    ? details => {
+                        if (!ownsSession() || readState().generation !== generation)
+                            return;
+                        if (available(action, readState()))
+                            dispatch(details);
+                    }
+                    : null);
+            });
+            installed.set(action, { generation, enabled });
+        }
+        const entry = element
+            ? state.queue.find(item => item.entryId === state.currentEntryId)
+            : undefined;
+        const metadata = entry?.metadata;
+        if (force || entry !== metadataEntry) {
+            metadataEntry = entry;
+            attempt('metadata', () => {
+                session.metadata =
+                    entry && typeof MediaMetadata !== 'undefined'
+                        ? new MediaMetadata({
+                            title: metadata?.title ?? '',
+                            artist: metadata?.artist ?? '',
+                            album: metadata?.album ?? '',
+                            // The API accepts unspecified intrinsic sizes. Do not claim resized
+                            // artwork exists when the app supplies only one original image URL.
+                            artwork: artwork(metadata?.artwork),
+                        })
+                        : null;
+            });
+        }
+        const observedPlayback = !element
+            ? 'none'
+            : element.paused || element.ended
+                ? 'paused'
+                : 'playing';
+        if (force || observedPlayback !== playbackState) {
+            playbackState = observedPlayback;
+            attempt('playbackState', () => {
+                session.playbackState = observedPlayback;
+            });
+        }
+        const rate = element?.playbackRate ?? 1;
+        const position = element &&
+            state.duration.kind === 'finite' &&
+            state.duration.seconds > 0 &&
+            Number.isFinite(state.duration.seconds) &&
+            Number.isFinite(rate) &&
+            rate > 0
+            ? {
+                duration: state.duration.seconds,
+                position: Math.min(state.duration.seconds, Math.max(0, state.position)),
+                playbackRate: rate,
+            }
+            : undefined;
+        const nextPositionKey = position
+            ? `${state.generation}:${position.duration}:${position.position}:${position.playbackRate}:${observedPlayback}`
+            : 'clear';
+        if (force || nextPositionKey !== positionKey) {
+            positionKey = nextPositionKey;
+            attempt('position', () => {
+                session.setPositionState?.(position);
+            });
+        }
+    }
+    return {
+        sync,
+        dispose() {
+            if (ownsSession()) {
+                for (const action of actions) {
+                    // Unsupported actions can also reject null. Clear each independently.
+                    try {
+                        session.setActionHandler(action, null);
+                    }
+                    catch {
+                        /* Already unavailable. */
+                    }
+                }
+                attempt('metadata', () => {
+                    session.metadata = null;
+                });
+                attempt('playbackState', () => {
+                    session.playbackState = 'none';
+                });
+                attempt('position', () => {
+                    session.setPositionState?.();
+                });
+                owners.delete(session);
+            }
+            disposed = true;
+        },
+    };
+}

package/dist/media/types.d.ts

@@ -0,0 +1,83 @@
+/** Each occurrence has its own entryId, including repeated songs. */
+export type MediaQueueEntry = Readonly<{
+    entryId: string;
+    mediaId: string;
+    src: string;
+    mimeType?: string;
+    sourceRevision?: string | number;
+    metadata?: Readonly<{
+        title?: string;
+        artist?: string;
+        album?: string;
+        artwork?: string;
+    }>;
+}>;
+/** How a media command ended. `needs-user-activation` means WebKit wants a tap first. */
+export type MediaCommandResult = Readonly<{
+    status: 'completed' | 'cancelled' | 'needs-user-activation' | 'unavailable';
+    operationId: number;
+} | {
+    status: 'failed';
+    operationId: number;
+    code: string;
+    cause?: unknown;
+}>;
+/** The queue's repeat mode. */
+export type MediaRepeat = 'off' | 'one' | 'all';
+/** Everything the player shows: the queue, the current entry, status, position and modes. */
+export type MediaSnapshot = Readonly<{
+    queue: readonly MediaQueueEntry[];
+    playbackOrder: readonly string[];
+    currentEntryId: string | null;
+    status: 'idle' | 'loading' | 'paused' | 'playing' | 'buffering' | 'ended' | 'interrupted' | 'error';
+    position: number;
+    duration: Readonly<{
+        kind: 'unknown' | 'live';
+    }> | Readonly<{
+        kind: 'finite';
+        seconds: number;
+    }>;
+    seekable: readonly Readonly<{
+        start: number;
+        end: number;
+    }>[];
+    repeat: MediaRepeat;
+    shuffle: boolean;
+    interruption: 'unknown-system' | null;
+    error: Readonly<{
+        code: string;
+    }> | null;
+}>;
+/** @internal Playback coordination fields, excluded from the application snapshot. */
+export type InternalMediaSnapshot = MediaSnapshot & Readonly<{
+    playIntent: boolean;
+    generation: number;
+    pendingSeek: number | null;
+}>;
+/** Where a replaced queue starts, and whether it plays. */
+export type MediaQueueOptions = Readonly<{
+    currentEntryId?: string;
+    position?: number;
+    autoplay?: boolean;
+}>;
+/** Queue results acknowledge the transaction. Playback and seek results acknowledge observed completion. */
+export interface MediaController {
+    replaceQueue(entries: readonly MediaQueueEntry[], options?: MediaQueueOptions): Promise<MediaCommandResult>;
+    play(): Promise<MediaCommandResult>;
+    pause(): MediaCommandResult;
+    stop(): MediaCommandResult;
+    seek(seconds: number): Promise<MediaCommandResult>;
+    next(): Promise<MediaCommandResult>;
+    previous(): Promise<MediaCommandResult>;
+    append(entries: readonly MediaQueueEntry[]): MediaCommandResult;
+    insertNext(entries: readonly MediaQueueEntry[]): MediaCommandResult;
+    remove(entryId: string): MediaCommandResult;
+    move(entryId: string, beforeEntryId: string | null): MediaCommandResult;
+    setRepeat(repeat: MediaRepeat): MediaCommandResult;
+    setShuffle(shuffle: boolean): MediaCommandResult;
+}
+/** `useMediaPlayer`'s result: the commands and the live state. */
+export type MediaPlayer = Readonly<{
+    controller: MediaController;
+    state: MediaSnapshot;
+}>;

package/dist/media/types.js

@@ -0,0 +1 @@
+export {};

package/dist/menu/menuContact.d.ts

@@ -0,0 +1,20 @@
+import type { GlassInteraction } from '../glass/rendererContract.js';
+export type MenuContactSample = {
+    touchId?: number;
+    pointerId: number;
+    x: number;
+    y: number;
+    phase?: 'start' | 'move' | 'end' | 'cancel';
+};
+/** How long a contact rests on a submenu row before the submenu opens under it. Unmeasured:
+ * the calibrated native contact held 900 ms and the submenu was open (submenus/SPEC.md). */
+export declare const SUBMENU_DWELL_MS = 500;
+/** One contact owns selection and deformation, including an already recognized context hold. */
+export declare function createMenuContact(): {
+    begin: (sample: MenuContactSample, held?: boolean) => void;
+    transfer(sample: MenuContactSample, source: HTMLElement): void;
+    readonly active: boolean;
+    sample: (next: MenuContactSample) => void;
+    cancel: () => void;
+    attach(element: HTMLElement, sendLight?: (input: GlassInteraction) => void): () => void;
+};

package/dist/menu/menuContact.js

@@ -0,0 +1,286 @@
+import { activateMenuAction } from '../actions/ActionMenu.js';
+import { transitionRowFeedback } from '../press/stateMachine.js';
+import { ROW_HIGHLIGHT_DELAY_MS } from '../press/tokens.js';
+import { ownMenuCompatibilityClick } from '../press/contactReceipt.js';
+import { beginMenuPanelContact } from './menuPanelContact.js';
+/** How long a contact rests on a submenu row before the submenu opens under it. Unmeasured:
+ * the calibrated native contact held 900 ms and the submenu was open (submenus/SPEC.md). */
+export const SUBMENU_DWELL_MS = 500;
+/** One contact owns selection and deformation, including an already recognized context hold. */
+export function createMenuContact() {
+    let emitLight;
+    let panel;
+    let current;
+    let releaseOwnership;
+    let transferred = false;
+    let initialRow;
+    let moved = false;
+    let lightStarted = false;
+    let feedback = 'idle';
+    let timer;
+    let selected;
+    let deformation;
+    let dwell;
+    /** This contact opened a submenu by resting on its row. */
+    let openedSubmenu = false;
+    const light = (phase, contact = current) => {
+        const glass = panel?.querySelector('[data-satin-glass-region-id]');
+        if (!glass || !emitLight)
+            return;
+        const point = contact && deformation?.localPoint(glass, contact.x, contact.y);
+        if (contact && !point)
+            return;
+        if (!lightStarted) {
+            if (phase === 'rest' || phase === 'releasing')
+                return;
+            // Recognition transfers a finger still resting on the source row. That
+            // contact owns selection, but only lights the glass after entering it.
+            if (transferred &&
+                point &&
+                (point.x < 0 || point.y < 0 || point.x > glass.offsetWidth || point.y > glass.offsetHeight))
+                return;
+            phase = 'pressed';
+            lightStarted = true;
+        }
+        emitLight({
+            regionId: glass.dataset.satinGlassRegionId,
+            phase,
+            epoch: performance.timeOrigin + performance.now(),
+            contact: point,
+        });
+    };
+    const highlight = (next) => {
+        if (selected === next)
+            return;
+        selected?.removeAttribute('data-satin-drag-selected');
+        selected = next;
+        selected?.setAttribute('data-satin-drag-selected', 'true');
+    };
+    const hit = (sample) => {
+        const row = panel?.ownerDocument
+            .elementFromPoint(sample.x, sample.y)
+            ?.closest(':is([role="menuitem"], [role="menuitemradio"])');
+        return row &&
+            panel?.contains(row) &&
+            !row.disabled &&
+            row.getAttribute('aria-disabled') !== 'true'
+            ? row
+            : undefined;
+    };
+    // Resting on a submenu row opens it, so one contact can travel into nested menus.
+    const dwellOn = (row) => {
+        if (dwell?.row === row)
+            return;
+        clearTimeout(dwell?.timer);
+        dwell = undefined;
+        if (!row || row.getAttribute('aria-haspopup') !== 'menu')
+            return;
+        if (row.getAttribute('aria-expanded') === 'true')
+            return;
+        dwell = {
+            row,
+            timer: setTimeout(() => {
+                dwell = undefined;
+                if (!current || selected !== row)
+                    return;
+                openedSubmenu = true;
+                activateMenuAction(row);
+            }, SUBMENU_DWELL_MS),
+        };
+    };
+    const update = () => {
+        if (current && feedback === 'pressed')
+            highlight(hit(current));
+        dwellOn(current ? selected : undefined);
+    };
+    /** Lifting off the row a rest just opened (or the new submenu's title, now under the finger)
+     * leaves the submenu open. */
+    const keepsSubmenu = (row) => openedSubmenu && row.getAttribute('aria-expanded') === 'true';
+    const cancel = () => {
+        if (lightStarted)
+            light('rest');
+        lightStarted = false;
+        releaseOwnership?.();
+        releaseOwnership = undefined;
+        clearTimeout(timer);
+        dwellOn();
+        current = undefined;
+        feedback = transitionRowFeedback(feedback, 'cancel');
+        highlight();
+        deformation?.cancel();
+        deformation = undefined;
+    };
+    const begin = (sample, held = false) => {
+        cancel();
+        current = sample;
+        transferred = held;
+        initialRow = hit(sample);
+        moved = false;
+        openedSubmenu = false;
+        feedback = transitionRowFeedback('idle', 'down');
+        if (panel)
+            deformation = beginMenuPanelContact(panel, sample.x, sample.y);
+        light('pressed');
+        if (held) {
+            feedback = transitionRowFeedback(feedback, 'hold');
+            update();
+        }
+        else
+            timer = setTimeout(() => {
+                feedback = transitionRowFeedback(feedback, 'hold');
+                update();
+            }, ROW_HIGHLIGHT_DELAY_MS);
+    };
+    const sample = (next) => {
+        if (!current || next.pointerId !== current.pointerId)
+            return;
+        current = next;
+        if (next.phase === 'end' || next.phase === 'cancel') {
+            light(next.phase === 'end' ? 'releasing' : 'rest', next);
+            const row = next.phase === 'end' ? hit(next) : undefined;
+            releaseOwnership?.();
+            releaseOwnership = undefined;
+            clearTimeout(timer);
+            dwellOn();
+            feedback = transitionRowFeedback(feedback, next.phase === 'end' ? 'release' : 'cancel');
+            current = undefined;
+            highlight();
+            if (next.phase === 'end')
+                deformation?.release();
+            else
+                deformation?.cancel();
+            const nativeTap = !transferred &&
+                !moved &&
+                !openedSubmenu &&
+                row === initialRow &&
+                row?.hasAttribute('data-satin-sensory-button');
+            if (!nativeTap) {
+                if (panel)
+                    ownMenuCompatibilityClick(panel.ownerDocument);
+                if (row && !keepsSubmenu(row))
+                    activateMenuAction(row);
+            }
+            return;
+        }
+        moved ||= hit(next) !== initialRow;
+        deformation?.move(next.x, next.y);
+        light('dragging', next);
+        update();
+    };
+    const controller = {
+        begin,
+        transfer(sample, source) {
+            begin(sample, true);
+            const document = source.ownerDocument;
+            const consume = (event) => {
+                let x;
+                let y;
+                if (sample.touchId !== undefined) {
+                    const touch = [...event.changedTouches].find(value => value.identifier === sample.touchId);
+                    if (!touch)
+                        return;
+                    x = touch.clientX;
+                    y = touch.clientY;
+                }
+                else {
+                    const pointer = event;
+                    if (pointer.pointerId !== sample.pointerId)
+                        return;
+                    x = pointer.clientX;
+                    y = pointer.clientY;
+                }
+                if (event.cancelable)
+                    event.preventDefault();
+                event.stopPropagation();
+                controller.sample({
+                    ...sample,
+                    x,
+                    y,
+                    phase: event.type.endsWith('end') || event.type.endsWith('up')
+                        ? 'end'
+                        : event.type.endsWith('cancel')
+                            ? 'cancel'
+                            : 'move',
+                });
+            };
+            const events = sample.touchId === undefined
+                ? ['pointermove', 'pointerup', 'pointercancel']
+                : ['touchmove', 'touchend', 'touchcancel'];
+            for (const event of events)
+                document.addEventListener(event, consume, { capture: true, passive: false });
+            releaseOwnership = () => {
+                for (const event of events)
+                    document.removeEventListener(event, consume, true);
+            };
+        },
+        get active() {
+            return !!current;
+        },
+        sample,
+        cancel,
+        attach(element, sendLight) {
+            panel = element;
+            emitLight = sendLight;
+            const document = panel.ownerDocument;
+            const scroll = panel.matches('[data-satin-menu-scroll]')
+                ? panel
+                : panel.querySelector('[data-satin-menu-scroll]');
+            const menu = panel.querySelector('[data-satin-action-menu]');
+            const touchPolicy = () => {
+                if (menu)
+                    menu.style.touchAction =
+                        scroll && scroll.scrollHeight > scroll.clientHeight + 1 ? 'pan-y' : 'none';
+            };
+            touchPolicy();
+            const resize = new ResizeObserver(touchPolicy);
+            if (menu)
+                resize.observe(menu);
+            if (current) {
+                deformation = beginMenuPanelContact(panel, current.x, current.y);
+                light('pressed');
+            }
+            const down = (event) => {
+                if (current || !event.isPrimary || event.button !== 0)
+                    return;
+                begin({ pointerId: event.pointerId, x: event.clientX, y: event.clientY });
+                // Preserve WebKit label activation for a direct tap.
+                event.stopImmediatePropagation();
+            };
+            const pointer = (event) => {
+                if (transferred || event.pointerId !== current?.pointerId)
+                    return;
+                sample({
+                    pointerId: event.pointerId,
+                    x: event.clientX,
+                    y: event.clientY,
+                    phase: event.type === 'pointerup' ? 'end' : event.type === 'pointercancel' ? 'cancel' : 'move',
+                });
+                if (event.type === 'pointercancel' || moved)
+                    event.preventDefault();
+                event.stopImmediatePropagation();
+            };
+            const blur = () => cancel();
+            const visibility = () => {
+                if (document.hidden)
+                    cancel();
+            };
+            document.defaultView?.addEventListener('blur', blur);
+            document.addEventListener('visibilitychange', visibility);
+            panel.addEventListener('pointerdown', down, true);
+            for (const type of ['pointermove', 'pointerup', 'pointercancel'])
+                document.addEventListener(type, pointer, true);
+            return () => {
+                cancel();
+                emitLight = undefined;
+                document.defaultView?.removeEventListener('blur', blur);
+                document.removeEventListener('visibilitychange', visibility);
+                resize.disconnect();
+                element.removeEventListener('pointerdown', down, true);
+                for (const type of ['pointermove', 'pointerup', 'pointercancel'])
+                    document.removeEventListener(type, pointer, true);
+                panel = undefined;
+            };
+        },
+    };
+    return controller;
+}

package/dist/menu/menuGesture.d.ts

@@ -0,0 +1,84 @@
+export { menuPull, menuReturn, MENU_RELEASE_SPRING, MENU_STRAIN_RESPONSE_MS, } from '../glass/contactPhysics.js';
+export type MenuGestureFrame = Readonly<{
+    x: number;
+    y: number;
+    scaleX: number;
+    scaleY: number;
+    highlightY: number;
+    highlightOpacity: number;
+    contact: number;
+    fingerX: number;
+    fingerY: number;
+    trigger: boolean;
+    tapFeedback: boolean;
+}>;
+export declare const MENU_GESTURE_REST: MenuGestureFrame;
+export declare const MENU_TAP_FEEDBACK_MS = 20;
+export type MenuPanelBounds = Readonly<{
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}>;
+/** Fit to axis controls plus the held diagonal, with its origin in the panel's
+ * resting coordinate space. Over-pull begins outside the panel; the anchored
+ * right edge couples vertical stretch to horizontal displacement. */
+export declare function menuPanelPull(x: number, y: number, startX: number, startY: number, bounds: MenuPanelBounds): {
+    x: number;
+    y: number;
+    scaleX: number;
+    scaleY: number;
+};
+/** Shared strain projection for presentation and backing-envelope allocation. */
+export declare function applyMenuStrain(pull: ReturnType<typeof menuPanelPull>, velocity: number, bounds: MenuPanelBounds): {
+    x: number;
+    y: number;
+    scaleX: number;
+    scaleY: number;
+};
+export declare function menuHighlightAttack(milliseconds: number): number;
+export declare function menuTriggerPress(milliseconds: number): {
+    scale: number;
+    contact: number;
+};
+export type MenuGestureMotion = Readonly<{
+    startedAt: number;
+    stepMilliseconds: number;
+    frames: readonly MenuGestureFrame[];
+}>;
+export type MenuGestureDecision = Readonly<{
+    pointerId: number;
+    at: number;
+    reason: 'accepted' | 'pointer-busy' | 'non-primary' | 'non-primary-button' | 'menu-closed' | 'pointercancel' | 'lostpointercapture' | 'host-cancel' | 'visibility-hidden' | 'window-blur' | 'disposed' | 'trigger-opened' | 'trigger-held-open' | 'trigger-drag-before-open' | 'release-outside-enabled-row' | 'selection-dispatched' | 'compatibility-click-suppressed' | 'capture-failed';
+    row?: number;
+}>;
+type Options = {
+    trigger: HTMLButtonElement;
+    panel: HTMLElement;
+    surface?: HTMLElement;
+    bounds?: () => MenuPanelBounds;
+    /** Stable resting aperture when the visual trigger itself is transformed. */
+    triggerBounds?: () => MenuPanelBounds;
+    /** A retained renderer can sample with tick() before painting its frame. */
+    autoSchedule?: boolean;
+    requestFrame?: () => void;
+    items: readonly HTMLButtonElement[];
+    isOpen: () => boolean;
+    open: () => void;
+    select: (index: number) => void;
+    frame: (frame: MenuGestureFrame) => void;
+    /** Input-driven timeline for autonomous DOM presentation; tick remains GL-only. */
+    motion?: (motion: MenuGestureMotion) => void;
+    reducedMotion: () => boolean;
+    decision?: (decision: MenuGestureDecision) => void;
+    observe?: (phase: 'down' | 'move' | 'up' | 'cancel', event: PointerEvent) => void;
+};
+/** One pointer owns a menu session, including the trigger-to-panel handoff.
+ * Native buttons retain their click/keyboard/assistive activation path. Hosts
+ * must declare touch-action:none on these gesture owners, never the document.
+ */
+export declare function bindMenuGestures(options: Options): {
+    tick(now: number): void;
+    cancel: () => void;
+    dispose(): void;
+};