npm - @celestia-island/hikari - Versions diffs - 0.55.65 → 0.55.67 - Mend

@celestia-island/hikari 0.55.65 → 0.55.67

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/package.json +1 -1
package/src/components/HkStepFlow.test.tsx +133 -1
package/src/components/HkStepFlow.tsx +29 -0
package/src/index.ts +12 -0
package/src/theme/index.ts +13 -0
package/src/theme/wallpaperShaderAliasGuard.test.ts +112 -0
package/src/theme/wallpaperShaderPresets.test.ts +159 -0
package/src/theme/wallpaperShaderPresets.ts +272 -0
package/src/theme/wallpaperShaderRenderer.test.ts +292 -0
package/src/theme/wallpaperShaderRenderer.ts +362 -0

package/package.json CHANGED Viewed

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

package/src/components/HkStepFlow.test.tsx CHANGED Viewed

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { createApp, defineComponent, h, nextTick, ref } from "vue";
+import { createApp, defineComponent, h, nextTick, onMounted, ref } from "vue";
 import HkStepFlow, { STEPFLOW_SWAP_EVENT } from "./HkStepFlow";
 import type { StepFlowSlotProps } from "./HkStepFlow";
@@ -198,6 +198,138 @@ describe("HkStepFlow", () => {
   });
 });
