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

package/dist/actions/nativeMotion.json

@@ -0,0 +1,388 @@
+{
+    "collapse": {
+        "duration": 360.0000000000001,
+        "keyframes": [
+            [
+                0.0,
+                -0.0
+            ],
+            [
+                0.032406,
+                0.081633
+            ],
+            [
+                0.078703,
+                0.22449
+            ],
+            [
+                0.328703,
+                0.795918
+            ],
+            [
+                0.513889,
+                0.938776
+            ],
+            [
+                0.560183,
+                0.959184
+            ],
+            [
+                0.60185,
+                0.959184
+            ],
+            [
+                0.648147,
+                0.979592
+            ],
+            [
+                0.694444,
+                0.979592
+            ],
+            [
+                0.740739,
+                0.979592
+            ],
+            [
+                0.796294,
+                1.0
+            ],
+            [
+                0.828703,
+                1.0
+            ],
+            [
+                0.861111,
+                1.0
+            ],
+            [
+                0.921294,
+                1.0
+            ],
+            [
+                0.953703,
+                1.0
+            ],
+            [
+                1.0,
+                1.0
+            ]
+        ],
+        "source": "light-commit-collapse.mp4",
+        "pts": [
+            1.756667,
+            2.116667
+        ],
+        "rmse": 0.21606191000218442
+    },
+    "contextEnter": {
+        "duration": 266.667,
+        "keyframes": [
+            [
+                0.0,
+                0.0
+            ],
+            [
+                0.0375,
+                0.118245
+            ],
+            [
+                0.106252,
+                0.24205
+            ],
+            [
+                0.125002,
+                0.242092
+            ],
+            [
+                0.20625,
+                0.38402
+            ],
+            [
+                0.2625,
+                0.527206
+            ],
+            [
+                0.3375,
+                0.649851
+            ],
+            [
+                0.39375,
+                0.733348
+            ],
+            [
+                0.443752,
+                0.834924
+            ],
+            [
+                0.524999,
+                0.876461
+            ],
+            [
+                0.575002,
+                0.936077
+            ],
+            [
+                0.650002,
+                0.957514
+            ],
+            [
+                0.706252,
+                0.978657
+            ],
+            [
+                0.762502,
+                0.99896
+            ],
+            [
+                0.824999,
+                0.99895
+            ],
+            [
+                0.8875,
+                0.998986
+            ],
+            [
+                0.937499,
+                0.99904
+            ],
+            [
+                1.0,
+                0.99904
+            ]
+        ],
+        "source": "light-lift.mp4",
+        "pts": [
+            1.693333,
+            1.96
+        ],
+        "rmse": 0.01980135953273082
+    },
+    "contextExit": {
+        "duration": 313.3330000000001,
+        "keyframes": [
+            [
+                0.0,
+                0.0
+            ],
+            [
+                0.047872,
+                0.079656
+            ],
+            [
+                0.101065,
+                0.160383
+            ],
+            [
+                0.154254,
+                0.281574
+            ],
+            [
+                0.207447,
+                0.420929
+            ],
+            [
+                0.265957,
+                0.521796
+            ],
+            [
+                0.324469,
+                0.641965
+            ],
+            [
+                0.372342,
+                0.722544
+            ],
+            [
+                0.425531,
+                0.801818
+            ],
+            [
+                0.484044,
+                0.842359
+            ],
+            [
+                0.500002,
+                0.842555
+            ],
+            [
+                0.526596,
+                0.919928
+            ],
+            [
+                0.537234,
+                0.920041
+            ],
+            [
+                0.590426,
+                0.939883
+            ],
+            [
+                0.606384,
+                0.940399
+            ],
+            [
+                0.622341,
+                0.95964
+            ],
+            [
+                0.632978,
+                0.959924
+            ],
+            [
+                0.686171,
+                0.979566
+            ],
+            [
+                0.702128,
+                0.979647
+            ],
+            [
+                0.739364,
+                0.979771
+            ],
+            [
+                0.750001,
+                0.979671
+            ],
+            [
+                0.787236,
+                0.999015
+            ],
+            [
+                0.840425,
+                0.99909
+            ],
+            [
+                0.893618,
+                0.999176
+            ],
+            [
+                0.904255,
+                0.999197
+            ],
+            [
+                0.957448,
+                0.999444
+            ],
+            [
+                0.962768,
+                0.99956
+            ],
+            [
+                1.0,
+                0.999698
+            ]
+        ],
+        "source": "light-dismiss.mp4",
+        "pts": [
+            0.845,
+            1.158333
+        ],
+        "rmse": 0.010989012706284985
+    },
+    "commitAdvance": {
+        "duration": 213.33300000000023,
+        "keyframes": [
+            [
+                0.0,
+                0
+            ],
+            [
+                0.03906099853281085,
+                0.21666666666666667
+            ],
+            [
+                0.10937360839626323,
+                0.4083333333333333
+            ],
+            [
+                0.11718768310575536,
+                0.4083333333333333
+            ],
+            [
+                0.16406275634805728,
+                0.65
+            ],
+            [
+                0.17187214355022454,
+                0.65
+            ],
+            [
+                0.24218475341367796,
+                0.65
+            ],
+            [
+                0.27343636474432054,
+                0.7833333333333333
+            ],
+            [
+                0.32812551269611356,
+                0.8666666666666667
+            ],
+            [
+                0.3359348998982808,
+                0.8666666666666667
+            ],
+            [
+                0.3906240478500748,
+                0.8666666666666667
+            ],
+            [
+                0.4062475097617342,
+                0.9083333333333333
+            ],
+            [
+                0.4140615844712263,
+                0.9083333333333333
+            ],
+            [
+                0.4765601196251866,
+                0.9083333333333333
+            ],
+            [
+                0.5078117309558292,
+                0.95
+            ],
+            [
+                0.5546868041981311,
+                0.9583333333333334
+            ],
+            [
+                0.5703102661097904,
+                0.9583333333333334
+            ],
+            [
+                0.6328134887710756,
+                0.9583333333333334
+            ],
+            [
+                0.6562510253922271,
+                0.9833333333333333
+            ],
+            [
+                0.7109354858366963,
+                0.9833333333333333
+            ],
+            [
+                0.7343730224578477,
+                0.9833333333333333
+            ],
+            [
+                0.8046856323213001,
+                1
+            ],
+            [
+                0.8906263916037368,
+                1
+            ],
+            [
+                0.9062498535153961,
+                1
+            ],
+            [
+                1.0,
+                1
+            ]
+        ]
+    }
+}

