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

package/dist/glass/webgpu/areaMips.js

@@ -0,0 +1,166 @@
+/// <reference types="@webgpu/types" />
+import { shaderModule } from './errors.js';
+import { encodeComputePass } from './passes.js';
+/** The bar material's blur pyramid: its wide diffusion reads coarse levels (level 5 to 6 at
+ * half resolution, texels of 21 to 43 pt), so the pyramid decides how bright the glass's interior
+ * reads over any detail in the backdrop.
+ *
+ * Two things keep that brightness a property of the backdrop alone, not of the shape's size.
+ *
+ * Every destination texel is the exact area average of the source texels it covers. With one
+ * bilinear tap at the destination centre, a chain that is not a power of two (the tab bar's is
+ * 789 x 477) gave whole bands of the backdrop no weight and others double weight: text scrolling
+ * under the bar lit its blur at some heights and vanished from it at others.
+ *
+ * The storage is a whole number of coarse texels (PYRAMID_GRID), so each level is exactly half
+ * the one below and a level-k texel always covers the same 2^k level-0 texels, counted from the
+ * sample rectangle's top-left corner. When the storage was the content rounded up, every level's
+ * texel size followed the surface's width: a growing Music accessory moved the coarse texels'
+ * edges across the tiles under it and its interior dimmed and brightened by several luma levels
+ * over a still backdrop, then stepped when the run ended at a narrower width. Storage past the
+ * content carries no weight: a coarse texel at the content's edge averages only the content it
+ * covers, and the shader's reads stop at the content (pyramidClamp). A wider surface changes
+ * only the texels at its edge; the ones away from it stay exactly as they were. */
+/** Level-0 texels per side of the coarsest exact texel (level 6, the wide diffusion's deepest). */
+export const PYRAMID_GRID = 64;
+/** Storage for `extent` level-0 texels of content: a whole number of PYRAMID_GRID cells. */
+export function pyramidStorage(extent) {
+    return Math.max(1, Math.ceil(Math.ceil(extent) / PYRAMID_GRID)) * PYRAMID_GRID;
+}
+/** Level-0 texels the content copy writes for a content extent: those whose centre lies inside
+ * it (the copy's scissor in passes.ts). */
+export function pyramidContent(extent) {
+    return Math.max(1, Math.ceil(extent - 0.5));
+}
+/** The kernel's read clamp for a pyramid whose level 0 holds `content` texels: half a texel
+ * inside the content, so no sample reaches the cleared storage past it. Same layout as
+ * rasterUniforms.ts inputUniforms' uInputClamp. */
+export function pyramidClamp(target, content) {
+    return [
+        0.5 / target.width,
+        0.5 / target.height,
+        (content[0] - 0.5) / target.width,
+        (content[1] - 0.5) / target.height,
+    ];
+}
+/** Texels of content at each level, fractional: a level keeps the content's share of its size. */
+export function contentLevels(target, content) {
+    const levels = areaMipLevels(target);
+    const result = [[content[0], content[1]]];
+    for (let level = 1; level < levels.length; level++) {
+        const [width, height] = result[level - 1];
+        const below = levels[level - 1];
+        const here = levels[level];
+        result.push([(width * here.width) / below.width, (height * here.height) / below.height]);
+    }
+    return result;
+}
+/** One axis of a destination texel's footprint over the level below: the source texels it
+ * overlaps and how much of each, counting only the part inside the content. Mirrors
+ * `footprint` in the compute shader; texel t spans [t, t + 1]. */
+export function footprint(index, ratio, content) {
+    const start = index * ratio;
+    const end = start + ratio;
+    const taps = [];
+    for (let texel = Math.floor(start); texel < end; texel++) {
+        const overlap = Math.min(texel + 1, end) - Math.max(texel, start);
+        const inside = Math.min(1, Math.max(0, content - texel));
+        if (overlap > 0 && inside > 0)
+            taps.push({ texel, weight: overlap * inside });
+    }
+    return taps;
+}
+// Each destination texel is the average of the source texels under it, weighted by how much of
+// each it covers and how much of each is content. A texel at the content's edge is the average
+// of the content it covers; one wholly past the content repeats the nearest content texel.
+const areaMipCompute = `@group(0) @binding(0) var source: texture_2d<f32>;
+@group(0) @binding(1) var destination: texture_storage_2d<rgba8unorm, write>;
+// xy: the source level's content in texels, fractional (contentLevels).
+@group(0) @binding(2) var<uniform> sourceContent: vec4f;
+@compute @workgroup_size(8,8) fn main(@builtin(global_invocation_id) id: vec3u) {
+ let size = textureDimensions(destination);
+ if (id.x >= size.x || id.y >= size.y) { return; }
+ let sourceSize = vec2i(textureDimensions(source));
+ let ratio = vec2f(sourceSize) / vec2f(size);
+ let start = vec2f(id.xy) * ratio;
+ let end = start + ratio;
+ let first = vec2i(floor(start));
+ var sum = vec4f(0.0);
+ var weight = 0.0;
+ // A footprint spans at most four texels per axis: level sizes halve rounding down, so the
+ // ratio is at most 3.
+ for (var dy = 0; dy < 4; dy++) {
+  for (var dx = 0; dx < 4; dx++) {
+   let texel = first + vec2i(dx, dy);
+   if (any(texel >= sourceSize)) { continue; }
+   let corner = vec2f(texel);
+   let overlap = max(vec2f(0.0), min(corner + 1.0, end) - max(corner, start));
+   let inside = clamp(sourceContent.xy - corner, vec2f(0.0), vec2f(1.0));
+   let w = overlap.x * overlap.y * inside.x * inside.y;
+   sum += textureLoad(source, texel, 0) * w;
+   weight += w;
+  }
+ }
+ if (weight > 0.0) {
+  textureStore(destination, id.xy, sum / weight);
+ } else {
+  let last = max(vec2i(ceil(sourceContent.xy)) - 1, vec2i(0));
+  textureStore(destination, id.xy, textureLoad(source, min(first, last), 0));
+ }
+}`;
+const pipelines = new WeakMap();
+const levelCache = new WeakMap();
+/** One view per mip level of a pyramid target (created once per texture). */
+export function areaMipLevels(target) {
+    let levels = levelCache.get(target.texture);
+    if (!levels) {
+        levels = Array.from({ length: target.levels }, (_, level) => ({
+            view: target.texture.createView({ baseMipLevel: level, mipLevelCount: 1 }),
+            width: Math.max(1, target.width >> level),
+            height: Math.max(1, target.height >> level),
+        }));
+        levelCache.set(target.texture, levels);
+    }
+    return levels;
+}
+/** Fill every level above 0 of `target` from the level below, in one compute pass. Level 0
+ * holds `content` texels of backdrop; `uniform` makes a uniform buffer (Passes.uniform). */
+export function encodeAreaMips(encoder, device, target, content, uniform) {
+    if (target.levels < 2)
+        return;
+    let pipeline = pipelines.get(device);
+    if (!pipeline) {
+        const module = shaderModule(device, { label: 'area-mips', code: areaMipCompute });
+        pipeline = device.createComputePipeline({
+            label: 'area-mips',
+            layout: 'auto',
+            compute: { module, entryPoint: 'main' },
+        });
+        pipelines.set(device, pipeline);
+    }
+    const levels = areaMipLevels(target);
+    const contents = contentLevels(target, content);
+    const layout = pipeline.getBindGroupLayout(0);
+    const steps = levels.slice(1).map((level, index) => ({
+        level,
+        group: device.createBindGroup({
+            layout,
+            entries: [
+                { binding: 0, resource: levels[index].view },
+                { binding: 1, resource: level.view },
+                {
+                    binding: 2,
+                    resource: { buffer: uniform(new Float32Array([...contents[index], 0, 0])) },
+                },
+            ],
+        }),
+    }));
+    const compute = pipeline;
+    encodeComputePass(encoder, pass => {
+        pass.setPipeline(compute);
+        for (const { level, group } of steps) {
+            pass.setBindGroup(0, group);
+            pass.dispatchWorkgroups(Math.ceil(level.width / 8), Math.ceil(level.height / 8));
+        }
+    }, 'area-mips');
+}

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

