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

package/dist/glass/worker/client.js

@@ -0,0 +1,152 @@
+import { readDarkAppearance } from '../../app/appearance.js';
+import { installGlassErrorAlert } from '../errorAlert.js';
+import { glassFailureCode } from '../webgpu/errorCode.js';
+import { reportGlassError } from '../errors.js';
+import { PageFrameHost } from '../webgpu/frameClock.js';
+export class WorkerGlassClient {
+    worker;
+    nextId = 0;
+    pending = new Map();
+    failed;
+    frames = new PageFrameHost();
+    backend = 'webgpu';
+    visibility = () => {
+        const visible = document.visibilityState === 'visible';
+        void this.request({ type: 'visible', visible }).catch(error => {
+            reportGlassError(glassFailureCode('worker control', error), error, 'worker control');
+        });
+        if (!visible)
+            this.frames.cancel();
+    };
+    work = [];
+    async init(canvas, resolution) {
+        installGlassErrorAlert();
+        try {
+            await this.initialize(canvas, resolution);
+        }
+        catch (error) {
+            reportGlassError(glassFailureCode('renderer initialization', error), error, 'renderer initialization');
+            throw error;
+        }
+    }
+    async initialize(canvas, resolution) {
+        // 7b: do not create the page context before visibility plus one frame.
+        if (document.visibilityState !== 'visible')
+            await new Promise(resolve => {
+                const listener = () => {
+                    if (document.visibilityState === 'visible') {
+                        document.removeEventListener('visibilitychange', listener);
+                        resolve();
+                    }
+                };
+                document.addEventListener('visibilitychange', listener);
+            });
+        await new Promise(resolve => requestAnimationFrame(() => resolve()));
+        this.worker = new Worker(new URL('../webgpu/entry.worker.js', import.meta.url), {
+            type: 'module',
+            name: 'satin-glass-webgpu',
+        });
+        this.worker.onerror = event => {
+            this.failed = new Error(event.message || 'Glass worker failed');
+            reportGlassError(glassFailureCode('worker startup/runtime', this.failed), this.failed, 'worker startup/runtime');
+            for (const request of this.pending.values())
+                request.reject(this.failed);
+            this.pending.clear();
+        };
+        this.worker.onmessageerror = () => {
+            this.failed = Error('Glass worker message could not be deserialized');
+            reportGlassError(glassFailureCode('worker transport', this.failed), this.failed, 'worker transport');
+            for (const request of this.pending.values())
+                request.reject(this.failed);
+            this.pending.clear();
+        };
+        this.worker.onmessage = event => {
+            if (this.frames.receive(event.data, data => this.worker.postMessage(data)))
+                return;
+            const { id, value, error, glassError } = event.data;
+            if (glassError) {
+                reportGlassError(glassError.code, glassError.message, glassError.stage, glassError.reason);
+                return;
+            }
+            const request = this.pending.get(id);
+            this.pending.delete(id);
+            if (error)
+                request?.reject(new Error(error));
+            else
+                request?.resolve(value);
+        };
+        let timeout;
+        try {
+            await Promise.race([
+                this.request({ type: 'capability' }),
+                new Promise((_, reject) => {
+                    timeout = setTimeout(() => reject(Error('WebGPU startup exceeded 2.5 seconds')), 2500);
+                }),
+            ]);
+            this.backend = 'webgpu';
+        }
+        catch (error) {
+            this.failed = error instanceof Error ? error : Error(String(error));
+            reportGlassError(glassFailureCode('WebGPU startup', this.failed), this.failed, 'WebGPU startup');
+            this.worker.terminate();
+            for (const pending of this.pending.values())
+                pending.reject(this.failed);
+            this.pending.clear();
+            throw this.failed;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        const offscreen = canvas.transferControlToOffscreen();
+        await this.request({
+            type: 'init',
+            canvas: offscreen,
+            resolution,
+            appearance: readDarkAppearance() ? 'dark' : 'light',
+        }, [offscreen]);
+        document.addEventListener('visibilitychange', this.visibility);
+    }
+    async attachLayer(canvas, layer) {
+        canvas.style.position = 'absolute';
+        canvas.style.pointerEvents = 'none';
+        canvas.style.zIndex = String(layer.depth);
+        canvas.dataset.satinGlassLayer = layer.id;
+        canvas.dataset.satinGlassAttachment = layer.attachment.kind;
+        if (layer.attachment.kind === 'scroll') {
+            const container = canvas.closest('[data-satin-scroll-container]');
+            if (container?.getAttribute('data-satin-scroll-container') !== layer.attachment.scrollId)
+                throw Error('Scroll glass canvas must be mounted inside its declared scroll container');
+        }
+        const offscreen = canvas.transferControlToOffscreen();
+        return this.request({ type: 'attach-layer', layer, canvas: offscreen }, [offscreen]);
+    }
+    request(request, transfer = []) {
+        if (this.failed)
+            return Promise.reject(this.failed);
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            try {
+                this.worker.postMessage({ id, request }, transfer);
+            }
+            catch (error) {
+                this.pending.delete(id);
+                reportGlassError(glassFailureCode('worker transport', error), error, 'worker transport');
+                reject(error);
+            }
+        });
+    }
+    pose(x, at) {
+        const start = performance.now(), request = { type: 'pose', x, at };
+        this.worker.postMessage({ id: 0, request });
+        this.work.push({ at, ms: performance.now() - start });
+        if (this.work.length > 2400)
+            this.work.shift();
+    }
+    park() {
+        this.frames.cancel();
+        document.removeEventListener('visibilitychange', this.visibility);
+        return this.request({ type: 'visible', visible: false });
+        // Do not terminate and recreate a glass worker within the same page.
+    }
+}