package/dist/actions/preview.d.ts

@@ -0,0 +1,27 @@
+/** The interaction host can contain layout wrappers. The lifted surface belongs
+ * to the selected semantic row, independently of swipe translation. Content that is
+ * not a row lifts itself (native snapshots the view, with its own shape), so a
+ * single child element is the source, not the framework's wrapper. */
+export declare function contextPreviewSource(anchor: HTMLElement, target?: Element | null): HTMLElement;
+export type PromotedContextSource = {
+    /** The promoted element, still in its own place in the DOM. */
+    element: HTMLElement;
+    /** Whether the source's place in the layout has moved (its scroller scrolled). */
+    moved(): boolean;
+    /** Return the source to its place in the layout. Safe to call more than once. */
+    restore(): void;
+    /** Static own-shape shadow for lifted content. Rows keep their box-shadow and pass null. */
+    shadow: HTMLElement | null;
+};
+/** Promote the existing source without changing its DOM ancestry or React ownership.
+ * A row lifts as a rounded cell; other content keeps its own shape and paint. */
+export declare function promoteContextSource(source: HTMLElement): PromotedContextSource;
+/** The longest a recognised context menu waits for its custom preview's images. The hold
+ * normally covers the decode; this only bounds a slow or failing image, which then shows
+ * as it arrives rather than holding the menu. */
+export declare const PREVIEW_DECODE_LIMIT_MS = 250;
+/** Resolves once every image in a custom preview is decoded (or has failed); undefined when
+ * there is nothing to wait for. A preview that moves before its pixels exist shows its empty
+ * backing for a few frames: the dark tile and late artwork the owner saw lifting an album
+ * (nowplaying-art-menu-glitch-2026-10-11). */
+export declare function decodePreviewImages(root: HTMLElement): Promise<void> | undefined;

package/dist/actions/preview.js

