@celestia-island/hikari 0.55.65 → 0.55.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.65",
+  "version": "0.55.66",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/index.ts

@@ -261,6 +261,18 @@ export {
   type WallpaperPipelinePreset,
 } from "./theme";
 
+// Wallpaper shader layer: the shared WebGL2 pipeline renderer + the host
+// preset registry. hikari ships the mechanism, never the GLSL — hosts
+// register their generated fragments through registerShaderPresets and
+// hand createWallpaperShaderSurface to HkWallpaperBackdrop's props bag.
+export {
+  registerShaderPresets, getShaderPreset, listShaderPresetIds,
+  SHADER_VERTEX, WallpaperShaderPipeline, createWallpaperShaderSurface,
+  type WallpaperShaderPreset, type WallpaperShaderPresetInput,
+  type WallpaperShaderScaleConfig, type WallpaperShaderScaleInput,
+  type WallpaperShaderOverlayConfig,
+} from "./theme";
+
 // The wallpaper stack's SURFACE component. hikari does NOT put it on the
 // `backdrop` decor floor (that floor has no unregister — a library-owned
 // page-covering layer would be a decision the host cannot take back). The

package/src/theme/index.ts

@@ -64,3 +64,16 @@ export {
   resolveThemeFollowSwitch, setWallpaperPipelineLookup, geo, currentPeriod,
 } from "./useWallpaper";
 export type { WallpaperInitConfig, WallpaperPipelineLookup, WallpaperPipelinePreset } from "./useWallpaper";
+// Wallpaper shader layer. The presets are host assets registered at
+// runtime — hikari ships the renderer and the registry, never any GLSL
+// and never a consumer-side alias import (see wallpaperShaderAliasGuard).
+export {
+  registerShaderPresets, getShaderPreset, listShaderPresetIds,
+} from "./wallpaperShaderPresets";
+export type {
+  WallpaperShaderPreset, WallpaperShaderPresetInput,
+  WallpaperShaderScaleConfig, WallpaperShaderScaleInput, WallpaperShaderOverlayConfig,
+} from "./wallpaperShaderPresets";
+export {
+  SHADER_VERTEX, WallpaperShaderPipeline, createWallpaperShaderSurface,
+} from "./wallpaperShaderRenderer";

package/src/theme/wallpaperShaderAliasGuard.test.ts