package/dist/glass/worker/experiment.d.ts

@@ -0,0 +1,13 @@
+import { type FrameSample } from './protocol.js';
+export declare function mountGlassWorkerExperiment(host: HTMLElement): Promise<unknown>;
+export declare function summarize(frames: FrameSample[]): {
+    frames: number;
+    medianMs: number;
+    p90Ms: number;
+    over20Percent: number | null;
+    maxMs: number | undefined;
+    cpuMedianMs: number;
+    cpuP90Ms: number;
+    poseErrorP90Px: number;
+    poseErrorMaxPx: number | undefined;
+};

package/dist/glass/worker/experiment.js

@@ -0,0 +1,221 @@
+import { reportGlassError } from '../errors.js';
+import { WorkerGlassClient } from './client.js';
+import { captureFixture, rasterSetup, fixtureMotion, WORKER_BACKDROPS, } from './fixture.js';
+import { epochNow, poseAt, } from './protocol.js';
+const mounted = new WeakMap();
+export function mountGlassWorkerExperiment(host) {
+    let existing = mounted.get(host);
+    if (!existing) {
+        existing = mount(host);
+        mounted.set(host, existing);
+    }
+    return existing;
+}
+async function mount(host) {
+    const params = new URLSearchParams(location.search);
+    host.innerHTML = `<h1>Glass worker feasibility</h1><p>Dedicated worker · WebGPU reference candidate, parity pending · synthetic motion, not phone acceptance</p>
+    <p id="status">Preparing renderer…</p><div style="position:relative;width:440px;height:318px;overflow:hidden;background:#888"><div id="page" style="position:absolute;inset:0;width:440px;background:linear-gradient(90deg,#ef476f,#118ab2)"></div><canvas id="glass" style="position:absolute;inset:0;width:440px;height:318px"></canvas></div>
+    <button id="sampled">Sampled pose + main stalls</button> <button id="timeline">Timeline + main stalls</button> <button id="export">Export measurements</button><pre id="result"></pre>`;
+    const status = host.querySelector('#status'), result = host.querySelector('#result');
+    const canvas = host.querySelector('#glass'), page = host.querySelector('#page');
+    const client = new WorkerGlassClient();
+    document.getElementById('satin-launch-screen')?.remove();
+    const launchStart = performance.now();
+    // Readiness failures remain visible even if asynchronous initialization later completes.
+    const fallback = setTimeout(() => {
+        reportGlassError('readiness-timeout', 'Glass worker was not ready within 2.5 seconds', 'diagnostic launch');
+    }, 2500);
+    try {
+        await client.init(canvas, Number(params.get('dpr') ?? 3));
+    }
+    catch (error) {
+        clearTimeout(fallback);
+        status.textContent = String(error);
+        throw error;
+    }
+    let setup = rasterSetup('light', 'dock', Number(params.get('dpr') ?? 3));
+    let capture, lastRun, sourceRevision = 0, currentBackdrop = 'photo-landscape';
+    const configure = async (backdrop = 'photo-landscape', appearance = 'light', kind = 'dock', lift, motion, trigger) => {
+        const revision = ++sourceRevision;
+        setup = fixtureMotion({ ...rasterSetup(appearance, kind, setup.resolution), lift, trigger }, motion);
+        setup = {
+            ...setup,
+            sourceKey: `fixture:${backdrop}:${appearance}:${setup.resolution}`,
+            glyphKey: `fixture-glyph:${appearance}:${kind}:${setup.resolution}`,
+        };
+        currentBackdrop = backdrop;
+        const value = await captureFixture(backdrop, setup);
+        if (revision !== sourceRevision) {
+            value.front.close();
+            value.rear.close();
+            value.glyphs.close();
+            return { superseded: true };
+        }
+        page.style.background = `url(/comparisons/measured-reference/backdrops/${backdrop}.png) left top / 440px auto`;
+        page.parentElement.style.background = `url(/comparisons/measured-reference/backdrops/${backdrop}.png) left bottom / 440px auto`;
+        const postStart = performance.now();
+        const installed = await client.request({
+            type: 'source',
+            revision,
+            setup,
+            front: value.front,
+            rear: value.rear,
+            glyphs: value.glyphs,
+            sentAt: epochNow(),
+        }, [value.front, value.rear, value.glyphs]);
+        capture = {
+            backdrop,
+            appearance,
+            kind,
+            captureMs: value.captureMs,
+            bitmapMs: value.bitmapMs,
+            mainCanvasBytes: value.mainCanvasBytes,
+            roundTripMs: performance.now() - postStart,
+            installed,
+        };
+        return capture;
+    };
+    await configure();
+    clearTimeout(fallback);
+    status.textContent = `Ready (${client.backend}). ${Math.round(performance.now() - launchStart)} ms including source preparation.`;
+    const run = async (mode = 'timeline', stallMs = 40, duration = 2200) => {
+        const plan = {
+            mode,
+            sourceRevision,
+            epoch: epochNow() + 100,
+            duration,
+            from: 0,
+            to: setup.width,
+        };
+        const blocked = [], poses = [];
+        client.work.length = 0;
+        const animation = page.animate([{ transform: 'translateX(0px)' }, { transform: `translateX(${setup.width}px)` }], { duration, fill: 'forwards', easing: 'linear' });
+        // Explicit same-clock WAAPI start. No claim of worker access to ScrollTimeline.
+        animation.startTime = plan.epoch - performance.timeOrigin;
+        await client.request({ type: 'run', plan });
+        await new Promise(resolve => {
+            let nextStall = plan.epoch + 180;
+            const tick = () => {
+                const at = epochNow(), expectedX = poseAt(plan, at);
+                const matrix = new DOMMatrixReadOnly(getComputedStyle(page).transform);
+                poses.push({ at, x: matrix.m41, expectedX });
+                if (mode === 'sampled')
+                    client.pose(matrix.m41, at);
+                if (stallMs && at >= nextStall && at < plan.epoch + duration - 100) {
+                    const start = performance.now();
+                    while (performance.now() - start < stallMs) {
+                        /* controlled CPU stall, excluded from render CPU cost */
+                    }
+                    blocked.push({ at, ms: performance.now() - start });
+                    nextStall += 200;
+                }
+                if (epochNow() < plan.epoch + duration + 100)
+                    requestAnimationFrame(tick);
+                else
+                    resolve();
+            };
+            requestAnimationFrame(tick);
+        });
+        animation.cancel();
+        const report = (await client.request({ type: 'report' }));
+        lastRun = {
+            worker: true,
+            mode,
+            stallMs,
+            plan,
+            blocked,
+            poses,
+            mainFrameWork: [...client.work],
+            report,
+            boundary: 'Frame times are renderer submissions. errorPx compares with the declared WAAPI timeline, not scanout. DOM pose reads exist only when the main thread runs.',
+        };
+        result.textContent = JSON.stringify(summarize(report.frames), null, 2);
+        return lastRun;
+    };
+    const addLayer = async (id, scroll = false) => {
+        const container = document.createElement('div');
+        container.style.cssText = 'position:relative;width:440px;height:200px;overflow:auto';
+        if (scroll)
+            container.setAttribute('data-satin-scroll-container', id);
+        const content = document.createElement('div');
+        content.style.cssText = 'position:relative;height:636px';
+        const extra = document.createElement('canvas');
+        extra.style.cssText = 'top:0;left:0;width:440px;height:318px';
+        content.append(extra);
+        container.append(content);
+        host.append(container);
+        await client.attachLayer(extra, {
+            id,
+            depth: 1,
+            attachment: scroll ? { kind: 'scroll', scrollId: id } : { kind: 'fixed' },
+        });
+        const value = await captureFixture(currentBackdrop, setup);
+        return client.request({
+            type: 'layer-source',
+            layerId: id,
+            setup,
+            front: value.front,
+            rear: value.rear,
+            glyphs: value.glyphs,
+        }, [value.front, value.rear, value.glyphs]);
+    };
+    const api = {
+        configure,
+        run,
+        addLayer,
+        snapshot: () => client.request({ type: 'snapshot' }),
+        request: client.request.bind(client),
+        report: () => client.request({ type: 'report' }),
+        capture: () => capture,
+        fixtures: WORKER_BACKDROPS,
+        readyMs: performance.now() - launchStart,
+        environment: {
+            backend: client.backend,
+            userAgent: navigator.userAgent,
+            worker: true,
+            standalone: matchMedia('(display-mode: standalone)').matches,
+            crossOriginIsolated,
+            sharedArrayBuffer: typeof SharedArrayBuffer !== 'undefined',
+            resolution: setup.resolution,
+        },
+    };
+    globalThis.__glass12u = api;
+    for (const mode of ['sampled', 'timeline'])
+        host.querySelector(`#${mode}`).addEventListener('click', () => {
+            void run(mode).catch(error => {
+                status.textContent = String(error);
+            });
+        });
+    host.querySelector('#export').addEventListener('click', () => {
+        const url = URL.createObjectURL(new Blob([JSON.stringify({ environment: api.environment, capture, lastRun }, null, 2)], {
+            type: 'application/json',
+        }));
+        const anchor = document.createElement('a');
+        anchor.href = url;
+        anchor.download = 'glass-12u.json';
+        anchor.click();
+        URL.revokeObjectURL(url);
+    });
+    return api;
+}
+export function summarize(frames) {
+    const intervals = frames
+        .flatMap(frame => (frame.interval === null ? [] : [frame.interval]))
+        .sort((a, b) => a - b);
+    const cpu = frames.map(frame => frame.cpuMs).sort((a, b) => a - b);
+    const error = frames.map(frame => frame.errorPx).sort((a, b) => a - b);
+    const quantile = (values, q) => values[Math.min(values.length - 1, Math.floor(values.length * q))] ?? null;
+    return {
+        frames: frames.length,
+        medianMs: quantile(intervals, 0.5),
+        p90Ms: quantile(intervals, 0.9),
+        over20Percent: intervals.length
+            ? (100 * intervals.filter(value => value > 20).length) / intervals.length
+            : null,
+        maxMs: intervals.at(-1),
+        cpuMedianMs: quantile(cpu, 0.5),
+        cpuP90Ms: quantile(cpu, 0.9),
+        poseErrorP90Px: quantile(error, 0.9),
+        poseErrorMaxPx: error.at(-1),
+    };
+}

