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

package/dist/glass/webgpu/productionPinnedTop.d.ts

@@ -0,0 +1,80 @@
+import { type CaptureWindow } from '../captureWindow.js';
+import type { Appearance } from '../lens/theme.js';
+import type { BackdropLayer } from '../worker/protocol.js';
+/** A second capture of a long list: its top, kept while the list's own capture window is
+ * somewhere further down.
+ *
+ * A jump to the top is the one jump the framework knows the destination of in advance: the
+ * status bar tap, a tab selected again, `scrollToTop`. With only the list's own window the first
+ * frames at the top had nothing to sample until a capture of the top was read back (90 to 190 ms
+ * in the Catalyst host). The pinned window is installed under the list's window (Backdrop.under),
+ * so glass at the top shows the list's real rows from the first frame of the arrival.
+ *
+ * It costs one entry-size capture per long list that is scrolled away from its top (about 24 MB
+ * of bytes and as much texture on a phone). It is made from the rows the list's window is giving
+ * up when it first leaves the top (no capture at all), or from the page by an idle preparation.
+ * It does not cover the way to the top: a smooth scroll over more than the list's window passes
+ * content neither capture holds, and there the plane's fill is shown. */
+export type PinnedTop = {
+    /** The renderer's image key (its slot is `plane:<id>:top`). */
+    key: string;
+    window: CaptureWindow;
+    /** The plane's width in points, and what it was captured at. */
+    width: number;
+    resolution: number;
+    appearance: Appearance;
+    text: string;
+    /** The page changed inside the plane since this was captured. */
+    stale: boolean;
+};
+/** The window pinned at the top of a list: what an entry at its top captures. */
+export declare function pinnedTopWindow(viewport: number, contentHeight: number, resolution: number): CaptureWindow;
+/** Whether glass over a scrollport at `scrollTop` can take everything it samples from the pinned
+ * window. A stale one does not count: its rows may no longer be the list's. */
+export declare function pinnedTopCovers(pinned: PinnedTop | undefined, scrollTop: number, viewport: number, contentHeight: number): boolean;
+export type PinnedTopInput = {
+    /** The plane's own window in this revision (undefined: its whole content is captured). */
+    window: CaptureWindow | undefined;
+    viewport: number;
+    contentHeight: number;
+    resolution: number;
+    width: number;
+    appearance: Appearance;
+    text: string;
+    existing: PinnedTop | undefined;
+    /** The capture this revision replaces, when the plane is captured anew. */
+    outgoing: {
+        window: CaptureWindow | undefined;
+        width: number;
+        resolution: number;
+        appearance: Appearance;
+        text: string;
+        /** The page changed inside the plane since it was captured. */
+        damaged: boolean;
+        /** Its bytes are still held on the page (a capture read back in this document). */
+        hasBytes: boolean;
+    } | undefined;
+    /** This preparation may capture from the page: the scene is idle, or a jump to the top asked. */
+    mayCapture: boolean;
+};
+export type PinnedTopPlan = {
+    action: 'none';
+} | {
+    action: 'keep';
+} | {
+    action: 'release';
+} | {
+    action: 'crop';
+    window: CaptureWindow;
+    stale: boolean;
+} | {
+    action: 'capture';
+    window: CaptureWindow;
+};
+/** What to do about a plane's pinned top in one source revision. */
+export declare function planPinnedTop(input: PinnedTopInput): PinnedTopPlan;
+/** The first `rows` rows of a capture's bytes, copied (`width` in pixels, four bytes each). */
+export declare function cropTopRows(bytes: Uint8Array | Uint8ClampedArray, width: number, rows: number): Uint8Array<ArrayBuffer> | Uint8ClampedArray<ArrayBuffer>;
+/** The backdrop layer of a pinned top: under its plane's own layer, scrolling with it. Its lower
+ * edge is open (the list goes on) unless it reaches the end of the content. */
+export declare function pinnedTopLayer(plane: BackdropLayer, pinned: PinnedTop, planeWindowTop: number, contentHeight: number): BackdropLayer;