@@ -0,0 +1,112 @@
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+// Why this guard exists: hikari ships TS source with ZERO path aliases.
+// A module that imports a consumer-side alias (`@shaders/shaders`,
+// `@wallpapers/wallpapers`, …) compiles fine inside the host that
+// defines the alias and breaks every OTHER consumer's vite/tsconfig —
+// the wallpaper shader adoption (#657's backdrop deliberately took its
+// driver through a `createSurface` prop for exactly this reason). The
+// shader modules added alongside this test are the first hikari modules
+// that would be tempted; the rule is now mechanically enforced for the
+// whole src tree.
+
+const srcDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** A quoted module specifier that resolves through a path alias — the
+ *  form every alias import must take (static, dynamic, require-like). */
+const ALIAS_SPECIFIER_RE = /["']@(?:shaders|wallpapers)\//;
+
+/** Strip full-line `//` comments and `/* … */` blocks so prose and
+ *  commented-out code do not count (registerAnimations.test.ts holds
+ *  the same line for its keyframe scan). */
+function stripComments(src: string): string {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/^[ \t]*\/\/.*$/gm, "");
+}
+
+/** Lines of a source file that reference an alias specifier, in order. */
+function aliasLines(src: string): string[] {
+  return src
+    .split("\n")
+    .filter((line) => ALIAS_SPECIFIER_RE.test(line))
+    .map((line) => line.trim());
+}
+
+/** Recursively collect TS/TSX/Vue sources under the package src tree.
+ *  This test's own file is skipped: its positive-control fixtures are
+ *  RUNTIME strings (not comments), and the guard would flag itself —
+ *  the thing under test is never its own subject (registerAnimations
+ *  holds the same line for the animation dir). */
+function collectSourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      out.push(...collectSourceFiles(p));
+    } else if (/\.(ts|tsx|vue)$/.test(entry.name)) {
+      if (p === path.resolve(fileURLToPath(import.meta.url))) continue;
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+describe("hikari src carries no consumer-side alias imports", () => {
+  // ── Self-proofs (an extractive check with 0 hits must first prove it
+  //    CAN hit — otherwise the pattern is silently broken and the guard
+  //    is a tautology) ────────────────────────────────────────────────
+  it("self-proof: the matcher catches every alias-import shape it exists for", () => {
+    const positives = [
+      'import * as s from "@shaders/shaders";',
+      "import meta from '@shaders/themes.json';",
+      'import("@wallpapers/wallpapers").then((m) => m.pack());',
+      'const r = require("@shaders/shaders");',
+    ];
+    for (const line of positives) {
+      expect(aliasLines(line)).toHaveLength(1);
+    }
+  });
+
+  it("self-proof: comment stripping removes prose mentions without touching live code", () => {
+    const sample = [
+      "/** Chest's `@shaders/shaders` alias is consumer-side. */",
+      "// import x from \"@shaders/shaders\"; // retired experiment",
+      'import { onFrame } from "../runtime/animationBus";',
+      'import x from "@shaders/shaders";',
+    ].join("\n");
+    const hits = aliasLines(stripComments(sample));
+    expect(hits).toEqual(['import x from "@shaders/shaders";']);
+  });
+
+  it("self-proof: the walk covers the tree and includes the shader modules", () => {
+    const files = collectSourceFiles(srcDir);
+    // The walk is not accidentally empty or rooted somewhere else: the
+    // baseline tree is hundreds of files and MUST contain the two
+    // modules this guard was written for (and, per the skip rule above,
+    // must NOT contain this test's own file).
+    expect(files.length).toBeGreaterThan(200);
+    const names = files.map((f) => path.basename(f));
+    for (const required of ["wallpaperShaderPresets.ts", "wallpaperShaderRenderer.ts"]) {
+      expect(names).toContain(required);
+    }
+    expect(names).not.toContain("wallpaperShaderAliasGuard.test.ts");
+  });
+
+  // ── The actual invariant ────────────────────────────────────────────
+  it("no src file references an @shaders/@wallpapers alias specifier", () => {
+    const offenders: string[] = [];
+    for (const file of collectSourceFiles(srcDir)) {
+      const stripped = stripComments(readFileSync(file, "utf-8"));
+      const hits = aliasLines(stripped);
+      if (hits.length > 0) {
+        offenders.push(`${path.relative(srcDir, file)}: ${hits[0]}`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+});

package/src/theme/wallpaperShaderPresets.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  getShaderPreset,
+  listShaderPresetIds,
+  registerShaderPresets,
+} from "./wallpaperShaderPresets";
+
+// NOTE (test-order): the "ships an empty table" block relies on running
+// before any registration below; vitest executes describes in file order.
+// Later blocks use dedicated ids so an ordering change cannot alias them.
+describe("wallpaperShaderPresets builtin default", () => {
+  it("ships an empty table — hikari bundles no GLSL of its own", () => {
+    expect(listShaderPresetIds()).toEqual([]);
+    expect(getShaderPreset("omphalos.dark")).toBeNull();
+    expect(getShaderPreset("anything")).toBeNull();
+  });
+});
+
+describe("registerShaderPresets", () => {
+  it("registers a preset under its record key and fills `id` from it", () => {
+    registerShaderPresets({
+      "reg.full": {
+        fragment: "// frag",
+        texture: "data:image/webp;base64,zz",
+        render: { desktop: 1.5, mobile: "1.0" },
+        overlay: { light: "rgb(255 255 255 / 55%)", dark: "rgb(0 0 0 / 35%)" },
+      },
+    });
+    const preset = getShaderPreset("reg.full");
+    expect(preset).not.toBeNull();
+    expect(preset!.id).toBe("reg.full");
+    expect(preset!.fragment).toBe("// frag");
+    expect(preset!.texture).toBe("data:image/webp;base64,zz");
+    expect(preset!.overlay).toEqual({
+      light: "rgb(255 255 255 / 55%)",
+      dark: "rgb(0 0 0 / 35%)",
+    });
+    expect(preset!.render!.desktop).toBe(1.5);
+    expect(listShaderPresetIds()).toContain("reg.full");
+  });
+
+  it("re-registering an id overrides the previous entry in place", () => {
+    registerShaderPresets({ "reg.over": { fragment: "// first" } });
+    registerShaderPresets({ "reg.over": { fragment: "// second" } });
+    const preset = getShaderPreset("reg.over");
+    expect(preset!.fragment).toBe("// second");
+    // Override, not append: the id appears exactly once.
+    expect(listShaderPresetIds().filter((id) => id === "reg.over")).toHaveLength(1);
+  });
+
+  it("accepts prototype-member ids without shadowing anything", () => {
+    // A plain-object registry would let "toString" collide with the
+    // prototype member; the Map must hold it as an ordinary key.
+    registerShaderPresets({ toString: { fragment: "// literal key" } });
+    expect(getShaderPreset("toString")!.fragment).toBe("// literal key");
+    expect(listShaderPresetIds()).toContain("toString");
+  });
+
+  it("throws loudly on an empty preset id", () => {
+    expect(() => registerShaderPresets({ "": { fragment: "// frag" } })).toThrow(
+      /empty id/,
+    );
+  });
+
+  it("throws loudly on a missing or empty fragment", () => {
+    expect(() =>
+      registerShaderPresets({ "reg.bad": { fragment: "" } }),
+    ).toThrow(/without a fragment shader/);
+    expect(() =>
+      registerShaderPresets({ "reg.bad2": {} as never }),
+    ).toThrow(/without a fragment shader/);
+  });
+
+  it("shallow-copies the overlay so later host mutation cannot desync the registry", () => {
+    const overlay = { light: "rgb(255 0 0 / 10%)", dark: "rgb(0 0 0 / 10%)" };
+    registerShaderPresets({ "reg.copy": { fragment: "// frag", overlay } });
+    overlay.light = "rgb(0 255 0 / 90%)";
+    expect(getShaderPreset("reg.copy")!.overlay!.light).toBe("rgb(255 0 0 / 10%)");
+  });
+});
+
+describe("mobile scale formula evaluation", () => {
+  it("evaluates an arithmetic formula with the live aspect", () => {
+    registerShaderPresets({
+      "scale.formula": {
+        fragment: "// frag",
+        render: { desktop: 1.8, mobile: "Math.min(4.0, 2.88 / aspect)" },
+      },
+    });
+    const render = getShaderPreset("scale.formula")!.render!;
+    expect(render.desktop).toBe(1.8);
+    // Below aspect 0.72 the raw curve (2.88 / aspect) exceeds the 4.0
+    // ceiling and clamps — 2.88 / 0.45 = 6.4 → 4.0.
+    expect(render.mobile(0.45)).toBe(4.0);
+    expect(render.mobile(0.8)).toBeCloseTo(2.88 / 0.8, 10);
+    // Wide aspects fall below the ceiling and follow the raw curve.
+    expect(render.mobile(2.0)).toBeCloseTo(2.88 / 2.0, 10);
+  });
+
+  it("evaluates plain arithmetic without function calls", () => {
+    registerShaderPresets({
+      "scale.arith": {
+        fragment: "// frag",
+        render: { desktop: 1.2, mobile: "1.0 + 0.5 * aspect" },
+      },
+    });
+    const render = getShaderPreset("scale.arith")!.render!;
+    expect(render.mobile(0.5)).toBeCloseTo(1.25, 10);
+    expect(render.mobile(0.72)).toBeCloseTo(1.36, 10);
+  });
+
+  it("falls back to the constant desktop scale when the charset is rejected", () => {
+    registerShaderPresets({
+      "scale.charset": {
+        fragment: "// frag",
+        render: { desktop: 0.9, mobile: "aspect ^ 2" },
+      },
+    });
+    const render = getShaderPreset("scale.charset")!.render!;
+    expect(render.mobile(0.3)).toBe(0.9);
+    expect(render.mobile(2.0)).toBe(0.9);
+  });
+
+  it("falls back to the constant desktop scale when the formula parses to NaN", () => {
+    // Passes the charset gate but the evaluator cannot parse it
+    // (function-call syntax) — the Number.isFinite guard carried from
+    // chest's registry keeps NaN out of the u_scale uniform.
+    registerShaderPresets({
+      "scale.nan": {
+        fragment: "// frag",
+        render: { desktop: 1.4, mobile: "Math.pow(aspect, 2)" },
+      },
+    });
+    const render = getShaderPreset("scale.nan")!.render!;
+    expect(render.mobile(0.5)).toBe(1.4);
+    expect(render.mobile(1.7)).toBe(1.4);
+  });
+
+  it("accepts a host closure and gates its NaN through the same finite guard", () => {
+    registerShaderPresets({
+      "scale.fn": {
+        fragment: "// frag",
+        render: {
+          desktop: 1.8,
+          mobile: (a) => (a > 0 ? 2.88 / a : Number.NaN),
+        },
+      },
+    });
+    const render = getShaderPreset("scale.fn")!.render!;
+    expect(render.mobile(0.5)).toBeCloseTo(5.76, 10);
+    expect(render.mobile(-1)).toBe(1.8);
+  });
+
+  it("leaves no render config when the host declares none", () => {
+    registerShaderPresets({ "scale.none": { fragment: "// frag" } });
+    expect(getShaderPreset("scale.none")!.render).toBeUndefined();
+  });
+});

package/src/theme/wallpaperShaderPresets.ts

@@ -0,0 +1,272 @@
+/**
+ * Wallpaper shader preset registry — the HOST-facing half of the pipeline
+ * wallpaper layer. A host registers its fragment shaders (plus optional
+ * texture / scale / overlay config) under runtime preset ids; the shared
+ * renderer (`wallpaperShaderRenderer.ts`) and the wallpaper logic layer
+ * (via `WallpaperPipelineLookup`) resolve those ids through this registry.
+ *
+ * Why a registry and not an import: hikari ships TS source with zero path
+ * aliases, and shader sources are application assets that live in each
+ * host's generated bundle (chest's `@shaders/shaders`, erp's
+ * `.generated/shaders`) — an alias import here would force every consumer
+ * to configure the same vite/tsconfig mapping. The same design language as
+ * `registerTokenGroup` / `registerThemeDecor`: hikari owns the mechanism,
+ * the host owns the content, and the built-in default is an EMPTY table —
+ * hikari deliberately bundles no GLSL of its own.
+ *
+ * Hard rules this module holds:
+ *
+ *  - **Zero alias imports.** Nothing here may reference `@shaders/*`,
+ *    `@wallpapers/*` or any other consumer-side alias (guarded by
+ *    `wallpaperShaderAliasGuard.test.ts`).
+ *  - **Registration is not a side effect of importing.** A host that never
+ *    calls `registerShaderPresets` gets an untouched (empty) registry and
+ *    every pipeline lookup degrades to `null` — the "no pipeline
+ *    wallpapers" state the backdrop renders as the solid floor.
+ *  - **Invalid input fails loudly** (themeDecor's rule): an empty preset
+ *    id or an empty fragment throws at registration time. The silent
+ *    alternative is a wallpaper that renders nothing with no error
+ *    anywhere.
+ *  - **Re-registration overrides.** Registering the same id again
+ *    replaces the previous entry — the escape hatch for hosts that swap
+ *    preset tables at runtime (a fresh codegen, an A/B experiment).
+ */
+
+/** Normalized render-scale config: flat on landscape, a curve on portrait. */
+export interface WallpaperShaderScaleConfig {
+  /** Uniform value at aspect >= 1.0. */
+  desktop: number;
+  /** Uniform value below aspect 1.0, given the live canvas aspect. */
+  mobile: (aspect: number) => number;
+}
+
+/** Host input for `render`: the mobile scale as a safe-evaluated formula
+ *  string (the generated theme manifests carry `"Math.min(4.0, 2.88 /
+ *  aspect)"`-style expressions) or a ready-made closure. */
+export interface WallpaperShaderScaleInput {
+  desktop: number;
+  mobile: string | ((aspect: number) => number);
+}
+
+/** Scrim colors the host's page CSS mixes over the canvas, per mode. */
+export interface WallpaperShaderOverlayConfig {
+  light: string;
+  dark: string;
+}
+
+/** What a host hands to `registerShaderPresets` — the record KEY is the
+ *  preset id (`omphalos.dark`, `single`, …); no `id` field to drift. */
+export interface WallpaperShaderPresetInput {
+  /** Fragment-shader source (GLSL ES 3.00). Must be non-empty. */
+  fragment: string;
+  /** Optional texture URL (data: or asset import) bound to `u_texture`. */
+  texture?: string;
+  /** Optional scale config (see `WallpaperShaderScaleInput`). */
+  render?: WallpaperShaderScaleInput;
+  /** Optional overlay colors for the host's scrim. */
+  overlay?: WallpaperShaderOverlayConfig;
+}
+
+/** The stored preset `getShaderPreset` resolves to — the input with `id`
+ *  filled from the registration key and `render` normalized to a
+ *  `WallpaperShaderScaleConfig`. */
+export interface WallpaperShaderPreset {
+  id: string;
+  fragment: string;
+  texture?: string;
+  render?: WallpaperShaderScaleConfig;
+  overlay?: WallpaperShaderOverlayConfig;
+}
+
+// The registry itself. A Map (not a plain object) so preset ids cannot
+// collide with Object.prototype members ("constructor", "toString", …) —
+// a generated manifest containing such an id would otherwise shadow a
+// prototype member and misbehave in surprising ways.
+const shaderPresets = new Map<string, WallpaperShaderPreset>();
+
+/**
+ * Safe arithmetic evaluator for mobile-scale formula strings — a
+ * hand-rolled recursive-descent parser, NOT `eval`/`Function`: generated
+ * theme manifests are build inputs, and feeding those to `eval` would
+ * make one poisoned codegen artifact a code-execution vector.
+ *
+ * Supported grammar: `+ - * /`, parentheses, unary minus, number
+ * literals, the registered variable names (the live aspect), and exactly
+ * `Math.min(a, b)` / `Math.max(a, b)` as the only function calls.
+ */
+function safeEvalArithmetic(
+  expr: string,
+  vars: Record<string, number>,
+): number {
+  const s = expr.trim();
+  let pos = 0;
+
+  function skip() {
+    while (pos < s.length && s[pos] === " ") pos++;
+  }
+
+  function parseAtom(): number {
+    skip();
+    if (s[pos] === "(") {
+      pos++;
+      const v = parseExpr();
+      skip();
+      pos++;
+      return v;
+    }
+    for (const name of ["Math.min", "Math.max"] as const) {
+      if (s.slice(pos, pos + name.length) === name) {
+        pos += name.length;
+        skip();
+        pos++;
+        const a = parseExpr();
+        skip();
+        pos++;
+        const b = parseExpr();
+        skip();
+        pos++;
+        return name === "Math.min" ? Math.min(a, b) : Math.max(a, b);
+      }
+    }
+    for (const [name, val] of Object.entries(vars)) {
+      if (
+        s.slice(pos, pos + name.length) === name &&
+        !/[a-zA-Z0-9_]/.test(s[pos + name.length] ?? "")
+      ) {
+        pos += name.length;
+        return val;
+      }
+    }
+    const start = pos;
+    while (pos < s.length && /[\d.]/.test(s[pos])) pos++;
+    return parseFloat(s.slice(start, pos));
+  }
+
+  function parseUnary(): number {
+    skip();
+    if (s[pos] === "-") {
+      pos++;
+      return -parseUnary();
+    }
+    return parseAtom();
+  }
+
+  function parseMul(): number {
+    let left = parseUnary();
+    skip();
+    while (pos < s.length && (s[pos] === "*" || s[pos] === "/")) {
+      const op = s[pos++];
+      const right = parseUnary();
+      left = op === "*" ? left * right : left / right;
+      skip();
+    }
+    return left;
+  }
+
+  function parseExpr(): number {
+    let left = parseMul();
+    skip();
+    while (pos < s.length && (s[pos] === "+" || s[pos] === "-")) {
+      const op = s[pos++];
+      const right = parseMul();
+      left = op === "+" ? left + right : left - right;
+      skip();
+    }
+    return left;
+  }
+
+  return parseExpr();
+}
+
+/** The sanctioned charset for a formula string — reject anything outside
+ *  arithmetic, parentheses, whitespace and identifier letters up front. */
+const FORMULA_CHARSET = /^[\d\s+\-*/().,a-zA-Z]+$/;
+
+/**
+ * Normalize a host's `render` input into the stored scale config.
+ *
+ * Two fallback tiers, both degrading to the constant desktop scale (never
+ * to NaN — a NaN `u_scale` poisons the vertex math and the canvas goes
+ * black):
+ *
+ *  1. a formula string with characters outside the arithmetic charset is
+ *     rejected unread;
+ *  2. a formula that passes the charset gate but still fails to parse
+ *     (`Math.pow(aspect, 2)`) evaluates to NaN and is dropped at call
+ *     time (the `Number.isFinite` guard carried from chest's registry).
+ */
+function normalizeScaleConfig(cfg: WallpaperShaderScaleInput): WallpaperShaderScaleConfig {
+  if (typeof cfg.mobile === "function") {
+    // A host-provided closure needs no evaluation — but its output still
+    // must not leak NaN into the uniform, so it gets the same finite gate.
+    const mobileFn = cfg.mobile;
+    return {
+      desktop: cfg.desktop,
+      mobile: (a) => {
+        const v = mobileFn(a);
+        return Number.isFinite(v) ? v : cfg.desktop;
+      },
+    };
+  }
+  const mobileSrc = cfg.mobile.trim();
+  if (!FORMULA_CHARSET.test(mobileSrc)) {
+    return { desktop: cfg.desktop, mobile: () => cfg.desktop };
+  }
+  return {
+    desktop: cfg.desktop,
+    mobile: (a) => {
+      const v = safeEvalArithmetic(mobileSrc, { aspect: a });
+      return Number.isFinite(v) ? v : cfg.desktop;
+    },
+  };
+}
+
+function assertPresetInput(id: string, input: WallpaperShaderPresetInput): void {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new Error(`[wallpaperShaderPresets] preset registered with an empty id`);
+  }
+  if (!input || typeof input.fragment !== "string" || input.fragment.length === 0) {
+    throw new Error(
+      `[wallpaperShaderPresets] preset "${id}" registered without a fragment shader`,
+    );
+  }
+}
+
+/**
+ * Register (or override) wallpaper shader presets. The record key is the
+ * runtime preset id — dual-mode themes register two entries
+ * (`"omphalos.dark"`, `"omphalos.light"`); the wallpaper logic layer
+ * resolves the mode suffix itself before looking up.
+ *
+ * Must run before the wallpaper state hydrates for the stored ids to
+ * resolve (host boot order: register → `initWallpaper`), same as
+ * `registerWallpaperPack`.
+ */
+export function registerShaderPresets(presets: Record<string, WallpaperShaderPresetInput>): void {
+  for (const [id, input] of Object.entries(presets ?? {})) {
+    assertPresetInput(id, input);
+    shaderPresets.set(id, {
+      id,
+      fragment: input.fragment,
+      ...(input.texture !== undefined && input.texture !== null
+        ? { texture: input.texture }
+        : {}),
+      ...(input.render ? { render: normalizeScaleConfig(input.render) } : {}),
+      // Shallow-copied so later host mutation cannot desync the registry
+      // (themeDecor holds the same line for its props bag).
+      ...(input.overlay ? { overlay: { ...input.overlay } } : {}),
+    });
+  }
+}
+
+/** Resolve a preset id, or `null` when nothing is registered under it —
+ *  the value the backdrop's pipeline branch stands down on. */
+export function getShaderPreset(id: string): WallpaperShaderPreset | null {
+  return shaderPresets.get(id) ?? null;
+}
+
+/** Every registered preset id, in registration order — introspection for
+ *  hosts and tests; mutation goes through `registerShaderPresets`. */
+export function listShaderPresetIds(): string[] {
+  return [...shaderPresets.keys()];
+}