@@ -0,0 +1,86 @@
+import type { KeyboardBackdrop } from './keyboardBackdrop.js';
+import { type GraphLease } from './frameGraph.js';
+import type { LayerDevice } from './layers.js';
+import type { Target } from './passes.js';
+import type { BackdropLayer } from '../worker/protocol.js';
+import type { ScrollEdge } from './scrollEdgeBackdrop.js';
+import type { NavigationPose } from './productionTracks.js';
+type Rect = readonly [number, number, number, number];
+type Plane = {
+    originY: number;
+    layer: BackdropLayer;
+    image: GraphLease<ImageBitmap>;
+    texture?: GraphLease<Target>;
+};
+/** Intersection of two viewport rectangles, or undefined when they do not overlap. */
+export declare function intersect(a: Rect, b: Rect): Rect | undefined;
+/** The screen-space backdrop every glass surface samples: planes (content-space
+ * captures of visible scroll containers and static screens) composed back to front
+ * over the page background, each at its live scroll offset and clipped to its
+ * viewport rectangle. Only the rectangles under glass are ever composed. */
+export declare class Backdrop {
+    static for(owner: LayerDevice): Backdrop;
+    private planes;
+    /** Navigation-bar scroll edges, composed over the planes under the bars. */
+    private edges;
+    private graph;
+    private constructor();
+    get layers(): readonly BackdropLayer[];
+    get size(): number;
+    /** A screen backdrop was installed (possibly empty: the page background alone). Surfaces
+     * then compose from it; before that they sample their own single capture. */
+    get installed(): boolean;
+    private isInstalled;
+    /** Replace the plane set. New images are retained before old ones are released, so a
+     * plane whose key survives keeps its upload. Every key must already be retained
+     * in the frame graph (a shared slot image); a missing one throws. */
+    setLayers(layers: readonly BackdropLayer[]): void;
+    /** Detach invalid or disposed pinned textures and restore the parent window's fill. */
+    removePinned(ids: readonly string[]): void;
+    /** Live scroll of one plane; false when unchanged or unknown. */
+    setScroll(id: string, x: number, y: number): boolean;
+    /** Only the capture that supplied the anchor may consume its trajectory. */
+    setKeyboard(id: string, key: string, keyboard: KeyboardBackdrop, scroll: {
+        x: number;
+        y: number;
+    }): void;
+    private keyboardSampledAt;
+    get keyboardMoving(): boolean;
+    /** Pose captured content before refraction, on the same clock as the lens. */
+    sampleKeyboard(at: number): boolean;
+    /** Replace the scroll-edge set; false when unchanged. */
+    setEdges(edges: readonly ScrollEdge[]): boolean;
+    /** Scroll edges that overlap a viewport rectangle. */
+    edgesUnder(rect: Rect, pose?: NavigationPose): ScrollEdge[];
+    /** Drop GPU storage (hidden page); images stay retained for the resume upload. */
+    suspend(): void;
+    clear(): void;
+    /** Planes that contribute to a viewport rectangle, back to front, with their clipped rectangle. */
+    under(rect: Rect, excluded?: readonly string[], menu?: boolean): {
+        plane: Plane;
+        clip: Rect;
+    }[];
+    /** Everything that decides the composed pixels of `rect`, relative to `rect`: a surface
+     * that moves with its plane (scroll-attached glass) keeps the same key while scrolling. */
+    keyFor(rect: Rect, skip?: string, excluded?: readonly string[], belowEdges?: boolean, menu?: boolean, pose?: NavigationPose): string;
+    /** GPU texture for a plane's capture (shared with any raster using the same key). */
+    texture(plane: Plane): Target;
+    report(): {
+        id: string;
+        owner: string | undefined;
+        resolution: number;
+        key: string;
+        origin: {
+            x: number;
+            y: number;
+        };
+        clip: readonly [number, number, number, number];
+        scroll: {
+            x: number;
+            y: number;
+        };
+        size: number[];
+        uploaded: boolean;
+    }[];
+}
+export {};