package/dist/glass/webgpu/productionPinnedTop.js

@@ -0,0 +1,77 @@
+import { planCaptureWindow, windowCoversScrollport } from '../captureWindow.js';
+/** The window pinned at the top of a list: what an entry at its top captures. */
+export function pinnedTopWindow(viewport, contentHeight, resolution) {
+    const window = planCaptureWindow({
+        scrollTop: 0,
+        viewport,
+        contentHeight,
+        resolution,
+        grow: false,
+        velocity: 0,
+    });
+    // Content an entry would capture whole has no window, and such a plane is never pinned.
+    return window ?? { top: 0, bottom: contentHeight, viewport };
+}
+/** Whether glass over a scrollport at `scrollTop` can take everything it samples from the pinned
+ * window. A stale one does not count: its rows may no longer be the list's. */
+export function pinnedTopCovers(pinned, scrollTop, viewport, contentHeight) {
+    return (!!pinned &&
+        !pinned.stale &&
+        windowCoversScrollport(pinned.window, scrollTop, viewport, contentHeight));
+}
+/** What to do about a plane's pinned top in one source revision. */
+export function planPinnedTop(input) {
+    const { window, existing, outgoing, mayCapture } = input;
+    const { viewport, contentHeight, resolution, width, appearance, text } = input;
+    // The list's own window holds the top (or the list is captured whole): nothing to pin.
+    if (!window || window.top <= 0)
+        return existing ? { action: 'release' } : { action: 'none' };
+    const wanted = pinnedTopWindow(viewport, contentHeight, resolution);
+    const matches = (capture) => capture.width === width &&
+        capture.resolution === resolution &&
+        capture.appearance === appearance &&
+        capture.text === text;
+    const current = existing && matches(existing) && existing.window.bottom >= wanted.bottom - 1 / 64;
+    if (existing && existing.window.bottom > contentHeight + 1 / 64)
+        return mayCapture ? { action: 'capture', window: wanted } : { action: 'release' };
+    if (current && !(existing.stale && mayCapture))
+        return { action: 'keep' };
+    if (mayCapture)
+        return { action: 'capture', window: wanted };
+    if (existing && matches(existing) && pinnedTopCovers(existing, 0, viewport, contentHeight))
+        return { action: 'keep' };
+    // The rows the list's window is giving up, when they are the list's top.
+    const fromOutgoing = !current &&
+        outgoing &&
+        outgoing.hasBytes &&
+        matches(outgoing) &&
+        outgoing.window !== undefined &&
+        outgoing.window.top <= 0 &&
+        outgoing.window.bottom >= wanted.bottom - 1 / 64;
+    if (fromOutgoing)
+        return { action: 'crop', window: wanted, stale: outgoing.damaged };
+    return existing ? { action: 'release' } : { action: 'none' };
+}
+/** The first `rows` rows of a capture's bytes, copied (`width` in pixels, four bytes each). */
+export function cropTopRows(bytes, width, rows) {
+    return bytes.slice(0, width * 4 * rows);
+}
+/** The backdrop layer of a pinned top: under its plane's own layer, scrolling with it. Its lower
+ * edge is open (the list goes on) unless it reaches the end of the content. */
+export function pinnedTopLayer(plane, pinned, planeWindowTop, contentHeight) {
+    return {
+        owner: plane.owner,
+        id: `${plane.id}:top`,
+        follows: plane.id,
+        key: `${pinned.key}:front`,
+        width: plane.width,
+        height: pinned.window.bottom,
+        resolution: pinned.resolution,
+        origin: { x: plane.origin.x, y: plane.origin.y - planeWindowTop },
+        clip: plane.clip,
+        scroll: plane.scroll,
+        fill: plane.fill,
+        ...(plane.fillEdges ? { fillEdges: plane.fillEdges } : {}),
+        openEdges: pinned.window.bottom < contentHeight - 1 / 64 ? 2 : 0,
+    };
+}