+describe("HkStepFlow focus handoff on swap", () => {
+  /** Mount with an input in `b`; `a` optionally autofocuses its own field
+   *  the moment the entering body mounts. */
+  function mountFocusRig(options: {
+    initial: string;
+    autoFocusEntry?: boolean;
+    hideTimeline?: boolean;
+    timelineClickable?: boolean;
+  }): { container: HTMLElement; setCurrent: (key: string) => void } {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const current = ref(options.initial);
+    const AutoField = defineComponent({
+      setup() {
+        const el = ref<HTMLInputElement | null>(null);
+        onMounted(() => el.value?.focus());
+        return () => h("input", { ref: el, class: "auto-input" });
+      },
+    });
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(
+            HkStepFlow,
+            {
+              steps: STEPS,
+              modelValue: current.value,
+              hideTimeline: options.hideTimeline ?? true,
+              timelineClickable: options.timelineClickable ?? false,
+              "onUpdate:modelValue": (key: string) => { current.value = key; },
+            },
+            {
+              a: () =>
+                options.autoFocusEntry
+                  ? h(AutoField)
+                  : h("p", { class: "step-body" }, "a-body"),
+              b: () => h("input", { class: "step-input" }),
+              c: () => h("p", { class: "step-body" }, "c-body"),
+              d: () => h("p", { class: "step-body" }, "d-body"),
+            },
+          );
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    return { container, setCurrent: (key) => { current.value = key; } };
+  }
+  it("drops focus out of the leaving body when an animated swap starts", async () => {
+    // Round-22 chest report: the leaving body keeps its DOM node — and so
+    // its focus — through the whole slide, so a focused endpoint field had
+    // Android re-anchoring its autofill suggestion panel on every frame of
+    // the height morph (the panel strobed for the length of the swap). The
+    // motion stub matters: on the instant path the node is recycled at
+    // once and the browser drops focus by itself, which would make this
+    // assertion pass for the wrong reason.
+    stubMotion("0.15s");
+    const t = mountFocusRig({ initial: "b" });
+    const input = t.container.querySelector<HTMLInputElement>(".step-input");
+    expect(input).not.toBeNull();
+    input!.focus();
+    expect(document.activeElement).toBe(input);
+    t.setCurrent("a");
+    await flushSwap();
+    // The slide is still in flight, so the leaving body — and its input —
+    // are still mounted; that is exactly the window that used to strobe.
+    expect(t.container.contains(input)).toBe(true);
+    expect(document.activeElement).not.toBe(input);
+  });
+  it("keeps focus on the timeline step that drove the change", async () => {
+    // The timeline sits inside the flow but is NOT leaving the stage: a
+    // keyboard or pointer user who activated a completed step must keep
+    // their focus. Blurring it drops them to <body> — the next Tab
+    // restarts at the top of the document, and HkModal's Tab trap stops
+    // engaging, so focus can escape the dialog.
+    stubMotion("0.15s");
+    const t = mountFocusRig({
+      initial: "c",
+      hideTimeline: false,
+      timelineClickable: true,
+    });
+    const stepEl = t.container.querySelector<HTMLElement>(
+      ".hk-timeline-step[data-clickable]",
+    );
+    expect(stepEl).not.toBeNull();
+    stepEl!.focus();
+    expect(document.activeElement).toBe(stepEl);
+    t.setCurrent("a");
+    await flushSwap();
+    expect(document.activeElement).toBe(stepEl);
+  });
+  it("lets the entering step's own autofocus win over the blur", async () => {
+    // The blur runs at the top of the swap watcher, before the entering
+    // body mounts, so a step that focuses its own first field on entry
+    // still wins. Moving the call below the mount turns this red.
+    stubMotion("0.15s");
+    const t = mountFocusRig({ initial: "b", autoFocusEntry: true });
+    const leaving = t.container.querySelector<HTMLInputElement>(".step-input");
+    expect(leaving).not.toBeNull();
+    leaving!.focus();
+    expect(document.activeElement).toBe(leaving);
+    t.setCurrent("a");
+    await flushSwap();
+    const entered = t.container.querySelector<HTMLInputElement>(".auto-input");
+    expect(entered).not.toBeNull();
+    expect(document.activeElement).toBe(entered);
+  });
+  it("leaves focus outside the flow alone", async () => {
+    const t = mountFocusRig({ initial: "a" });
+    const outside = document.createElement("input");
+    document.body.appendChild(outside);
+    containers.push(outside);
+    outside.focus();
+    expect(document.activeElement).toBe(outside);
+    t.setCurrent("b");
+    await flushSwap();
+    // Containment, not a blanket blur.
+    expect(document.activeElement).toBe(outside);
+  });
+});
 describe("HkStepFlow split-window swap (motion enabled)", () => {
   it("slides both bodies across one window, then morphs the sheet after", async () => {
     stubMotion();

package/src/components/HkStepFlow.tsx CHANGED Viewed

@@ -287,10 +287,39 @@ export default defineComponent({
     // Sticky-header whitespace strategy (2026-09-14): see HkScrollPin.
     const pinStrategy = ref<"offset" | "bleed">("bleed");
+    /** Drop focus out of the step bodies the moment a swap starts.
+     *
+     *  The leaving body keeps its DOM node — and therefore its focus —
+     *  for the whole slide window, and its input rides the cell while
+     *  the sheet morphs its height. Android re-anchors an open autofill
+     *  suggestion panel on every layout change, so a focused endpoint
+     *  field made the system's autofill sheet strobe at roughly the
+     *  frame rate for the entire animation (round-22 chest report: the
+     *  panel toggled over ~94% of the sheet body for ~250ms while the
+     *  step changed). Blurring before the first animated frame dismisses
+     *  the panel outright; the field the user was typing in is leaving
+     *  the stage anyway, so nothing is taken from them.
+     *
+     *  Containment is the BODIES, not the flow: HkTimeline renders the
+     *  completed steps as `role="button" tabindex="0"` inside this same
+     *  element, and a timeline step that drove the change is not leaving
+     *  the stage. Blurring it would drop a keyboard or pointer user to
+     *  `<body>` — Tab restarts at the top of the document, and HkModal's
+     *  Tab trap stops engaging so focus can escape the dialog. */
+    function dropFlowFocus(): void {
+      if (typeof document === "undefined") return; // SSR guard
+      const active = document.activeElement;
+      if (!(active instanceof HTMLElement)) return;
+      const body = active.closest(".hk-stepflow-body");
+      if (!body || !flowRef.value?.contains(body)) return;
+      active.blur();
+    }
     watch(
       () => props.modelValue,
       async (next, prev) => {
         if (next === prev) return;
+        dropFlowFocus();
         preemptSwap();
         const leaving = bodies.value.find((b) => b.phase === "active");
         if (!leaving) return;

package/src/index.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 `/* … *&#47;` 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 ADDED Viewed

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