package/dist/glass/worker/fixture.d.ts

@@ -0,0 +1,21 @@
+import type { Appearance } from '../lens/theme.js';
+import type { RasterSetup } from './protocol.js';
+export declare const WORKER_BACKDROPS: readonly ['abstract-1', 'abstract-2', 'abstract-3', 'abstract-4', 'app-list', 'app-settings', 'article-light', 'article-dark', 'photo-architecture', 'photo-foliage', 'photo-food', 'photo-landscape', 'photo-night', 'photo-portrait'];
+export type FixtureKind = 'dock' | 'lens' | 'menu';
+export declare function rasterSetup(appearance: Appearance, kind: FixtureKind, resolution?: number): RasterSetup;
+/** Captures only the bounded source needed by this experiment. Real app DOM
+ * capture, source-generation invalidation and glyph masking remain main-owned. */
+export declare function captureFixture(backdrop: string, setup: RasterSetup): Promise<{
+    front: ImageBitmap;
+    rear: ImageBitmap;
+    glyphs: ImageBitmap;
+    captureMs: number;
+    bitmapMs: number;
+    mainCanvasBytes: number;
+}>;
+export type FixtureMotion = {
+    kind: 'menu-open' | 'menu-close' | 'pill';
+    milliseconds: number;
+};
+/** Freeze both backends at the same model time, independent of rendering cadence. */
+export declare function fixtureMotion(setup: RasterSetup, motion?: FixtureMotion): RasterSetup;

