@celestia-island/hikari 0.55.64 → 0.55.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.64",
+  "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/composables/useSizeMorph.test.ts

@@ -1268,4 +1268,71 @@ describe("useSizeMorph heightMorph (round 18)", () => {
     expect(h.frame.style.transition).toBe("");
     h.stop();
   });
+
+  it("does not replay a clip conceal for the settle transient after a shrink morph", async () => {
+    // Round-21 mechanism (rig REPORT-R21-shrink): a stepflow shrink's
+    // heightMorph targets the natural height measured the instant the slide
+    // settled — e.g. 503 — which sits a few px off the frame's settled rest
+    // height (483; the chrome-allowance transient, the long-standing +20px
+    // drift). The observer's settle-debounced remeasure then read that
+    // residual as a fresh shrink and replayed a CLIP CONCEAL ~152ms into
+    // the morph — re-promoting the riders and sweeping a moving edge for
+    // 300ms, which is the shrink-time flash the phone kept reporting. The
+    // remeasure must DEFER for the morph's duration, and the morph's
+    // restore must absorb the drift silently (snap the pin to the settled
+    // height, no clip sweep, no rider re-promotion).
+    const rider = document.createElement("div");
+    const h = mountHarness(786, 366, {
+      collectRide: () => [{ el: rider }],
+    });
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.content.appendChild(rider);
+    h.start();
+    expect(h.frame.style.height).toBe("786px");
+    expect(rider.style.willChange).toBe("transform");
+
+    // The shrink morph: natural reads 503 at the settle instant.
+    h.setNatural(503);
+    h.heightMorph(300);
+    expect(h.frame.style.height).toBe("503px");
+    expect(h.frame.style.transition).toContain("height");
+    expect(h.frame.hasAttribute("data-hk-morphing")).toBe(true);
+    expect(rider.style.willChange).toBe("");
+
+    // Mid-morph the transient resolves: the settled rest height is 483.
+    // The observer fires on the content change — it must NOT start a clip
+    // conceal against the running morph.
+    h.setNatural(483);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    // No clip was staged and the rider was NOT re-promoted: the remeasure
+    // deferred instead of replaying a conceal.
+    expect(h.frame.style.clipPath).toBe("");
+    expect(rider.style.willChange).toBe("");
+    // The morph's own height transition is untouched (still running to 503).
+    expect(h.frame.style.transition).toContain("height");
+    expect(h.frame.hasAttribute("data-hk-morphing")).toBe(true);
+
+    // The morph's transition completes: restore absorbs the drift — the pin
+    // snaps to the settled 483 silently, with no clip sweep and no rider
+    // re-promotion beyond the restore of the ORIGINAL promotion.
+    const ev = new Event("transitionend");
+    Object.defineProperty(ev, "propertyName", { value: "height" });
+    h.frame.dispatchEvent(ev);
+    expect(h.frame.hasAttribute("data-hk-morphing")).toBe(false);
+    expect(h.frame.style.clipPath).toBe("");
+    expect(h.frame.style.height).toBe("483px");
+    // The resident promotions are restored to their armed values (the frame
+    // is at rest), not left demoted and not re-swept.
+    expect(h.frame.style.willChange).toBe("clip-path");
+    expect(rider.style.willChange).toBe("transform");
+
+    // Nothing is left pending: a later observer tick finds the pin already
+    // settled and stays quiet (no delayed conceal).
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.clipPath).toBe("");
+    expect(h.frame.style.height).toBe("483px");
+    h.stop();
+  });
 });

package/src/composables/useSizeMorph.ts

@@ -625,12 +625,23 @@ export function useSizeMorph(
 
   function remeasure(interrupt = true): void {
     if (!armed) return;
-    if (!interrupt && revealEl !== null) {
+    if (!interrupt && (revealEl !== null || morphDemoted)) {
       // A background measurement must never tear down a live sweep: doing so
       // republished the sweep's own teardown as its LANDING, so a consumer
       // parking geometry for that fold released it ~2ms in and the sheet
       // undid and replayed the fold (real-engine finding). The change is
       // measured as soon as the sweep lands instead.
+      // The same holds while a heightMorph is in flight (morphDemoted): a
+      // stepflow's morph targets the natural height measured the instant the
+      // slide settled, which can sit a few px off the frame's settled rest
+      // height (the chrome-allowance transient, the long-standing +20px
+      // drift). If the observer's settle-debounced remeasure runs mid-morph
+      // it reads that residual as a fresh shrink and replays a CLIP CONCEAL
+      // — re-promoting the riders and sweeping a moving edge for 300ms,
+      // which is exactly the shrink-time flash the phone kept reporting
+      // (round-21 rig: the conceal fired ~152ms into the morph, clobbering
+      // the running height transition before transitionend). Defer it; the
+      // morph's own restore absorbs the drift silently instead.
       pendingMeasure = true;
       return;
     }
@@ -1011,6 +1022,32 @@ export function useSizeMorph(
       morphSavedRiderWills = [];
       morphSavedFrameWill = "";
       morphDemoted = false;
+      // Absorb the settle transient silently. The morph targeted the natural
+      // height measured the instant the slide settled; that figure can sit a
+      // few px off the frame's settled rest height (the chrome-allowance
+      // transient — the long-standing +20px drift). The observer's
+      // settle-debounced remeasure was deferred for the morph's duration
+      // (see the morphDemoted gate in remeasure); if it ran now against the
+      // stale pin it would read the residual as a fresh shrink and replay a
+      // CLIP CONCEAL (re-promoting riders, sweeping a moving edge) — the
+      // shrink-time flash. Re-measure at rest and snap the pin to the
+      // settled height in one transition-disabled task instead: the few-px
+      // correction lands in the same frame the animation ends, so it is
+      // imperceptible, and the deferred remeasure finds nothing to sweep.
+      if (pendingMeasure) {
+        pendingMeasure = false;
+        const inlineT = f.style.transition;
+        f.style.transition = "none";
+        f.style.height = "";
+        const settled = Math.round(f.offsetHeight);
+        if (settled > 0) {
+          f.style.height = `${settled}px`;
+          pinned = settled;
+        } else if (pinned > 0) {
+          f.style.height = `${pinned}px`;
+        }
+        f.style.transition = inlineT;
+      }
     };
     const onEnd = (ev: TransitionEvent): void => {
       if (ev.target === f && ev.propertyName === "height") {

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();
+  });
+});