package/src/theme/wallpaperShaderRenderer.test.ts

@@ -0,0 +1,292 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { HkWallpaperSurfaceContext } from "../components/HkWallpaperBackdrop";
+import { registerShaderPresets } from "./wallpaperShaderPresets";
+import {
+  WallpaperShaderPipeline,
+  createWallpaperShaderSurface,
+} from "./wallpaperShaderRenderer";
+
+// WallpaperShaderPipeline.attach() compiles real GLSL through WebGL2;
+// happy-dom has no WebGL at all, so the GPU side is stubbed at its seam —
+// the preset registry — and only the pure selection logic runs against
+// real numbers. (The WebGL2-unavailable branch itself lives in
+// HkWallpaperBackdrop, which owns the context probe now.)
+registerShaderPresets({
+  configured: {
+    fragment: "// frag",
+    render: { desktop: 2.5, mobile: (a) => 10 * a },
+  },
+  bare: { fragment: "// frag" },
+});
+
+/** Private members the render loop reads; reached structurally, no `any`. */
+type PipelineInternals = {
+  canvas: HTMLCanvasElement | null;
+  currentPreset: string;
+  computeScale(): number;
+};
+
+const internals = (p: WallpaperShaderPipeline): PipelineInternals =>
+  p as unknown as PipelineInternals;
+
+/** Bind a preset + canvas size, then read the scale the shader would get. */
+function scaleFor(presetId: string, width: number, height: number): number {
+  const p = new WallpaperShaderPipeline();
+  const i = internals(p);
+  i.currentPreset = presetId;
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  i.canvas = canvas;
+  return i.computeScale();
+}
+
+/** Minimal gl stub for the failure paths: clearColor no-ops, the first
+ *  createShader answers null so createProgram bails before any real GL. */
+const failingGl = () =>
+  ({ clearColor: () => {}, createShader: () => null }) as unknown as WebGL2RenderingContext;
+
+const ctx = (overrides: Partial<HkWallpaperSurfaceContext> = {}): HkWallpaperSurfaceContext => ({
+  canvas: document.createElement("canvas"),
+  gl: failingGl(),
+  presetId: "configured",
+  period: "day",
+  powerPreference: "high-performance",
+  ...overrides,
+});
+
+describe("createWallpaperShaderSurface (HkWallpaperBackdrop driver)", () => {
+  /** A canvas attached to the document, as the component hands it over —
+   *  the driver must never remove it (the component owns the DOM). */
+  const ownedCanvas = (): HTMLCanvasElement => {
+    const canvas = document.createElement("canvas");
+    document.body.append(canvas);
+    return canvas;
+  };
+
+  it("declines (null) on an unknown preset without touching the canvas", () => {
+    const canvas = ownedCanvas();
+    expect(createWallpaperShaderSurface(ctx({ presetId: "unknown", canvas }))).toBeNull();
+    expect(canvas.isConnected).toBe(true);
+  });
+
+  it("declines (null) when the program cannot build, leaving the canvas in place", () => {
+    const canvas = ownedCanvas();
+    expect(createWallpaperShaderSurface(ctx({ canvas }))).toBeNull();
+    expect(canvas.isConnected).toBe(true);
+  });
+
+  it("delegates setPeriod/dispose to one pipeline per surface", async () => {
+    const attachSpy = vi
+      .spyOn(WallpaperShaderPipeline.prototype, "attach")
+      .mockReturnValue(true);
+    const setPeriodSpy = vi.spyOn(WallpaperShaderPipeline.prototype, "setPeriod").mockImplementation(() => {});
+    const destroySpy = vi.spyOn(WallpaperShaderPipeline.prototype, "destroy").mockImplementation(() => {});
+
+    const surface = createWallpaperShaderSurface(ctx());
+    expect(surface).not.toBeNull();
+    expect(attachSpy).toHaveBeenCalledTimes(1);
+
+    surface!.setPeriod?.("night");
+    expect(setPeriodSpy).toHaveBeenCalledWith("night");
+
+    surface!.dispose();
+    expect(destroySpy).toHaveBeenCalledTimes(1);
+
+    attachSpy.mockRestore();
+    setPeriodSpy.mockRestore();
+    destroySpy.mockRestore();
+  });
+});
+
+describe("attach failure modes", () => {
+  it("rolls back to idle on failure", () => {
+    const p = new WallpaperShaderPipeline();
+    expect(p.attach(ctx().canvas, failingGl(), "configured", "night")).toBe(false);
+    expect(p.isActive).toBe(false);
+    expect(p.presetId).toBe("");
+  });
+});
+
+describe("WallpaperShaderPipeline.computeScale (render-config selection)", () => {
+  it("routes portrait aspects through the mobile curve with the real ratio", () => {
+    // 1080×2400 phone → aspect 0.45; the stub mobile curve (10 × aspect)
+    // echoes the exact ratio the pipeline derived from the canvas.
+    expect(scaleFor("configured", 1080, 2400)).toBeCloseTo(4.5, 10);
+    // 999×1000 → aspect 0.999: still strictly below 1.0, still mobile.
+    expect(scaleFor("configured", 999, 1000)).toBeCloseTo(9.99, 10);
+  });
+
+  it("uses the flat desktop scale at aspect 1.0 and above", () => {
+    // Exactly square is desktop (the mobile branch is aspect < 1.0 only).
+    expect(scaleFor("configured", 1000, 1000)).toBe(2.5);
+    // 16:9 and 16:9-at-4K landscape monitors.
+    expect(scaleFor("configured", 1920, 1080)).toBe(2.5);
+    expect(scaleFor("configured", 3840, 2160)).toBe(2.5);
+  });
+
+  it("falls back to 1.0 without a canvas, a render config, or a preset", () => {
+    const p = new WallpaperShaderPipeline();
+    const i = internals(p);
+    i.currentPreset = "configured";
+    i.canvas = null; // never attached / already destroyed
+    expect(i.computeScale()).toBe(1.0);
+    // A preset without a render config keeps the neutral scale.
+    expect(scaleFor("bare", 1080, 2400)).toBe(1.0);
+    // An unknown preset id likewise.
+    expect(scaleFor("unknown", 1920, 1080)).toBe(1.0);
+  });
+});
+
+// ── Resize policy (2026-09-21 phone-IME flicker mitigation) ──────────
+//
+// The drawing buffer sizes against the LAYOUT viewport
+// (documentElement client size) and reallocs only after the viewport
+// settles (RESIZE_SETTLE_MS debounce): keyboard animations step the
+// visual viewport many times without moving the canvas' CSS box
+// (fixed, 100% of the ICB), and each intermediate realloc discarded the
+// GPU texture → black flash. These tests pin both halves.
+type PipelineResizeInternals = {
+  canvas: HTMLCanvasElement | null;
+  gl: WebGL2RenderingContext | null;
+  onResize: () => void;
+};
+
+describe("WallpaperShaderPipeline resize policy", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  const restoreFns: Array<() => void> = [];
+
+  /** Override a getter with a fixed value; restored in afterEach. */
+  function stubGetter(obj: object, prop: string, value: number): void {
+    const desc = Object.getOwnPropertyDescriptor(obj, prop);
+    Object.defineProperty(obj, prop, {
+      configurable: true,
+      get: () => value,
+    });
+    restoreFns.push(() => {
+      if (desc) Object.defineProperty(obj, prop, desc);
+      else delete (obj as Record<string, unknown>)[prop];
+    });
+  }
+
+  function stubViewport(opts: {
+    innerWidth?: number;
+    innerHeight?: number;
+    icbWidth: number;
+    icbHeight: number;
+    dpr?: number;
+  }): void {
+    if (opts.innerWidth !== undefined) stubGetter(window, "innerWidth", opts.innerWidth);
+    if (opts.innerHeight !== undefined) stubGetter(window, "innerHeight", opts.innerHeight);
+    if (opts.dpr !== undefined) stubGetter(window, "devicePixelRatio", opts.dpr);
+    stubGetter(document.documentElement, "clientWidth", opts.icbWidth);
+    stubGetter(document.documentElement, "clientHeight", opts.icbHeight);
+  }
+
+  /** Bind a canvas + truthy gl onto the pipeline (resize gates on both). */
+  function bind(): { p: PipelineResizeInternals; canvas: HTMLCanvasElement } {
+    const p = new WallpaperShaderPipeline() as unknown as PipelineResizeInternals;
+    const canvas = document.createElement("canvas");
+    p.canvas = canvas;
+    p.gl = {} as WebGL2RenderingContext;
+    return { p, canvas };
+  }
+
+  /** Count writes to the canvas backing-store width (realloc proxy). */
+  function countWidthWrites(canvas: HTMLCanvasElement): () => number {
+    const desc = Object.getOwnPropertyDescriptor(HTMLCanvasElement.prototype, "width")!;
+    let n = 0;
+    Object.defineProperty(canvas, "width", {
+      configurable: true,
+      get: () => desc.get!.call(canvas) as number,
+      set: (v: number) => {
+        n += 1;
+        desc.set!.call(canvas, v);
+      },
+    });
+    restoreFns.push(() => delete (canvas as unknown as Record<string, unknown>).width);
+    return () => n;
+  }
+
+  afterEach(() => {
+    vi.useRealTimers();
+    while (restoreFns.length > 0) restoreFns.pop()!();
+  });
+
+  it("sizes the buffer from the layout viewport, not the visual one", () => {
+    // Keyboard open (resizes-visual engines): window.innerHeight
+    // shrinks to 400 while the ICB stays 390×844.
+    stubViewport({ innerWidth: 390, innerHeight: 400, icbWidth: 390, icbHeight: 844, dpr: 2 });
+    const { p, canvas } = bind();
+    // Buffer already at the ICB-derived size (dpr 2, scale 0.5 → 1:1).
+    canvas.width = 390;
+    canvas.height = 844;
+    const writes = countWidthWrites(canvas);
+
+    p.onResize();
+    vi.advanceTimersByTime(1000);
+
+    // The CSS box never moved → no realloc, no GPU-texture discard.
+    expect(writes()).toBe(0);
+    expect(canvas.width).toBe(390);
+    expect(canvas.height).toBe(844);
+  });
+
+  it("reallocs once, after the settle window, on a real geometry change", () => {
+    stubViewport({ icbWidth: 390, icbHeight: 700, dpr: 2 });
+    const { p, canvas } = bind();
+    canvas.width = 390;
+    canvas.height = 844;
+    const writes = countWidthWrites(canvas);
+
+    p.onResize();
+    expect(writes()).toBe(0); // nothing before the settle window
+    vi.advanceTimersByTime(140);
+    expect(writes()).toBe(1);
+    expect(canvas.width).toBe(390);
+    expect(canvas.height).toBe(700);
+  });
+
+  it("coalesces a resize storm into exactly one realloc", () => {
+    // Five stepped viewport sizes (keyboard/drag animation) inside the
+    // settle window must end in ONE final realloc, not five.
+    const { p, canvas } = bind();
+    canvas.width = 390;
+    canvas.height = 844;
+    const writes = countWidthWrites(canvas);
+
+    const heights = [820, 800, 780, 760, 700];
+    for (const h of heights) {
+      stubViewport({ icbWidth: 390, icbHeight: h, dpr: 2 });
+      p.onResize();
+      vi.advanceTimersByTime(50); // below the settle window every time
+    }
+    expect(writes()).toBe(0);
+    vi.advanceTimersByTime(140);
+    expect(writes()).toBe(1);
+    expect(canvas.height).toBe(700);
+  });
+
+  it("cancels a pending realloc when the surface is disposed", () => {
+    stubViewport({ icbWidth: 390, icbHeight: 700, dpr: 2 });
+    const { p, canvas } = bind();
+    canvas.width = 390;
+    canvas.height = 844;
+    const writes = countWidthWrites(canvas);
+
+    p.onResize();
+    expect(vi.getTimerCount()).toBe(1); // the settle timer is armed
+    (p as unknown as WallpaperShaderPipeline).destroy();
+    // destroy must CLEAR the timer, not merely orphan it: a live timer
+    // that no-ops against a nulled canvas still holds the event loop
+    // hostage in embedders and reads as "cancelled" to a canvas-write
+    // probe — the timer count is the load-bearing probe.
+    expect(vi.getTimerCount()).toBe(0);
+    vi.advanceTimersByTime(1000);
+    expect(writes()).toBe(0);
+  });
+});