package/dist/glass/webgpu/productionPinnedTopPrepare.d.ts

@@ -0,0 +1,21 @@
+import type { SharedSourceImage } from '../worker/protocol.js';
+import type { ProductionGlassRuntime } from './production.js';
+import { type PinnedTop } from './productionPinnedTop.js';
+import { type Plane, type PlaneCapture, type PlaneCaptureFrame } from './productionPlanes.js';
+/** What one source revision changes about pinned tops: applied with its commit. */
+export type PinnedTopChanges = {
+    /** New pinned images, for the batch (slot `plane:<id>:top`). */
+    images: SharedSourceImage[];
+    /** Slots of pinned tops that are no longer kept. */
+    release: string[];
+    /** The pinned tops after the commit. */
+    next: Map<string, PinnedTop>;
+    /** Snapshot separately from the preparation revision: damage invalidates only this pin. */
+    generations: Map<string, number>;
+};
+/** Check immediately before the synchronous commit, after all preparation awaits have finished. */
+export declare function discardChangedPinnedTops(runtime: ProductionGlassRuntime, changes: PinnedTopChanges, opened: ImageBitmap[]): void;
+/** Decide and make each plane's pinned top for this revision (productionPinnedTop.ts): crop the
+ * capture a window is leaving, capture the top from the page when the preparation may, or let a
+ * pinned top go. Nothing of the runtime is changed here; the commit takes `next`. */
+export declare function preparePinnedTops(runtime: ProductionGlassRuntime, planes: readonly Plane[], captures: ReadonlyMap<string, PlaneCapture>, frame: PlaneCaptureFrame, text: string, capturedGenerations?: ReadonlyMap<string, number>): Promise<PinnedTopChanges>;

package/dist/glass/webgpu/productionPinnedTopPrepare.js