@@ -0,0 +1,217 @@
+/** The interaction host can contain layout wrappers. The lifted surface belongs
+ * to the selected semantic row, independently of swipe translation. Content that is
+ * not a row lifts itself (native snapshots the view, with its own shape), so a
+ * single child element is the source, not the framework's wrapper. */
+export function contextPreviewSource(anchor, target) {
+    const selected = target?.closest('[data-satin-row]');
+    if (selected && anchor.contains(selected))
+        return selected;
+    if (anchor.matches('[data-satin-row]'))
+        return anchor;
+    const rows = anchor.querySelectorAll('[data-satin-row]');
+    if (rows.length === 1)
+        return rows[0];
+    const content = anchor.querySelector('[data-satin-row-action-content]');
+    if (!content)
+        return anchor;
+    // A press during the previous lift's dismissal finds that lift's placeholder beside the
+    // content. It is not content: counting it lifted the wrapper instead.
+    const children = [...content.children].filter(child => !child.matches('[data-satin-context-placeholder]'));
+    const only = children.length === 1 ? children[0] : null;
+    return only instanceof HTMLElement ? only : content;
+}
+/** Promote the existing source without changing its DOM ancestry or React ownership.
+ * A row lifts as a rounded cell; other content keeps its own shape and paint. */
+export function promoteContextSource(source) {
+    const rect = source.getBoundingClientRect();
+    const width = source.offsetWidth;
+    const height = source.offsetHeight;
+    const style = source.getAttribute('style');
+    const popover = source.getAttribute('popover');
+    const content = !source.matches('[data-satin-row]');
+    // Resolved while the source is still in place, so the popover's UA canvas paint can
+    // be overwritten without cloning an unpromoted twin into the document.
+    const paint = content ? readOwnPaint(source) : null;
+    const shapes = content ? artworkShapes(source) : [];
+    const clone = content ? shadowClone(source) : null;
+    const placeholder = source.ownerDocument.createElement('div');
+    placeholder.style.width = `${width}px`;
+    placeholder.style.height = `${height}px`;
+    placeholder.setAttribute('aria-hidden', 'true');
+    placeholder.dataset.satinContextPlaceholder = 'true';
+    source.before(placeholder);
+    source.dataset.satinContextLift = content ? 'content' : 'row';
+    source.setAttribute('popover', 'manual');
+    Object.assign(source.style, {
+        position: 'fixed',
+        inset: 'auto',
+        margin: '0',
+        left: `${rect.left + (rect.width - width) / 2}px`,
+        top: `${rect.top + (rect.height - height) / 2}px`,
+        width: `${width}px`,
+        height: `${height}px`,
+    });
+    // Measured once the source has left the flow: until then the placeholder sits beside it, and a
+    // bottom-anchored list (a short chat thread) places both one source-height higher.
+    const resting = placeholder.getBoundingClientRect();
+    // The top layer's UA popover style paints a canvas background, border and padding.
+    let shadow = null;
+    if (content && clone && paint) {
+        applyOwnPaint(source, paint);
+        // The copy sits outside the source's ancestors, where styles that depend on them no longer
+        // match: a wrapper's cell paint (white corners behind a bubble) or a bubble's tail padding.
+        applyOwnPaint(clone, paint);
+        shadow = mountContentShadow(source, clone, shapes);
+    }
+    else
+        Object.assign(source.style, { border: '0', overflow: 'hidden' });
+    // The shadow plate enters the top layer first, so the lifted source paints over its clone.
+    shadow?.showPopover?.();
+    source.showPopover?.();
+    let restored = false;
+    return {
+        element: source,
+        shadow,
+        moved() {
+            const now = placeholder.getBoundingClientRect();
+            return Math.abs(now.top - resting.top) > 0.5 || Math.abs(now.left - resting.left) > 0.5;
+        },
+        restore() {
+            if (restored)
+                return;
+            restored = true;
+            if (shadow?.isConnected)
+                shadow.hidePopover?.();
+            shadow?.remove();
+            if (source.isConnected)
+                source.hidePopover?.();
+            if (popover === null)
+                source.removeAttribute('popover');
+            else
+                source.setAttribute('popover', popover);
+            if (style === null)
+                source.removeAttribute('style');
+            else
+                source.setAttribute('style', style);
+            delete source.dataset.satinContextLift;
+            placeholder.remove();
+        },
+    };
+}
+/** Popover UA styles stand in wherever the content's own styles are silent (a canvas
+ * background, a border, padding, clipping). Re-apply the used values the content had
+ * in place, read before promotion so no unpromoted twin is inserted. */
+const ownPaint = [
+    'background-color',
+    'color',
+    'overflow',
+    'padding-top',
+    'padding-right',
+    'padding-bottom',
+    'padding-left',
+    'border-top-style',
+    'border-right-style',
+    'border-bottom-style',
+    'border-left-style',
+    'border-top-width',
+    'border-right-width',
+    'border-bottom-width',
+    'border-left-width',
+];
+function readOwnPaint(source) {
+    const computed = getComputedStyle(source);
+    return ownPaint.map(property => computed.getPropertyValue(property));
+}
+function applyOwnPaint(source, values) {
+    for (let index = 0; index < ownPaint.length; index++)
+        source.style.setProperty(ownPaint[index], values[index]);
+}
+/** Glyph copy for the drop-shadow. Artwork is omitted: its alpha would force the
+ * blur to cover the whole image, which is the frame cost this plate avoids. */
+function shadowClone(source) {
+    const clone = source.cloneNode(true);
+    clone.removeAttribute('id');
+    clone.removeAttribute('popover');
+    delete clone.dataset.satinContextLift;
+    for (const element of clone.querySelectorAll('[id]'))
+        element.removeAttribute('id');
+    for (const image of clone.querySelectorAll('img, canvas, video'))
+        image.style.visibility = 'hidden';
+    Object.assign(clone.style, {
+        boxSizing: 'border-box',
+        width: '100%',
+        height: '100%',
+        margin: '0',
+        transform: 'none',
+    });
+    return clone;
+}
+/** One box per opaque artwork, in the source's border box, sampled once at promotion. */
+function artworkShapes(source) {
+    const origin = source.getBoundingClientRect();
+    const shapes = [];
+    for (const image of source.querySelectorAll('img, canvas, video')) {
+        const rect = image.getBoundingClientRect();
+        if (rect.width < 1 || rect.height < 1)
+            continue;
+        shapes.push({
+            left: `${rect.left - origin.left}px`,
+            top: `${rect.top - origin.top}px`,
+            width: `${rect.width}px`,
+            height: `${rect.height}px`,
+            borderRadius: getComputedStyle(image).borderRadius,
+        });
+    }
+    return shapes;
+}
+function mountContentShadow(source, clone, shapes) {
+    const document = source.ownerDocument;
+    const plate = document.createElement('div');
+    plate.dataset.satinContextShadow = 'true';
+    plate.setAttribute('popover', 'manual');
+    plate.setAttribute('aria-hidden', 'true');
+    plate.setAttribute('inert', '');
+    for (const shape of shapes) {
+        const layer = document.createElement('div');
+        layer.dataset.satinContextShadowShape = 'true';
+        Object.assign(layer.style, shape);
+        plate.append(layer);
+    }
+    const paint = document.createElement('div');
+    paint.dataset.satinContextShadowPaint = 'true';
+    paint.append(clone);
+    plate.append(paint);
+    Object.assign(plate.style, {
+        position: 'fixed',
+        inset: 'auto',
+        margin: '0',
+        padding: '0',
+        border: '0',
+        background: 'transparent',
+        overflow: 'visible',
+        pointerEvents: 'none',
+        left: source.style.left,
+        top: source.style.top,
+        width: source.style.width,
+        height: source.style.height,
+        willChange: 'transform, opacity',
+    });
+    document.body.append(plate);
+    return plate;
+}
+/** The longest a recognised context menu waits for its custom preview's images. The hold
+ * normally covers the decode; this only bounds a slow or failing image, which then shows
+ * as it arrives rather than holding the menu. */
+export const PREVIEW_DECODE_LIMIT_MS = 250;
+/** Resolves once every image in a custom preview is decoded (or has failed); undefined when
+ * there is nothing to wait for. A preview that moves before its pixels exist shows its empty
+ * backing for a few frames: the dark tile and late artwork the owner saw lifting an album
+ * (nowplaying-art-menu-glitch-2026-10-11). */
+export function decodePreviewImages(root) {
+    // An image without a source has nothing to decode; without decode() (older engines, test
+    // DOMs) there is nothing to wait on.
+    const pending = [...root.querySelectorAll('img')].filter(image => image.getAttribute('src') && typeof image.decode === 'function');
+    if (pending.length === 0)
+        return undefined;
+    return Promise.all(pending.map(image => image.decode().catch(() => undefined))).then(() => { });
+}