package/dist/glass/webgpu/backdrop.js

@@ -0,0 +1,243 @@
+import { sampleKeyboardTranslation } from '../../keyboard/translation.js';
+import { FrameGraph } from './frameGraph.js';
+import { poseScrollEdges } from './scrollEdgePose.js';
+const backdrops = new WeakMap();
+/** Intersection of two viewport rectangles, or undefined when they do not overlap. */
+export function intersect(a, b) {
+    const x = Math.max(a[0], b[0]), y = Math.max(a[1], b[1]), r = Math.min(a[0] + a[2], b[0] + b[2]), bottom = Math.min(a[1] + a[3], b[1] + b[3]);
+    return r > x && bottom > y ? [x, y, r - x, bottom - y] : undefined;
+}
+/** The screen-space backdrop every glass surface samples: planes (content-space
+ * captures of visible scroll containers and static screens) composed back to front
+ * over the page background, each at its live scroll offset and clipped to its
+ * viewport rectangle. Only the rectangles under glass are ever composed. */
+export class Backdrop {
+    static for(owner) {
+        let backdrop = backdrops.get(owner);
+        if (!backdrop) {
+            backdrop = new Backdrop(owner);
+            backdrops.set(owner, backdrop);
+        }
+        return backdrop;
+    }
+    planes = [];
+    /** Navigation-bar scroll edges, composed over the planes under the bars. */
+    edges = [];
+    graph;
+    constructor(owner) {
+        this.graph = FrameGraph.for(owner);
+        // A lost device invalidates every texture; planes re-upload from their retained images.
+        owner.subscribe(device => {
+            if (!device)
+                for (const plane of this.planes)
+                    plane.texture = undefined;
+        });
+    }
+    get layers() {
+        return this.planes.map(plane => plane.layer);
+    }
+    get size() {
+        return this.planes.length;
+    }
+    /** A screen backdrop was installed (possibly empty: the page background alone). Surfaces
+     * then compose from it; before that they sample their own single capture. */
+    get installed() {
+        return this.isInstalled;
+    }
+    isInstalled = false;
+    /** Replace the plane set. New images are retained before old ones are released, so a
+     * plane whose key survives keeps its upload. Every key must already be retained
+     * in the frame graph (a shared slot image); a missing one throws. */
+    setLayers(layers) {
+        const previous = this.planes;
+        this.isInstalled = true;
+        this.planes = layers.map(layer => {
+            const kept = previous.find(plane => plane.layer.key === layer.key);
+            return {
+                originY: layer.origin.y,
+                layer,
+                image: this.graph.retain(layer.key),
+                texture: kept?.texture
+                    ? this.graph.target('front', kept.texture.value.width, kept.texture.value.height, false, layer.key)
+                    : undefined,
+            };
+        });
+        this.sampleKeyboard(performance.timeOrigin + performance.now());
+        for (const plane of previous) {
+            plane.texture?.release();
+            plane.image.release();
+        }
+    }
+    /** Detach invalid or disposed pinned textures and restore the parent window's fill. */
+    removePinned(ids) {
+        const removed = new Set(ids);
+        this.setLayers(this.planes
+            .map(({ layer, originY }) => ({ ...layer, origin: { ...layer.origin, y: originY } }))
+            .filter(layer => !layer.follows || !removed.has(layer.follows))
+            .map(layer => {
+            if (!removed.has(layer.id))
+                return layer;
+            const { band: _band, ...rest } = layer;
+            return rest;
+        }));
+    }
+    /** Live scroll of one plane; false when unchanged or unknown. */
+    setScroll(id, x, y) {
+        let changed = false;
+        // A window pinned at the top of a list scrolls with the list's own window.
+        for (const plane of this.planes) {
+            if (plane.layer.id !== id && plane.layer.follows !== id)
+                continue;
+            if (plane.layer.scroll.x === x && plane.layer.scroll.y === y)
+                continue;
+            plane.layer = { ...plane.layer, scroll: { x, y } };
+            changed = true;
+        }
+        return changed;
+    }
+    /** Only the capture that supplied the anchor may consume its trajectory. */
+    setKeyboard(id, key, keyboard, scroll) {
+        if (!this.planes.some(({ layer }) => layer.id === id && layer.key === key))
+            return;
+        if (keyboard.motion)
+            this.keyboardSampledAt = Math.min(this.keyboardSampledAt, keyboard.motion.epoch - 1);
+        for (const plane of this.planes) {
+            if (plane.layer.id !== id && plane.layer.follows !== id)
+                continue;
+            // Pinned windows share their parent's content origin and keyboard displacement.
+            plane.layer = { ...plane.layer, keyboard, scroll };
+        }
+    }
+    keyboardSampledAt = -Infinity;
+    get keyboardMoving() {
+        return this.planes.some(({ layer }) => layer.keyboard?.motion && this.keyboardSampledAt < layer.keyboard.motion.end);
+    }
+    /** Pose captured content before refraction, on the same clock as the lens. */
+    sampleKeyboard(at) {
+        this.keyboardSampledAt = at;
+        let changed = false;
+        for (const plane of this.planes) {
+            const keyboard = plane.layer.keyboard;
+            const offset = keyboard?.motion
+                ? sampleKeyboardTranslation(keyboard.motion, at)
+                : (keyboard?.offsetY ?? 0);
+            const y = plane.originY + offset;
+            if (plane.layer.origin.y === y)
+                continue;
+            plane.layer = { ...plane.layer, origin: { ...plane.layer.origin, y } };
+            changed = true;
+        }
+        return changed;
+    }
+    /** Replace the scroll-edge set; false when unchanged. */
+    setEdges(edges) {
+        const next = JSON.stringify(edges);
+        if (next === JSON.stringify(this.edges))
+            return false;
+        this.edges = edges;
+        return true;
+    }
+    /** Scroll edges that overlap a viewport rectangle. */
+    edgesUnder(rect, pose) {
+        return poseScrollEdges(this.edges, pose).filter(edge => !!intersect(rect, edge.rect));
+    }
+    /** Drop GPU storage (hidden page); images stay retained for the resume upload. */
+    suspend() {
+        for (const plane of this.planes) {
+            plane.texture?.release();
+            plane.texture = undefined;
+        }
+    }
+    clear() {
+        for (const plane of this.planes) {
+            plane.texture?.release();
+            plane.image.release();
+        }
+        this.planes = [];
+        this.isInstalled = false;
+    }
+    /** Planes that contribute to a viewport rectangle, back to front, with their clipped rectangle. */
+    under(rect, excluded = [], menu = false) {
+        return this.planes.flatMap(plane => {
+            const layer = plane.layer;
+            if (layer.menuOverlay && !menu)
+                return [];
+            if (layer.owner && excluded.includes(layer.owner))
+                return [];
+            let clip = intersect(rect, layer.clip);
+            const bottom = layer.keyboard?.clipBottom;
+            if (clip && bottom !== undefined)
+                clip = intersect(clip, [clip[0], clip[1], clip[2], Math.max(0, bottom - clip[1])]);
+            // A banded window is drawn only where it has pixels: beyond its open edges the window
+            // pinned under it shows (and that one's fill beyond its own).
+            if (clip && layer.band) {
+                const top = layer.origin.y - layer.scroll.y;
+                const open = layer.openEdges ?? 0;
+                const from = open & 1 ? top : -Infinity;
+                const to = open & 2 ? top + layer.height : Infinity;
+                const y = Math.max(clip[1], from);
+                const bottom = Math.min(clip[1] + clip[3], to);
+                clip = bottom > y ? [clip[0], y, clip[2], bottom - y] : undefined;
+            }
+            return clip ? [{ plane, clip }] : [];
+        });
+    }
+    /** Everything that decides the composed pixels of `rect`, relative to `rect`: a surface
+     * that moves with its plane (scroll-attached glass) keeps the same key while scrolling. */
+    keyFor(rect, skip, excluded = [], belowEdges = false, menu = false, pose) {
+        // Edges are fixed to the bars: their position relative to the surface decides the pixels.
+        // A surface below the edge layer does not have the edges in its backdrop at all.
+        const edges = (belowEdges ? [] : this.edgesUnder(rect, pose)).map(e => [
+            e.rect[0] - rect[0],
+            e.rect[1] - rect[1],
+            e.rect[2],
+            e.rect[3],
+            e.solid - rect[1],
+            e.mask?.map(([y, alpha]) => [y - rect[1], alpha]),
+            e.sigma,
+            e.tint,
+            e.strength,
+            e.cap ? [e.cap.color, e.cap.solid - rect[1], e.cap.end - rect[1]] : null,
+        ]);
+        return JSON.stringify([
+            edges,
+            this.under(rect, excluded, menu).map(({ plane: { layer }, clip }) => layer.id === skip
+                ? [layer.id, clip[0] - rect[0], clip[1] - rect[1], clip[2], clip[3], layer.fillEdges ?? 0]
+                : [
+                    layer.key,
+                    layer.origin.x - layer.scroll.x - rect[0],
+                    layer.origin.y - layer.scroll.y - rect[1],
+                    clip[0] - rect[0],
+                    clip[1] - rect[1],
+                    clip[2],
+                    clip[3],
+                    layer.fill,
+                    layer.menuOverlay ?? false,
+                    layer.openEdges ?? 0,
+                    layer.fillEdges ?? 0,
+                ]),
+        ]);
+    }
+    /** GPU texture for a plane's capture (shared with any raster using the same key). */
+    texture(plane) {
+        if (!plane.texture) {
+            const image = plane.image.value;
+            plane.texture = this.graph.target('front', image.width, image.height, false, plane.layer.key);
+        }
+        this.graph.upload(plane.image.value, plane.texture.value);
+        return plane.texture.value;
+    }
+    report() {
+        return this.planes.map(({ layer, texture }) => ({
+            id: layer.id,
+            owner: layer.owner,
+            resolution: layer.resolution,
+            key: layer.key,
+            origin: layer.origin,
+            clip: layer.clip,
+            scroll: layer.scroll,
+            size: [layer.width, layer.height],
+            uploaded: !!texture,
+        }));
+    }
+}

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