@@ -0,0 +1,132 @@
+import { cssColor } from './backdropLayers.js';
+import { rasterProductionSource } from './capture.js';
+import { releaseCaptureCanvas } from './captureRelease.js';
+import { keepSourcePixels, pixelImage, takeSourcePixels } from './preparedSourcePixels.js';
+import { cropTopRows, planPinnedTop } from './productionPinnedTop.js';
+import { measurePlane, } from './productionPlanes.js';
+import { traceStage, traceStageStart } from './profile.js';
+const slot = (id) => `plane:${id}:top`;
+/** Check immediately before the synchronous commit, after all preparation awaits have finished. */
+export function discardChangedPinnedTops(runtime, changes, opened) {
+    for (const [id, generation] of changes.generations) {
+        if ((runtime.damageGenerations?.get(id) ?? 0) === generation)
+            continue;
+        changes.next.delete(id);
+        const index = changes.images.findIndex(source => source.slot === slot(id));
+        if (index >= 0) {
+            const [{ image }] = changes.images.splice(index, 1);
+            if (image) {
+                const openedIndex = opened.indexOf(image);
+                if (openedIndex >= 0)
+                    opened.splice(openedIndex, 1);
+                image.close();
+            }
+        }
+        if (!changes.release.includes(slot(id)))
+            changes.release.push(slot(id));
+    }
+}
+/** Decide and make each plane's pinned top for this revision (productionPinnedTop.ts): crop the
+ * capture a window is leaving, capture the top from the page when the preparation may, or let a
+ * pinned top go. Nothing of the runtime is changed here; the commit takes `next`. */
+export async function preparePinnedTops(runtime, planes, captures, frame, text, capturedGenerations) {
+    const changes = {
+        images: [],
+        release: [],
+        next: new Map(),
+        generations: new Map(),
+    };
+    // A renderer in a worker takes bitmaps, which cannot be cropped or kept as bytes here.
+    if (!runtime.client.documentOwned)
+        return changes;
+    const { resolution, appearance } = frame;
+    for (const id of runtime.pinnedOrphans)
+        changes.release.push(slot(id));
+    for (const [id] of runtime.pinnedTops)
+        if (!planes.some(plane => plane.id === id && !plane.hidden))
+            changes.release.push(slot(id));
+    for (const plane of planes) {
+        if (plane.hidden)
+            continue;
+        changes.generations.set(plane.id, runtime.damageGenerations?.get(plane.id) ?? 0);
+        const existing = runtime.pinnedTops.get(plane.id);
+        const installed = captures.has(plane.id) ? runtime.planes.get(plane.id) : undefined;
+        const outgoingImage = installed ? runtime.planeImages.get(plane.id) : undefined;
+        const outgoingBytes = outgoingImage ? takeSourcePixels(outgoingImage) : undefined;
+        const viewport = Math.max(1, plane.host.clientHeight);
+        const plan = planPinnedTop({
+            window: plane.window,
+            viewport,
+            contentHeight: plane.contentHeight,
+            resolution,
+            width: plane.width,
+            appearance,
+            text,
+            existing,
+            outgoing: installed && {
+                // A capture of the whole content holds the top as a window from 0 does.
+                window: installed.window ?? { top: 0, bottom: installed.height, viewport },
+                width: installed.width,
+                resolution: installed.resolution,
+                appearance: installed.appearance,
+                text: installed.text,
+                damaged: runtime.damaged.has(plane.id),
+                hasBytes: !!outgoingBytes,
+            },
+            mayCapture: runtime.growPlanes.has(plane.id),
+        });
+        if (plan.action === 'none')
+            continue;
+        if (plan.action === 'keep') {
+            changes.next.set(plane.id, existing);
+            continue;
+        }
+        if (plan.action === 'release') {
+            changes.release.push(slot(plane.id));
+            continue;
+        }
+        const started = traceStageStart();
+        let image;
+        if (plan.action === 'crop') {
+            // Cropping keeps the older plane's pixels, not the page state at this pin's start.
+            if (capturedGenerations)
+                changes.generations.set(plane.id, capturedGenerations.get(plane.id) ?? 0);
+            const rows = Math.min(outgoingImage.height, Math.round(plan.window.bottom * resolution));
+            image = pixelImage(outgoingImage.width, rows);
+            keepSourcePixels(image, cropTopRows(outgoingBytes, outgoingImage.width, rows));
+        }
+        else
+            image = await capturePinnedTop(runtime, plane, plan.window, frame, appearance);
+        traceStage('pinned-top', started, () => `${plan.action} ${image.width}x${image.height}`);
+        const key = `backdrop:${plane.id}:top:${++runtime.captureRevision}`;
+        changes.images.push({ slot: slot(plane.id), key: `${key}:front`, image });
+        changes.next.set(plane.id, {
+            key,
+            window: plan.window,
+            width: plane.width,
+            resolution,
+            appearance,
+            text,
+            stale: plan.action === 'crop' && plan.stale,
+        });
+    }
+    return changes;
+}
+/** Capture the first `window.bottom` points of a plane's content from the page. */
+async function capturePinnedTop(runtime, plane, window, frame, appearance) {
+    runtime.preparingPinnedWindows ??= new Map();
+    runtime.preparingPinnedWindows.set(plane.id, window);
+    const top = await measurePlane(plane.host, frame, () => plane.id, false, undefined, window);
+    if (!top)
+        throw Error(`Glass pinned top: ${plane.id} is clipped out of the screen`);
+    const canvas = document.createElement('canvas');
+    try {
+        await rasterProductionSource(canvas, top.measured, top.width, top.height, frame.resolution, appearance === 'dark', cssColor(top.fill));
+        const image = pixelImage(canvas.width, canvas.height);
+        await runtime.sourcePixels.prepare(image, canvas);
+        return image;
+    }
+    finally {
+        releaseCaptureCanvas(canvas);
+    }
+}