package/src/theme/wallpaperShaderRenderer.ts

@@ -0,0 +1,362 @@
+import { onFrame, type AnimationHandle } from "../runtime/animationBus";
+import type {
+  HkWallpaperSurface,
+  HkWallpaperSurfaceContext,
+  HkWallpaperSurfaceFactory,
+} from "../components/HkWallpaperBackdrop";
+import type { TimePeriod } from "./useSolarTime";
+import { getShaderPreset } from "./wallpaperShaderPresets";
+
+/**
+ * The shared WebGL2 pipeline renderer for wallpaper backdrops — the
+ * attach()-form driver `HkWallpaperBackdrop` hands a canvas to. Ported
+ * from the per-app copies chest (#1123) and erp (#123) carried after the
+ * component-layer adoption; those two repos kept identical 280-line
+ * renderers, which is exactly the duplication this module retires.
+ *
+ * The shape is the surface contract, not the pre-component singleton:
+ *
+ *  - the COMPONENT owns the canvas and the GL context (it created the
+ *    context with the `powerPreference` it was configured with — that
+ *    attribute was consumed at `getContext` time and is therefore not
+ *    something this driver passes again; it rides
+ *    `HkWallpaperSurfaceContext` for factories that create their own
+ *    context);
+ *  - ONE driver instance per attach — the module-level singleton both
+ *    forks once kept was the two-layouts-share-one-canvas bug the
+ *    component layer was built to kill (either layout's teardown
+ *    destroyed the other's pipeline);
+ *  - `attach()` never writes the DOM and never removes the canvas on
+ *    failure — it returns `false` fully rolled back, and the component
+ *    stands down to the solid floor.
+ *
+ * Uniform contract (what a registered fragment shader may rely on):
+ * `u_time` (seconds since attach), `u_resolution` (drawing-buffer px),
+ * `u_scale` (see `WallpaperShaderScaleConfig`), `u_period` (0 day,
+ * 1 dusk, 2 night) and `u_texture` (sampler2D, unit 0 — bound only when
+ * the preset declares a texture). Attributes: `a_position` (fullscreen
+ * quad, triangle strip).
+ */
+
+/** The fixed vertex stage every preset fragment pairs with. */
+export const SHADER_VERTEX = `#version 300 es
+in vec2 a_position;
+out vec2 v_position;
+void main() {
+  gl_Position = vec4(a_position, 0.0, 1.0);
+  v_position = a_position;
+}`;
+
+/** Viewport-resize settle window (ms) before the drawing buffer is
+ *  reallocated — see WallpaperShaderPipeline.onResize. */
+const RESIZE_SETTLE_MS = 140;
+
+function compileShader(
+  gl: WebGL2RenderingContext,
+  type: number,
+  source: string,
+): WebGLShader | null {
+  const shader = gl.createShader(type);
+  if (!shader) return null;
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    gl.deleteShader(shader);
+    return null;
+  }
+  return shader;
+}
+
+function createProgram(
+  gl: WebGL2RenderingContext,
+  vertSrc: string,
+  fragSrc: string,
+): WebGLProgram | null {
+  const vs = compileShader(gl, gl.VERTEX_SHADER, vertSrc);
+  const fs = compileShader(gl, gl.FRAGMENT_SHADER, fragSrc);
+  if (!vs || !fs) return null;
+  const prog = gl.createProgram();
+  if (!prog) return null;
+  gl.attachShader(prog, vs);
+  gl.attachShader(prog, fs);
+  gl.linkProgram(prog);
+  if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) {
+    gl.deleteProgram(prog);
+    return null;
+  }
+  return prog;
+}
+
+/**
+ * One pipeline lifetime: one canvas attach, one program, one frame loop.
+ * Hosts normally reach this through {@link createWallpaperShaderSurface};
+ * the class is exported for hosts that need to drive the lifecycle
+ * themselves (embedding the canvas outside the backdrop component).
+ */
+export class WallpaperShaderPipeline {
+  private gl: WebGL2RenderingContext | null = null;
+  private program: WebGLProgram | null = null;
+  private vao: WebGLVertexArrayObject | null = null;
+  private startTime: number = 0;
+  private uTime: WebGLUniformLocation | null = null;
+  private uResolution: WebGLUniformLocation | null = null;
+  private uScale: WebGLUniformLocation | null = null;
+  private uPeriod: WebGLUniformLocation | null = null;
+  private uTexture: WebGLUniformLocation | null = null;
+  private canvas: HTMLCanvasElement | null = null;
+  private currentPreset: string = "";
+  private currentPeriod: TimePeriod = "day";
+  private handle: AnimationHandle | null = null;
+  private resizeTimer: ReturnType<typeof setTimeout> | null = null;
+  private texture: WebGLTexture | null = null;
+  private pendingTexImg: HTMLImageElement | null = null;
+
+  /**
+   * Attach to a component-owned canvas + live WebGL2 context (the
+   * HkWallpaperBackdrop surface contract: the component owns the CSS box
+   * and the context, the driver owns the drawing buffer and the pixels).
+   * No DOM writes, no canvas removal on failure — the caller's canvas
+   * stays exactly where it was. Returns false (fully rolled back) when
+   * the preset is unknown or the program cannot build.
+   */
+  attach(
+    canvas: HTMLCanvasElement,
+    gl: WebGL2RenderingContext,
+    presetId: string,
+    period: TimePeriod,
+  ): boolean {
+    this.destroy();
+
+    const preset = getShaderPreset(presetId);
+    if (!preset) return false;
+
+    this.currentPreset = presetId;
+    this.currentPeriod = period;
+
+    this.canvas = canvas;
+    this.gl = gl;
+    gl.clearColor(0, 0, 0, 0);
+
+    const prog = createProgram(gl, SHADER_VERTEX, preset.fragment);
+    if (!prog) {
+      this.gl = null;
+      this.canvas = null;
+      this.currentPreset = "";
+      return false;
+    }
+    this.program = prog;
+
+    gl.useProgram(prog);
+
+    this.uTime = gl.getUniformLocation(prog, "u_time");
+    this.uResolution = gl.getUniformLocation(prog, "u_resolution");
+    this.uScale = gl.getUniformLocation(prog, "u_scale");
+    this.uPeriod = gl.getUniformLocation(prog, "u_period");
+    this.uTexture = gl.getUniformLocation(prog, "u_texture");
+
+    if (preset.texture) {
+      this.loadTexture(preset.texture);
+    }
+
+    const vao = gl.createVertexArray();
+    this.vao = vao;
+    gl.bindVertexArray(vao);
+
+    const buf = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+    gl.bufferData(
+      gl.ARRAY_BUFFER,
+      new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]),
+      gl.STATIC_DRAW,
+    );
+
+    const aPos = gl.getAttribLocation(prog, "a_position");
+    gl.enableVertexAttribArray(aPos);
+    gl.vertexAttribPointer(aPos, 2, gl.FLOAT, false, 0, 0);
+
+    this.startTime = performance.now();
+    this.resize();
+
+    this.handle = onFrame((ctx) => this.render(ctx), "normal");
+
+    window.addEventListener("resize", this.onResize);
+    return true;
+  }
+
+  setPeriod(period: TimePeriod) {
+    this.currentPeriod = period;
+  }
+
+  private render(ctx: { now: number }) {
+    const gl = this.gl;
+    if (!gl || !this.canvas) return;
+
+    const elapsed = (ctx.now - this.startTime) / 1000;
+    gl.viewport(0, 0, this.canvas.width, this.canvas.height);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    gl.uniform1f(this.uTime, elapsed);
+    gl.uniform2f(this.uResolution, this.canvas.width, this.canvas.height);
+    if (this.uScale) gl.uniform1f(this.uScale, this.computeScale());
+
+    let periodVal = 2.0;
+    if (this.currentPeriod === "day") periodVal = 0.0;
+    else if (this.currentPeriod === "dusk") periodVal = 1.0;
+    gl.uniform1f(this.uPeriod, periodVal);
+
+    if (this.texture && this.uTexture) {
+      gl.activeTexture(gl.TEXTURE0);
+      gl.bindTexture(gl.TEXTURE_2D, this.texture);
+      gl.uniform1i(this.uTexture, 0);
+    }
+
+    gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+  }
+
+  private computeScale(): number {
+    if (!this.canvas) return 1.0;
+    const preset = getShaderPreset(this.currentPreset);
+    const cfg = preset?.render;
+    if (!cfg) return 1.0;
+    const aspect = this.canvas.width / this.canvas.height;
+    if (aspect < 1.0) {
+      return cfg.mobile(aspect);
+    }
+    return cfg.desktop;
+  }
+
+  private loadTexture(url: string) {
+    const gl = this.gl;
+    if (!gl) return;
+
+    const tex = gl.createTexture();
+    if (!tex) return;
+    this.texture = tex;
+    gl.bindTexture(gl.TEXTURE_2D, tex);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array([0, 0, 0, 0]));
+
+    const img = new Image();
+    this.pendingTexImg = img;
+    img.onload = () => {
+      if (!this.gl || !this.texture || this.pendingTexImg !== img) return;
+      this.gl.bindTexture(gl.TEXTURE_2D, this.texture);
+      this.gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
+      this.gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+      this.gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+      this.gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+      this.gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+      this.pendingTexImg = null;
+    };
+    img.src = url;
+  }
+
+  private onResize = () => {
+    // Settle-debounce: viewport-resize storms (phone keyboard animations
+    // step the viewport every frame for ~250ms; window drags/rotations
+    // step it too) must not reallocate the drawing buffer per step —
+    // each realloc discards the GPU texture and the gap before the next
+    // submitted frame renders as a black flash. While a debounce is
+    // pending the canvas keeps drawing into the old buffer; CSS
+    // (width/height 100%) stretches it, which background art survives
+    // fine for the ~140ms settle window.
+    if (this.resizeTimer != null) clearTimeout(this.resizeTimer);
+    this.resizeTimer = setTimeout(() => {
+      this.resizeTimer = null;
+      this.resize();
+    }, RESIZE_SETTLE_MS);
+  };
+
+  private resize() {
+    if (!this.canvas || !this.gl) return;
+    // Size against the LAYOUT viewport (documentElement client size),
+    // not window.innerWidth/innerHeight (visual viewport). Under the
+    // default interactive-widget=resizes-visual the soft keyboard
+    // shrinks only the visual viewport — this canvas' CSS box (fixed,
+    // 100% of the ICB) never moves, so reallocating the buffer on an
+    // innerHeight change produced zero visual change while discarding
+    // the GPU texture mid-animation (the 2026-09-21 phone IME black
+    // flicker report). The layout viewport only moves for real
+    // geometry changes (URL-bar collapse, rotation, window resize),
+    // which is exactly when the buffer SHOULD follow.
+    const vw = document.documentElement.clientWidth || window.innerWidth;
+    const vh = document.documentElement.clientHeight || window.innerHeight;
+    const dpr = Math.min(window.devicePixelRatio || 1, 2);
+    const scale = 0.5;
+    const w = Math.floor(vw * dpr * scale);
+    const h = Math.floor(vh * dpr * scale);
+    if (this.canvas.width !== w || this.canvas.height !== h) {
+      this.canvas.width = w;
+      this.canvas.height = h;
+      this.canvas.style.width = "100%";
+      this.canvas.style.height = "100%";
+    }
+  }
+
+  destroy() {
+    if (this.handle) {
+      this.handle.disconnect();
+      this.handle = null;
+    }
+    if (this.resizeTimer != null) {
+      clearTimeout(this.resizeTimer);
+      this.resizeTimer = null;
+    }
+    window.removeEventListener("resize", this.onResize);
+    if (this.gl) {
+      if (this.vao) this.gl.deleteVertexArray(this.vao);
+      if (this.program) this.gl.deleteProgram(this.program);
+      if (this.texture) this.gl.deleteTexture(this.texture);
+      this.gl = null;
+    }
+    this.program = null;
+    this.vao = null;
+    this.uTime = null;
+    this.uResolution = null;
+    this.uScale = null;
+    this.uPeriod = null;
+    this.uTexture = null;
+    this.texture = null;
+    this.pendingTexImg = null;
+    // The canvas is component-owned (HkWallpaperBackdrop removes it with
+    // its own tree); the driver only forgets it.
+    this.canvas = null;
+    this.currentPreset = "";
+  }
+
+  get isActive(): boolean {
+    return this.handle !== null;
+  }
+
+  get presetId(): string {
+    return this.currentPreset;
+  }
+}
+
+/**
+ * The ready-made pipeline driver for `HkWallpaperBackdrop`: one
+ * {@link WallpaperShaderPipeline} per surface attach, resolved against
+ * the shared preset registry ({@link getShaderPreset}). Hand it to the
+ * component through the backdrop decor registration's props bag:
+ *
+ * ```ts
+ * registerThemeDecor({
+ *   themeId: "*", slot: "backdrop", component: HkWallpaperBackdrop,
+ *   props: { createSurface: createWallpaperShaderSurface },
+ * });
+ * ```
+ *
+ * Returning `null` on an unknown preset or a failed program build is the
+ * contract's "decline" — the component then stands down to the solid
+ * floor instead of leaving an invisible canvas on screen.
+ */
+export const createWallpaperShaderSurface: HkWallpaperSurfaceFactory = (
+  ctx: HkWallpaperSurfaceContext,
+): HkWallpaperSurface | null => {
+  const pipeline = new WallpaperShaderPipeline();
+  if (!pipeline.attach(ctx.canvas, ctx.gl, ctx.presetId, ctx.period)) {
+    return null;
+  }
+  return {
+    setPeriod: (period) => pipeline.setPeriod(period),
+    dispose: () => pipeline.destroy(),
+  };
+};