package/dist/actions/recognizers.d.ts

@@ -0,0 +1,24 @@
+import { type GestureBounds } from '../gestures/arena.js';
+export type InteractionCalibration = Readonly<{
+    claimDistance: number;
+    holdMilliseconds: number;
+    holdSlop: number;
+}>;
+/** The generic arena receives calibration from the interaction owner. */
+export declare function createRowArena(bounds: GestureBounds, options: {
+    canPop: boolean;
+    leading: boolean;
+    trailing: boolean;
+    context: boolean;
+    calibration: InteractionCalibration;
+}): Readonly<{
+    bounds: GestureBounds;
+    exclusions?: readonly import("../gestures/arena.js").GestureExclusion[];
+    recognizers: readonly import("../gestures/arena.js").GestureRecognizerDeclaration[];
+}>;
+export declare function registerRowNavigationOwner(host: Element, canPop: (target: Element) => boolean): () => void;
+export declare function rowCanPop(target: Element, clientX: number): boolean;
+/** Set before contact: native horizontal scrolling cannot be enabled after down. */
+export declare function rowSwipeTouchAction(nativeDriver: boolean, canPop: boolean, directionalPanning?: boolean): "pan-y" | "pan-y pan-right pinch-zoom";
+/** Sample the committed target policy at contact, not after direction lock. */
+export declare function rowBlocksNativeBack(target: Element | undefined): boolean;