@@ -0,0 +1,29 @@
+import { type Travel } from '../presentationFrame.js';
+/** Main-thread discovery of the screen-space backdrop planes. No pane names, no
+ * "primary" heuristics: every visible scroll container is a plane, and so is every
+ * visible screen (or presentation's content) that has no scroll container of its own.
+ * A held or travelling presentation is discovered in its resting frame
+ * (presentationFrame.ts). Nested scroll containers
+ * belong to their parent's capture. Planes are ordered back to front by paint order
+ * (document order within the scene, then open dialogs, which paint in the top layer). */
+type Rect = [number, number, number, number];
+/** Ownership survives recaptures; the same dialog must never become its own backdrop. */
+export declare function backdropOwner(element: Element): string | undefined;
+/** Presentation materials sample below their top-layer dialog. Smaller controls may
+ * sample their dialog's content, but never a later dialog above them.
+ * `dialogs` is the scene's top-layer order. Callers that refresh many regions
+ * pass one list; a single lookup reads it itself. */
+export declare function backdropExclusions(element: Element, presentation: boolean, dialogs?: readonly HTMLDialogElement[]): string[];
+/** Planes of the scene (its active tab panel) followed by open modal dialogs. `content` (the
+ * navigation source) is included when nothing discovered covers it and it is not
+ * hidden within the scene (a collapsed sidebar can still be the navigation source). */
+export declare function discoverBackdropHosts(scene: Element, content?: HTMLElement): HTMLElement[];
+/** Viewport rectangle the plane is visible through: its box, every clipping ancestor and the
+ * viewport. Inside a travelling presentation, the box and the clips that travel with it are read
+ * in the presentation's resting frame. */
+export declare function backdropClip(host: HTMLElement, travel?: Travel): Rect | undefined;
+/** Opaque colour a plane's empty area shows: its own and its ancestors' backgrounds
+ * composited front to back, over the page background. Straight RGB, alpha 1. */
+export declare function effectiveBackground(host: HTMLElement, page: readonly [number, number, number]): [number, number, number, number];
+export declare const cssColor: (fill: readonly number[]) => string;
+export {};