package/dist/glass/webgpu/productionPlanes.d.ts

@@ -0,0 +1,135 @@
+import { type SampleRect } from './captureBands.js';
+import { LazyRegularMaterialContext } from '../regularMaterialContext.js';
+import type { Appearance } from '../lens/theme.js';
+import type { RuntimeGeometry, SurfaceRenderSpec } from '../renderSpecs.js';
+import type { BackdropLayer } from '../worker/protocol.js';
+import { type MeasuredSource } from './capture.js';
+import { type PinnedTop } from './productionPinnedTop.js';
+import { type CaptureBand, type PlaneDemand } from './captureDemand.js';
+import { type CaptureWindow } from '../captureWindow.js';
+export type MaterialContext = {
+    sample: LazyRegularMaterialContext['sample'];
+};
+/** An installed plane capture: worker image key and the settled viewport geometry it was taken at. */
+export type PlaneEntry = {
+    searchAnchor?: MeasuredSource['searchAnchor'];
+    keyboardAnchor?: MeasuredSource['keyboardAnchor'];
+    window?: CaptureWindow;
+    /** The only rows the capture holds: the ones glass samples (captureDemand.ts). */
+    bands?: readonly CaptureBand[];
+    signature: string;
+    key: string;
+    revision: number;
+    origin: {
+        x: number;
+        y: number;
+    };
+    width: number;
+    height: number;
+    resolution: number;
+    host: HTMLElement;
+    appearance: Appearance;
+    text: string;
+};
+/** Dynamic Type: the root's resolved system body size. A capture made at another text size is stale. */
+export declare const textKey: () => string;
+export type Plane = {
+    id: string;
+    host: HTMLElement;
+    measured: MeasuredSource;
+    origin: {
+        x: number;
+        y: number;
+    };
+    clip: readonly [number, number, number, number];
+    fill: readonly [number, number, number, number];
+    width: number;
+    height: number;
+    signature: string;
+    hidden?: boolean;
+    window?: CaptureWindow;
+    /** The only rows the capture holds: the ones glass samples (captureDemand.ts). */
+    bands?: readonly CaptureBand[];
+    /** The height of the host's whole content in points (a window holds a part of it). */
+    contentHeight: number;
+};
+/** A fresh capture of a plane, with the signature it installs under. */
+export type PlaneCapture = {
+    bitmap: ImageBitmap;
+    signature: string;
+};
+/** Page background behind every plane, straight RGB. */
+export type PageColour = readonly [number, number, number];
+/** What every plane of one preparation is captured at. */
+export type PlaneCaptureFrame = {
+    page: PageColour;
+    resolution: number;
+    appearance: Appearance;
+    /** Glass is waiting for this capture (ProductionGlassRuntime.coverFor): a presentation that
+     * moves elsewhere (a sheet held for its glass) does not delay a plane that is not in it. */
+    covering?: boolean;
+};
+/** What the runtime knows about a plane when its capture window is chosen (captureWindow.ts,
+ * "Bounded capture"). */
+export type PlaneWindowHint = {
+    /** What the plane holds now, installed or resident: a window, the whole content, or nothing. */
+    current?: CaptureWindow | 'full';
+    /** The bands it holds instead of its whole content (captureDemand.ts). */
+    bands?: readonly CaptureBand[];
+    /** The scene is idle: an entry window may grow. */
+    grow: boolean;
+    /** The host's scroll speed in points per second (positive: towards the end of the content). */
+    velocity: number;
+    /** What glass samples, for a host that does not scroll (captureDemand.ts). */
+    demand?: PlaneDemand;
+};
+/** Measure one backdrop host as a plane (undefined when it is clipped out of the screen). A hidden
+ * plane (a collapsed sidebar's navigation source) keeps its capture but shows nothing. With a
+ * `windowHint` a scrolling host is measured and captured for a bounded window (the default in
+ * production); without one, for its whole content. */
+export declare function measurePlane(host: HTMLElement, frame: PlaneCaptureFrame, planeId: (host: HTMLElement) => string, hidden?: boolean, windowHint?: (id: string, host: HTMLElement) => PlaneWindowHint, 
+/** Measure exactly this window (a window pinned at the top of a list), whatever the host's
+ * scroll offset and whatever the plane holds. */
+forcedWindow?: CaptureWindow, 
+/** Publish the immutable capture bounds before asynchronous source measurement. */
+captureChosen?: (id: string, capture: Pick<PlaneEntry, 'host' | 'window' | 'width'>) => void): Promise<Plane | undefined>;
+/** The plane that holds the navigation source, when it is part of the visible screen. */
+export declare function findVisibleContentPlane(planes: readonly Plane[], contentHost: HTMLElement): Plane | undefined;
+/** The material context of this exact plane set (ids, captures, geometry, scroll): valid only
+ * when every plane is unchanged, so a retained set comes back with the context it had. */
+export declare function planeSetContextKey(planes: readonly Plane[], contentPlane: Plane, geometry: RuntimeGeometry, page: PageColour): string;
+/** The visible plane SET and the capture each one holds: a change rebuilds the material context. */
+export declare function visiblePlaneSetKey(planes: readonly Plane[], installed: ReadonlyMap<string, PlaneEntry>, contentPlane: Plane, geometry: RuntimeGeometry): string;
+/** A rectangle of the material context that is read back, in its sample coordinates (the
+ * navigation plane's content space): x, y, width, height in points. */
+export type ContextArea = readonly [number, number, number, number];
+/** Material context (trigger and tab-glyph regimes) read from the composed screen, in the
+ * navigation plane's content space: rows move with its scroll, not with the viewport. Only
+ * `areas` are read back now (where the trigger and the tab glyphs sample), never the screen. */
+export declare function composeMaterialContext(contextCanvas: HTMLCanvasElement, planes: readonly Plane[], planeCanvases: ReadonlyMap<string, {
+    canvas: HTMLCanvasElement;
+}>, contentPlane: Plane, geometry: RuntimeGeometry, frame: Pick<PlaneCaptureFrame, 'page' | 'resolution'>, areas: readonly ContextArea[], overlayAlpha?: number): {
+    context: MaterialContext;
+    bytes: number;
+};
+/** Where the material context is sampled (`applyTabGlyphContext`, `triggerValues`), in its sample
+ * coordinates: the tab glyph discs and the trigger's disc, at every offset the navigation scroller
+ * can reach (a context is kept while the list scrolls under it). Rubber-band offsets beyond the
+ * ends reach at most one viewport further. A screen that does not scroll needs only the discs. */
+export declare function materialContextAreas(specs: readonly SurfaceRenderSpec[], scroller: {
+    scrollHeight: number;
+    clientHeight: number;
+}, viewport: number): ContextArea[];
+/** The disc each tab's glyph colour is read from (points). */
+export declare const TAB_CONTEXT_RADIUS = 24;
+/** Where `triggerValues` samples the context, relative to the trigger surface's frame (points). */
+export declare const TRIGGER_CONTEXT_X = 241;
+export declare const TRIGGER_CONTEXT_Y = 50;
+/** The worker's backdrop layers for the visible planes. Scroll offsets are read now (at commit):
+ * later scroll events are ordered after this batch. */
+export declare function backdropLayers(planes: readonly Plane[], installed: ReadonlyMap<string, PlaneEntry>, resolution: number, pinnedTops?: ReadonlyMap<string, PinnedTop>): BackdropLayer[];
+/** A capture measured before an asynchronous readback may already be behind the drawer.
+ * Check the exact renderer mapping before replacing its installed source. */
+export declare function uncoveredCapturePlane(planes: readonly Plane[], rects: readonly SampleRect[], resolution: number): string | undefined;
+/** One diagnostic line per plane for the prepared-event record. */
+export declare function planeDiagnostics(plane: Plane): string;