package/dist/glass/worker/fixture.js

@@ -0,0 +1,152 @@
+import { sampleMenuMotion } from '../lens/menuMotion.js';
+import { TabMotion } from '../lens/tabMotion.js';
+import { stableTabSelection, tabSelectionCapsule } from '../lens/tabSelectionMaterial.js';
+export const WORKER_BACKDROPS = [
+    'abstract-1',
+    'abstract-2',
+    'abstract-3',
+    'abstract-4',
+    'app-list',
+    'app-settings',
+    'article-light',
+    'article-dark',
+    'photo-architecture',
+    'photo-foliage',
+    'photo-food',
+    'photo-landscape',
+    'photo-night',
+    'photo-portrait',
+];
+export function rasterSetup(appearance, kind, resolution = 3) {
+    const menu = kind === 'menu', width = 440, height = 318;
+    const frameWidth = menu ? 280 : 398, frameHeight = menu ? 230 : 62;
+    return {
+        appearance,
+        width,
+        height,
+        resolution,
+        spec: {
+            id: menu ? 'right' : 'dock',
+            frameX: menu ? 80 : 21,
+            frameY: menu ? 44 : 128,
+            frameWidth,
+            frameHeight,
+            radius: menu ? 32 : 30.8,
+            sampleHeight: height,
+            sampleWidth: menu ? 408 : 526,
+            sampleInsetX: 64,
+            sampleInsetY: menu ? 44 : 128,
+            shaderAperture: true,
+            materialMix: 1,
+            materialProfile: menu ? 'menu' : 'chrome',
+            shape: {
+                blendRadius: 0,
+                rimAlpha: 1,
+                whiteMix: 0,
+                first: {
+                    centerX: frameWidth / 2,
+                    centerY: frameHeight / 2,
+                    halfWidth: frameWidth / 2,
+                    halfHeight: frameHeight / 2,
+                    radius: menu ? 32 : 30.8,
+                },
+            },
+            tabSelection: menu
+                ? undefined
+                : {
+                    ...stableTabSelection(appearance),
+                    capsule: tabSelectionCapsule(1, [69, 199, 329], 107.5, 54),
+                    glyphCount: 3,
+                    lensMix: kind === 'lens' ? 1 : 0,
+                },
+        },
+    };
+}
+/** Captures only the bounded source needed by this experiment. Real app DOM
+ * capture, source-generation invalidation and glyph masking remain main-owned. */
+export async function captureFixture(backdrop, setup) {
+    if (!WORKER_BACKDROPS.some(value => value === backdrop))
+        throw new Error('Unknown 11f backdrop');
+    const image = new Image();
+    image.src = `/comparisons/measured-reference/backdrops/${backdrop}.png`;
+    await image.decode();
+    const started = performance.now(), { width, height, resolution } = setup;
+    const capture = (rear) => {
+        const canvas = document.createElement('canvas');
+        canvas.width = width * resolution;
+        canvas.height = height * resolution;
+        const ctx = canvas.getContext('2d');
+        // Same physical crop on both paths, with a distinct rear-page strip.
+        ctx.drawImage(image, 0, rear ? Math.max(0, image.height - canvas.height) : 0, image.width, Math.min(image.height, canvas.height), 0, 0, canvas.width, canvas.height);
+        return canvas;
+    };
+    const frontCanvas = capture(false), rearCanvas = capture(true), glyphCanvas = document.createElement('canvas');
+    glyphCanvas.width = setup.spec.sampleWidth * resolution;
+    glyphCanvas.height = height * resolution;
+    const ctx = glyphCanvas.getContext('2d');
+    ctx.scale(resolution, resolution);
+    ctx.fillStyle = setup.appearance === 'light' ? '#007aff' : '#0a84ff';
+    ctx.font = '600 12px system-ui';
+    ctx.textAlign = 'center';
+    for (const [index, label] of ['Home', 'Saved', 'Settings'].entries()) {
+        const x = setup.spec.sampleInsetX + [69, 199, 329][index];
+        ctx.fillText(label, x, setup.spec.sampleInsetY + 48);
+        ctx.beginPath();
+        ctx.arc(x, setup.spec.sampleInsetY + 21, 9, 0, 2 * Math.PI);
+        ctx.fill();
+    }
+    const capturedMs = performance.now() - started, bitmapStart = performance.now();
+    const options = {
+        premultiplyAlpha: 'premultiply',
+        colorSpaceConversion: 'none',
+    };
+    const [front, rear, glyphs] = await Promise.all([
+        createImageBitmap(frontCanvas, options),
+        createImageBitmap(rearCanvas, options),
+        createImageBitmap(glyphCanvas, options),
+    ]);
+    return {
+        front,
+        rear,
+        glyphs,
+        captureMs: capturedMs,
+        bitmapMs: performance.now() - bitmapStart,
+        mainCanvasBytes: (frontCanvas.width * frontCanvas.height +
+            rearCanvas.width * rearCanvas.height +
+            glyphCanvas.width * glyphCanvas.height) *
+            4,
+    };
+}
+/** Freeze both backends at the same model time, independent of rendering cadence. */
+export function fixtureMotion(setup, motion) {
+    if (!motion)
+        return setup;
+    if (motion.kind === 'pill') {
+        const tab = new TabMotion();
+        tab.configure([69, 199, 329], 107.5, 54, 398);
+        tab.reset(0);
+        tab.select(2, 0);
+        for (let at = 0; at < motion.milliseconds; at += 1000 / 120)
+            tab.sample(at, false);
+        tab.sample(motion.milliseconds, false);
+        return {
+            ...setup,
+            spec: {
+                ...setup.spec,
+                tabSelection: { ...setup.spec.tabSelection, capsule: tab.capsule(), lensMix: tab.lensMix },
+            },
+        };
+    }
+    const frame = sampleMenuMotion(motion.kind === 'menu-open' ? 'open' : 'close', motion.milliseconds / 1000, setup.appearance, false);
+    return {
+        ...setup,
+        spec: {
+            ...setup.spec,
+            shape: frame.shape,
+            radius: frame.shape.first.radius,
+            materialMix: frame.materialMix,
+            menuTintMix: frame.menuTintMix,
+            returningTrigger: frame.returningTrigger,
+        },
+    };
+}