@celestia-island/hikari 0.55.51 → 0.55.53

package/package.json

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

package/src/components/HkModal.stepflowswap.test.tsx

@@ -338,21 +338,14 @@ describe("HkModal publishes its own fold for the step flow", () => {
     stubClip();
     stubBox(500, Number.POSITIVE_INFINITY);
 
-    let registered = false;
+    // The rider models the stepflow's ENTERING body: registered
+    // MID-CYCLE (never at arm time), so it stays on the per-swap
+    // promotion path — resident promotion is the chrome's alone.
+    let lateRegistry: ReturnType<typeof useSheetRide> = null;
     const Rider = defineComponent({
       setup() {
-        const registry = useSheetRide();
-        return () =>
-          h("div", {
-            class: "rider-el",
-            ref: (el: unknown) => {
-              const node = el as HTMLElement | null;
-              if (node && registry && !registered) {
-                registered = true;
-                registry.register({ el: node, counter: true });
-              }
-            },
-          }, "rider");
+        lateRegistry = useSheetRide();
+        return () => h("div", { class: "rider-el" }, "rider");
       },
     });
 
@@ -384,7 +377,9 @@ describe("HkModal publishes its own fold for the step flow", () => {
     const header = () => document.querySelector<HTMLElement>(".hk-modal-header")!;
     const bodyBlock = () => document.querySelector<HTMLElement>(".hk-modal-body")!;
     const riderEl = () => document.querySelector<HTMLElement>(".rider-el")!;
-    expect(registered).toBe(true);
+    expect(lateRegistry).not.toBeNull();
+    // Register only AFTER the surface armed — the per-swap timing.
+    lateRegistry!.register({ el: riderEl(), counter: true });
 
     // The sweep needs real frames from here on.
     const frames: FrameRequestCallback[] = [];
@@ -422,13 +417,19 @@ describe("HkModal publishes its own fold for the step flow", () => {
     expect(riderEl().style.transform).toBe("translateY(0px)");
     expect(header().style.transition).toMatch(/^transform 0\.3s /);
 
-    // The landing releases the rides with the frame.
+    // The landing releases the rides with the frame — but the CHROME
+    // keeps its resident promotion (round 15: demoting at the settle
+    // put the phone-GPU raster race back at every landing = black
+    // blocks). Only the per-swap registration (the Rider div, not in
+    // the frame at arm time) releases its layer.
     const ev = new Event("transitionend");
     Object.defineProperty(ev, "propertyName", { value: "clip-path" });
     frame().dispatchEvent(ev);
     expect(header().style.transform).toBe("");
     expect(bodyBlock().style.transform).toBe("");
     expect(riderEl().style.transform).toBe("");
-    expect(header().style.willChange).toBe("");
+    expect(header().style.willChange).toBe("transform");
+    expect(bodyBlock().style.willChange).toBe("transform");
+    expect(riderEl().style.willChange).toBe("");
   });
 });

package/src/components/HkSettingsDialog.scss

@@ -0,0 +1,169 @@
+// HkSettingsDialog — the sectioned settings shell (rail + pane) and its
+// content vocabulary (group / sub / hint). Grammar extracted from the
+// wowsp settings window (the pattern this component upstreams): values
+// are the L2 scale tokens wowsp already used, so existing surfaces
+// migrate without repainting.
+//
+// Scroll ownership: inside the dialog (host class `hk-settings-host`)
+// the shell gets a STABLE height sized under the modal body scroller's
+// inner padding, so HkModal's floating overlay scrollbar stays idle and
+// the pane's own edge bar is the only scrollbar. The negative-margin
+// trick puts that edge — and its scrollbar — flush with the modal
+// window's right edge; the padding re-applies the content inset between
+// the scrollbar and the cards. A page-embedded body (no host class)
+// skips both: plain scroll container, host-managed layout.
+
+.hk-settings {
+  display: flex;
+  align-items: stretch;
+  gap: var(--space-20);
+
+  /* ── section rail (mirrors the main sidebar nav look) ── */
+  &__rail {
+    flex: none;
+    width: 10.5rem;
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2);
+    padding: var(--space-4) var(--space-12) var(--space-4) 0;
+    border-right: 1px solid rgb(var(--color-border) / 15%);
+    overflow-y: auto;
+  }
+
+  &__rail-item {
+    display: flex;
+    align-items: center;
+    gap: var(--space-10);
+    padding: var(--space-8) var(--space-12);
+    border: 0;
+    border-radius: var(--radius-sm);
+    background: transparent;
+    text-align: left;
+    color: rgb(var(--color-muted));
+    font-size: var(--text-sm);
+    font-family: inherit;
+    cursor: pointer;
+    transition:
+      color var(--duration-short) var(--ease-standard),
+      background var(--duration-short) var(--ease-standard);
+
+    &:hover:not(:disabled) {
+      color: rgb(var(--color-text));
+      background: rgb(var(--color-primary) / 8%);
+    }
+
+    &:focus-visible {
+      outline: 2px solid rgb(var(--color-primary));
+      outline-offset: 1px;
+    }
+
+    &:disabled {
+      opacity: 0.45;
+      cursor: not-allowed;
+    }
+
+    &.is-active {
+      color: rgb(var(--color-primary));
+      background: rgb(var(--color-primary) / 12%);
+      font-weight: 500;
+    }
+  }
+
+  &__rail-icon {
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--space-20);
+    height: var(--space-20);
+  }
+
+  &__rail-label {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* ── content pane: one section at a time, this is the scroller ── */
+  &__pane {
+    flex: 1;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-16);
+    overflow-y: auto;
+  }
+}
+
+/* ── Dialog host: stable frame + flush scrollbar edge ────────────────── */
+
+/* Give the body inner a definite height so the shell's fit is computed
+   against the real scroll area (wowsp's host rule, verbatim). */
+.hk-settings-host .hk-modal-body-inner {
+  height: 100%;
+}
+
+.hk-settings-host .hk-settings {
+  height: var(--hk-settings-height, calc(70vh - 6.5rem));
+}
+
+/* Cancel the modal body's fixed right padding so the pane's scrollbar
+   sits flush at the window edge; re-apply the inset between the bar and
+   the cards. HkModal retunes the body padding to 1rem under 768px —
+   follow it or the pane overshoots the edge. */
+.hk-settings-host .hk-settings__pane {
+  margin-right: calc(-1 * var(--hk-modal-padding-body, 1.5rem));
+  padding-right: var(--space-28);
+
+  @media (max-width: 767px) {
+    margin-right: -1rem;
+    padding-right: var(--space-20);
+  }
+}
+
+/* ── Content vocabulary ───────────────────────────────────────────────── */
+
+/* One titled card per settings area. Slightly translucent so the cards
+   sit quietly on image wallpapers. */
+.hk-settings-group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-12);
+  padding: var(--space-16) var(--space-20);
+  background: rgb(var(--color-surface) / 55%);
+  border: 1px solid rgb(var(--color-border) / 15%);
+  border-radius: var(--radius-md);
+}
+
+.hk-settings-group-title {
+  margin: 0;
+  font-size: var(--text-sm);
+  font-weight: 600;
+  color: rgb(var(--color-text));
+}
+
+/* Titled sub-block inside a group. */
+.hk-settings-sub {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8);
+  margin-top: var(--space-4);
+}
+
+.hk-settings-sub-title {
+  margin: 0;
+  font-size: var(--text-xs);
+  font-weight: 600;
+  color: rgb(var(--color-muted));
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+/* The small muted explanation line under a control. */
+.hk-settings-hint {
+  margin: 0;
+  font-size: var(--text-xs);
+  line-height: 1.5;
+  color: rgb(var(--color-muted));
+}

package/src/components/HkSettingsDialog.test.tsx

@@ -0,0 +1,249 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+import { Languages, Globe } from "lucide-vue-next";
+import {
+  HkSettingsBody as HSettingsBody,
+  HkSettingsDialog as HSettingsDialog,
+  HkSettingsGroup as HSettingsGroup,
+  HkSettingsHint as HSettingsHint,
+  HkSettingsSub as HSettingsSub,
+} from "./HkSettingsDialog";
+
+function mount(component: ReturnType<typeof defineComponent>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(component);
+  app.mount(container);
+  return { container, unmount: () => { app.unmount(); container.remove(); } };
+}
+
+const SECTIONS = [
+  { key: "language", label: "Language", icon: Languages },
+  { key: "network", label: "Network", icon: Globe },
+  { key: "locked", label: "Locked", disabled: true },
+];
+
+const Host = defineComponent({
+  setup() {
+    const section = ref("language");
+    return () => (
+      <HSettingsBody sections={SECTIONS} v-model:section={section.value}
+        onUpdate:section={(v: string) => (section.value = v)}>
+        {{
+          language: () => <div data-test="pane-language">lang pane</div>,
+          network: () => <div data-test="pane-network">net pane</div>,
+          locked: () => <div data-test="pane-locked">locked pane</div>,
+        }}
+      </HSettingsBody>
+    );
+  },
+});
+
+describe("HSettingsBody", () => {
+  it("renders every rail entry and the first section's pane", () => {
+    const { container, unmount } = mount(Host);
+    const items = container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item");
+    expect(items).toHaveLength(3);
+    expect(items[0].textContent).toContain("Language");
+    expect(items[0].querySelector(".hk-settings__rail-icon svg")).toBeTruthy();
+    // First section active by default (internal state, unbound prop).
+    expect(items[0].classList.contains("is-active")).toBe(true);
+    expect(container.querySelector('[data-test="pane-language"]')).toBeTruthy();
+    expect(container.querySelector('[data-test="pane-network"]')).toBeNull();
+    unmount();
+  });
+
+  it("switches the pane on rail click and reports aria-current", async () => {
+    const { container, unmount } = mount(Host);
+    const items = container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item");
+    items[1].click();
+    await nextTick();
+    expect(container.querySelector('[data-test="pane-network"]')).toBeTruthy();
+    expect(items[1].getAttribute("aria-current")).toBe("true");
+    expect(items[0].getAttribute("aria-current")).toBeNull();
+    unmount();
+  });
+
+  it("never activates a disabled entry", async () => {
+    const { container, unmount } = mount(Host);
+    const items = container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item");
+    expect(items[2].disabled).toBe(true);
+    items[2].click();
+    await nextTick();
+    // Still on the first section.
+    expect(container.querySelector('[data-test="pane-language"]')).toBeTruthy();
+    expect(items[2].classList.contains("is-active")).toBe(false);
+    unmount();
+  });
+
+  it("restarts the pane scroll on section switch", async () => {
+    const scrolled = ref(false);
+    const Probe = defineComponent({
+      setup() {
+        const section = ref("language");
+        return () => (
+          <HSettingsBody
+            sections={SECTIONS.slice(0, 2)}
+            section={section.value}
+            onUpdate:section={(v: string) => (section.value = v)}
+          >
+            {{
+              language: () => <div style="height: 2000px">lang</div>,
+              network: () => <div style="height: 2000px">net</div>,
+            }}
+          </HSettingsBody>
+        );
+      },
+    });
+    const { container, unmount } = mount(Probe);
+    const pane = container.querySelector<HTMLElement>(".hk-settings__pane")!;
+    pane.scrollTop = 500;
+    const items = container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item");
+    items[1].click();
+    await nextTick();
+    await nextTick();
+    scrolled.value = pane.scrollTop === 0;
+    expect(scrolled.value).toBe(true);
+    unmount();
+  });
+
+  it("honors an externally driven section change (deep-link landing)", async () => {
+    const section = ref("language");
+    const Deep = defineComponent({
+      setup() {
+        return () => (
+          <HSettingsBody sections={SECTIONS.slice(0, 2)} section={section.value}>
+            {{
+              language: () => <div data-test="pane-language" />,
+              network: () => <div data-test="pane-network" />,
+            }}
+          </HSettingsBody>
+        );
+      },
+    });
+    const { container, unmount } = mount(Deep);
+    section.value = "network";
+    await nextTick();
+    expect(container.querySelector('[data-test="pane-network"]')).toBeTruthy();
+    unmount();
+  });
+});
+
+describe("HSettingsDialog", () => {
+  it("hosts the shell inside an open HModal and lands on the bound section", async () => {
+    const section = ref("network");
+    const Dialog = defineComponent({
+      setup() {
+        return () => (
+          <HSettingsDialog
+            modelValue
+            title="Settings"
+            sections={SECTIONS.slice(0, 2)}
+            section={section.value}
+            onUpdate:section={(v: string) => (section.value = v)}
+          >
+            {{
+              language: () => <div data-test="pane-language" />,
+              network: () => <div data-test="pane-network" />,
+            }}
+          </HSettingsDialog>
+        );
+      },
+    });
+    const { unmount } = mount(Dialog);
+    await nextTick();
+    await new Promise((r) => setTimeout(r, 0));
+    // HkModal teleports to document.body — the shell lives there, not in
+    // the mount container.
+    const host = document.body.querySelector(".hk-settings-host");
+    expect(host).toBeTruthy();
+    expect(host!.querySelector(".hk-settings__rail")).toBeTruthy();
+    // The bound section won over the default-first.
+    expect(host!.querySelector('[data-test="pane-network"]')).toBeTruthy();
+    unmount();
+  });
+});
+
+describe("settings content vocabulary", () => {
+  it("renders group / sub / hint with their titles", () => {
+    const { container, unmount } = mount(
+      defineComponent({
+        setup() {
+          return () => (
+            <HSettingsGroup title="Network">
+              <HSettingsSub title="Proxy">
+                <HSettingsHint>Applies to every request.</HSettingsHint>
+              </HSettingsSub>
+            </HSettingsGroup>
+          );
+        },
+      }),
+    );
+    expect(container.querySelector(".hk-settings-group-title")!.textContent).toBe("Network");
+    expect(container.querySelector(".hk-settings-sub-title")!.textContent).toBe("Proxy");
+    expect(container.querySelector(".hk-settings-hint")!.textContent)
+      .toContain("Applies to every request");
+    unmount();
+  });
+
+  it("renders a group without a title (untitled card)", () => {
+    const { container, unmount } = mount(
+      defineComponent({
+        setup() {
+          return () => h(HSettingsGroup, null, { default: () => "body" });
+        },
+      }),
+    );
+    expect(container.querySelector(".hk-settings-group-title")).toBeNull();
+    unmount();
+  });
+});
+
+describe("settings dialog SCSS host contract (source-level)", () => {
+  // The stable-frame contract is three rules in the SCSS that happy-dom's
+  // cascade-free environment cannot exercise behaviorally — pin them at
+  // the source so a silent deletion turns this red (the R1 mutation-d
+  // gap). Known-positive control: the base rail rule every variant
+  // depends on.
+  // vitest serves modules through its own scheme, so import.meta.url is
+  // not a file URL here; the suite's cwd is packages/vue.
+  const scss = readFileSync("src/components/HkSettingsDialog.scss", "utf8");
+
+  it("self-check: the extractor sees a rule that exists", () => {
+    // The shell rules are BEM-nested in the source (&__rail-item inside
+    // .hk-settings) — the positive control matches the nested form.
+    expect(scss).toContain("&__rail-item {");
+  });
+
+  it("pins the stable-frame host rules (idle modal scrollbar, flush edge)", () => {
+    expect(scss).toContain(".hk-settings-host .hk-modal-body-inner {");
+    expect(scss).toContain("height: var(--hk-settings-height, calc(70vh - 6.5rem));");
+    expect(scss).toContain("margin-right: calc(-1 * var(--hk-modal-padding-body, 1.5rem));");
+  });
+
+  it("never activates a disabled section through a deep-linked prop", async () => {
+    const Deep = defineComponent({
+      setup() {
+        return () => (
+          <HSettingsBody sections={SECTIONS} section="locked">
+            {{
+              language: () => <div data-test="pane-language" />,
+              network: () => <div data-test="pane-network" />,
+              locked: () => <div data-test="pane-locked" />,
+            }}
+          </HSettingsBody>
+        );
+      },
+    });
+    const { container, unmount } = mount(Deep);
+    await nextTick();
+    // The disabled key did not win: first usable section shows, the
+    // locked pane never renders, its rail entry stays grey.
+    expect(container.querySelector('[data-test="pane-language"]')).toBeTruthy();
+    expect(container.querySelector('[data-test="pane-locked"]')).toBeNull();
+    const items = container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item");
+    expect(items[2].classList.contains("is-active")).toBe(false);
+    unmount();
+  });
+});

package/src/components/HkSettingsDialog.tsx

@@ -0,0 +1,237 @@
+import {
+  defineComponent,
+  h,
+  nextTick,
+  ref,
+  watch,
+  type Component,
+  type PropType,
+} from "vue";
+
+import HModal from "./HkModal";
+import "./HkSettingsDialog.scss";
+
+/** One rail entry of the settings dialog. */
+export interface HkSettingsSection {
+  /** Identity of the section — also the name of the slot that renders its
+   *  content pane (`{ [key]: () => … }`). */
+  key: string;
+  /** Rail label. */
+  label: string;
+  /** Leading rail icon (a lucide-style component; rendered at 16px). */
+  icon?: Component;
+  /** A disabled entry renders but cannot be activated. */
+  disabled?: boolean;
+}
+
+/**
+ * HkSettingsBody — the sectioned settings shell: a left rail of icon+label
+ * nav entries and a right scrollable pane rendering the active section's
+ * slot. Extracted from the pattern wowsp, the flasher and the admin
+ * consoles each hand-rolled (the "classic settings window" anatomy).
+ *
+ * Standalone by design: the BODY can be embedded in a page (the phone
+ * surface pattern — wowsp renders it inside its own /settings route) or
+ * inside {@link HSettingsDialog}, which wraps it in an HModal window.
+ * Section identity is a `v-model:section` so openers can land on a
+ * specific section; leaving it unbound keeps the state internal
+ * (first section active).
+ *
+ * Scroll ownership: the pane is the only scroller — switching sections
+ * restarts it from the top (arriving on a half-scrolled pane reads as a
+ * broken page). Inside the dialog the modal body's own scroller is made
+ * mathematically idle by the host height rule (see the SCSS); on a page
+ * the host manages its own layout.
+ */
+export const HkSettingsBody = defineComponent({
+  name: "HkSettingsBody",
+  props: {
+    /** Rail entries, in rail order. */
+    sections: { type: Array as PropType<HkSettingsSection[]>, required: true },
+    /** Active section key (v-model:section). Unbound = internal state. */
+    section: { type: String, default: undefined },
+    /** Accessible name for the rail navigation. */
+    navLabel: { type: String, default: undefined },
+  },
+  emits: {
+    "update:section": (key: string) => typeof key === "string",
+  },
+  setup(props, { emit, slots }) {
+    const internal = ref(props.sections[0]?.key ?? "");
+    // Controlled while a section prop is bound: external changes flow in,
+    // clicks flow out. Unbound: the internal ref alone decides. Immediate
+    // so an opener that mounts ALREADY on a deep-linked section
+    // (section="network" from the first render) wins over the first-entry
+    // default — a non-immediate watch would never fire for it.
+    watch(
+      () => props.section,
+      (key) => {
+        if (key == null) return;
+        // A disabled (or unknown) key never activates — a host that
+        // deep-links to one keeps the first usable section instead
+        // (R1 gap: the locked pane used to render with its rail entry
+        // greyed out, contradicting "renders but cannot be activated").
+        if (props.sections.some((sec) => sec.key === key && !sec.disabled)) {
+          internal.value = key;
+        }
+      },
+      { immediate: true },
+    );
+    const active = () =>
+      props.sections.some((s) => s.key === internal.value)
+        ? internal.value
+        : (props.sections[0]?.key ?? "");
+
+    const paneRef = ref<HTMLElement | null>(null);
+    // Section switches restart the pane from the top.
+    watch(active, () => {
+      void nextTick(() => {
+        if (paneRef.value) paneRef.value.scrollTop = 0;
+      });
+    });
+
+    function pick(key: string) {
+      const entry = props.sections.find((s) => s.key === key);
+      if (!entry || entry.disabled) return;
+      internal.value = key;
+      emit("update:section", key);
+    }
+
+    return () => (
+      <div class="hk-settings">
+        <nav class="hk-settings__rail" aria-label={props.navLabel}>
+          {props.sections.map((s) => {
+            const Icon = s.icon;
+            const on = active() === s.key && !s.disabled;
+            return (
+              <button
+                key={s.key}
+                type="button"
+                class={["hk-settings__rail-item", on ? "is-active" : ""]}
+                aria-current={on ? "true" : undefined}
+                aria-disabled={s.disabled || undefined}
+                disabled={s.disabled}
+                onClick={() => pick(s.key)}
+              >
+                {typeof Icon === "function" ? (
+                  <span class="hk-settings__rail-icon" aria-hidden="true">
+                    <Icon size={16} />
+                  </span>
+                ) : null}
+                <span class="hk-settings__rail-label">{s.label}</span>
+              </button>
+            );
+          })}
+        </nav>
+        <div class="hk-settings__pane" ref={paneRef}>
+          {slots[active()]?.()}
+        </div>
+      </div>
+    );
+  },
+});
+
+/**
+ * HkSettingsDialog — the settings window: an HModal carrying the
+ * {@link HSettingsBody} shell with a stable frame height, so the modal
+ * body's floating scrollbar stays idle and the pane's edge bar is the
+ * only scrollbar (the wowsp-proven contract). Width defaults to the
+ * settings-standard 58rem; `height` styles the shell (the 70vh default
+ * fits a modal with title and paddings).
+ *
+ * Like every HkModal composite it bottom-sheets under 768px; hosts that
+ * want a phone page instead render HSettingsBody in their own route and
+ * simply never mount this dialog there.
+ */
+export const HkSettingsDialog = defineComponent({
+  name: "HkSettingsDialog",
+  props: {
+    modelValue: { type: Boolean, default: false },
+    title: { type: String, default: "" },
+    /** Modal max-width (CSS value or HkModal preset). */
+    width: { type: String, default: "58rem" },
+    /** Rail entries — passed through to the body. */
+    sections: { type: Array as PropType<HkSettingsSection[]>, required: true },
+    /** Active section key (v-model:section). */
+    section: { type: String, default: undefined },
+    /** Accessible name for the rail navigation. */
+    navLabel: { type: String, default: undefined },
+    /** Shell height — the stable frame the pane scrolls inside. */
+    height: { type: String, default: "calc(70vh - 6.5rem)" },
+  },
+  emits: {
+    "update:modelValue": (v: boolean) => typeof v === "boolean",
+    "update:section": (key: string) => typeof key === "string",
+  },
+  setup(props, { emit, slots }) {
+    return () => (
+      <HModal
+        modelValue={props.modelValue}
+        onUpdate:modelValue={(v: boolean) => emit("update:modelValue", v)}
+        title={props.title}
+        width={props.width}
+        contentClass="hk-settings-host"
+      >
+        {/* The per-section slots flow through h()'s third argument — the
+            canonical slots channel. JSX children would wrap the slots
+            object into a vnode child and the keys would never reach the
+            body (caught by the dialog mount test). */}
+        {h(
+          HkSettingsBody,
+          {
+            sections: props.sections,
+            section: props.section,
+            navLabel: props.navLabel,
+            "onUpdate:section": (key: string) => emit("update:section", key),
+            style: { "--hk-settings-height": props.height },
+          },
+          slots,
+        )}
+      </HModal>
+    );
+  },
+});
+
+/**
+ * HSettingsGroup — one titled card in the content pane: the standard
+ * container of a section's controls. Slightly translucent so cards sit
+ * quietly on image wallpapers.
+ */
+export const HkSettingsGroup = defineComponent({
+  name: "HkSettingsGroup",
+  props: {
+    title: { type: String, default: undefined },
+  },
+  setup(props, { slots }) {
+    return () => (
+      <section class="hk-settings-group">
+        {props.title ? <h3 class="hk-settings-group-title">{props.title}</h3> : null}
+        {slots.default?.()}
+      </section>
+    );
+  },
+});
+
+/** HSettingsSub — a titled sub-block inside a group. */
+export const HkSettingsSub = defineComponent({
+  name: "HkSettingsSub",
+  props: {
+    title: { type: String, default: undefined },
+  },
+  setup(props, { slots }) {
+    return () => (
+      <div class="hk-settings-sub">
+        {props.title ? <h4 class="hk-settings-sub-title">{props.title}</h4> : null}
+        {slots.default?.()}
+      </div>
+    );
+  },
+});
+
+/** HSettingsHint — the small muted explanation line under a control. */
+export const HkSettingsHint = defineComponent({
+  name: "HkSettingsHint",
+  setup(_props, { slots }) {
+    return () => <p class="hk-settings-hint">{slots.default?.()}</p>;
+  },
+});

package/src/composables/useSizeMorph.test.ts

@@ -200,6 +200,35 @@ describe("useSizeMorph", () => {
     expect(h.frame.style.transition).toBe("");
   });
 
+  it("keeps the resident rider layers through a contamination-guard release", async () => {
+    // Round 15 rig finding: the guard's mid-flight release() used to
+    // call clearResidentWill(), tearing the chrome promotions down at
+    // the swap frame on capped sheets — every later sweep of the same
+    // open cycle then promoted at STAGE again (the black-block race).
+    // The pin drops (measurement hygiene) but the cycle's layers stay.
+    const rider = document.createElement("div");
+    const h = mountHarness(600, 560, {
+      collectRide: () => [{ el: rider }],
+    });
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.content.appendChild(rider);
+    h.start();
+    expect(rider.style.willChange).toBe("transform");
+
+    h.setNatural(1728);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    // The pin dropped…
+    expect(h.frame.style.height).toBe("");
+    // …but the resident promotion survived the guard, and only the full
+    // stop unwinds it.
+    expect(rider.style.willChange).toBe("transform");
+    expect(h.frame.style.willChange).toBe("clip-path");
+    h.stop();
+    expect(rider.style.willChange).toBe("");
+    expect(h.frame.style.willChange).toBe("");
+  });
+
   it("recovers and pins again once a clean measurement returns", async () => {
     const h = mountHarness(600, 560);
     h.start();
@@ -874,14 +903,15 @@ describe("useSizeMorph fold riders", () => {
     h.setNatural(360);
     h.remeasure();
     await busFrames(2);
-    expect(collected).toBe(1);
+    // One collection at ARM (resident promotion) + one at the stage.
+    expect(collected).toBe(2);
     // A second growth mid-sweep: the old ride is cleared (atomically
     // with the interrupted sweep's landing) and re-collected for the new
     // dance's own stage.
     h.setNatural(420);
     h.remeasure();
     expect(rider.style.transform).toBe("translateY(60px)");
-    expect(collected).toBe(2);
+    expect(collected).toBe(3);
     // The successor sweep runs and lands on its own terms.
     await busFrames(2);
     expect(rider.style.transform).toBe("translateY(0px)");
@@ -1017,3 +1047,104 @@ describe("useSizeMorph fold rider settle handoff", () => {
     h.stop();
   });
 });
+
+// ── Resident rider promotion (round 15, 2026-09-23 black-block report) ──
+// The riders' will-change initially landed at STAGE time: three fresh
+// layer promotions inside the frame's re-raster task, with only the
+// two-frame warmup to absorb them — on the phone GPU the body block
+// composited as black tiles through the early sweep (the same raster
+// race the frame's resident promotion had fixed). The host chrome now
+// promotes ONCE at arm time and keeps its layers for the whole cycle.
+
+describe("useSizeMorph resident rider promotion", () => {
+  it("promotes in-frame riders at arm time and keeps them through settles", async () => {
+    const rider = document.createElement("div");
+    const h = mountHarness(300, 300, {
+      collectRide: () => [{ el: rider }],
+    });
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.content.appendChild(rider);
+    // Before arming there is no promotion.
+    expect(rider.style.willChange).toBe("");
+    h.start();
+    // Armed: the rider (inside the frame subtree) is promoted once,
+    // together with the frame itself.
+    expect(rider.style.willChange).toBe("transform");
+    expect(h.frame.style.willChange).toBe("clip-path");
+
+    // A full sweep: stage → flip → settle. The rider rides, and the
+    // settle must NOT demote it — the landing crossing a layer boundary
+    // is the raster race that read as black blocks on the phone.
+    h.setNatural(360);
+    h.remeasure();
+    expect(rider.style.transform).toBe("translateY(60px)");
+    await busFrames(2);
+    expect(rider.style.transform).toBe("translateY(0px)");
+    fireTransitionEnd(h.frame, "clip-path");
+    expect(rider.style.transform).toBe("");
+    expect(rider.style.willChange).toBe("transform");
+
+    // The whole open cycle's layerization unwinds at stop/hold.
+    h.stop();
+    expect(rider.style.willChange).toBe("");
+    expect(h.frame.style.willChange).toBe("");
+  });
+
+  it("leaves detached (per-swap) riders on the stage-time promotion path", async () => {
+    // A rider NOT in the frame subtree at arm time — the stepflow's
+    // entering body, registered mid-swap — never becomes resident: its
+    // promotion still lands at stage and still releases at the settle.
+    const resident = document.createElement("div");
+    let perSwap: HTMLElement | null = null;
+    const h = mountHarness(300, 300, {
+      collectRide: () => {
+        const out: Array<{ el: HTMLElement }> = [{ el: resident }];
+        if (perSwap) out.push({ el: perSwap });
+        return out;
+      },
+    });
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.content.appendChild(resident);
+    h.start();
+    expect(resident.style.willChange).toBe("transform");
+
+    perSwap = document.createElement("div"); // registered mid-flight, detached
+    h.setNatural(360);
+    h.remeasure();
+    expect(perSwap.style.willChange).toBe("transform");
+    await busFrames(2);
+    fireTransitionEnd(h.frame, "clip-path");
+    expect(perSwap.style.willChange).toBe("");
+    expect(resident.style.willChange).toBe("transform");
+    h.stop();
+  });
+
+  it("unwinds the resident rider layers on unmount", async () => {
+    // The unmount teardown owns its own clearResidentWill (it must not
+    // rely on hold() — an open surface torn down mid-cycle leaves no
+    // other path). Witness: the promoted layer flag outlives the app.
+    const rider = document.createElement("div");
+    const h = mountHarness(300, 300, {
+      collectRide: () => [{ el: rider }],
+    });
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.content.appendChild(rider);
+    h.start();
+    expect(rider.style.willChange).toBe("transform");
+    const mount = mounts.splice(-1)[0]!;
+    mount.app.unmount();
+    expect(rider.style.willChange).toBe("");
+    expect(h.frame.style.willChange).toBe("");
+  });
+
+  it("does not promote riders when the surface is not clip-mode", () => {
+    const rider = document.createElement("div");
+    const h = mountHarness(300, 300, {
+      collectRide: () => [{ el: rider }],
+    });
+    h.content.appendChild(rider);
+    h.start();
+    expect(rider.style.willChange).toBe("");
+    h.stop();
+  });
+});

package/src/composables/useSizeMorph.ts

@@ -235,6 +235,22 @@ export function useSizeMorph(
    *  at open and KEEPING it means step morphs never cross a layer
    *  boundary at all. */
   let residentWill = false;
+  /** Resident RIDER promotions (2026-09-23 round 15, the black-block
+   *  regression report): the fold riders' own will-change initially
+   *  landed at STAGE time — three fresh layer promotions (header,
+   *  subheader, body block) inside the same task as the frame's
+   *  re-raster, with only the two-frame warmup to absorb them. On the
+   *  phone GPU the promoted-but-unrastered body block composited as
+   *  black tiles through the early sweep — the same race the frame's
+   *  resident promotion had fixed, re-entered from the side. The host
+   *  chrome riders (whatever collectRide returns at ARM time, when no
+   *  swap is registered) now promote ONCE at open and keep their layers
+   *  for the whole cycle; a sweep's settle no longer demotes them, so
+   *  stage and landing cross no layer boundaries at all. Per-swap
+   *  riders (the stepflow's entering body — registered mid-flight,
+   *  small, and opacity-composited by its own fade anyway) keep the
+   *  stage-time promotion. */
+  let residentRideEls: HTMLElement[] = [];
   /** Identity of the sweep currently staged/folding, echoed to consumers. */
   let sweepSeq = 0;
   let activeSweep = 0;
@@ -336,7 +352,12 @@ export function useSizeMorph(
       // instant; opacity (still listed with its own clock) keeps running.
       r.el.style.transition = r.ownTransition || "none";
       r.el.style.transform = "";
-      r.el.style.willChange = "";
+      // Resident-promoted riders (the host chrome, promoted at arm time)
+      // KEEP their layers through the settle — demoting here would put
+      // the raster race back at every landing (round 15 black blocks).
+      if (!residentRideEls.includes(r.el)) {
+        r.el.style.willChange = "";
+      }
     }
     void frame.value?.offsetHeight;
     for (const r of rideEls) {
@@ -423,8 +444,15 @@ export function useSizeMorph(
     }
   }
 
-  /** Drop the resident layer promotion (hold / release paths). */
+  /** Drop the resident layer promotion (hold / release paths) — the
+   *  frame's own and the resident riders' together: the whole open
+   *  cycle's layerization unwinds at once, inside the close
+   *  choreography's own leave window. */
   function clearResidentWill(): void {
+    for (const el of residentRideEls) {
+      el.style.willChange = "";
+    }
+    residentRideEls = [];
     if (!residentWill) return;
     residentWill = false;
     const f = frame.value;
@@ -551,7 +579,15 @@ export function useSizeMorph(
     const f = frame.value;
     if (f) f.style.height = "";
     stopReveal();
-    clearResidentWill();
+    // Deliberately NOT clearResidentWill(): release() runs both on the
+    // full-stop path AND mid-flight from the contamination guard, and
+    // the guard's pin drop is a measurement-hygiene event, not a cycle
+    // end — dropping the resident layers there re-armed the stage-time
+    // raster race for every later sweep of the same open cycle (round
+    // 15 rig finding, confirmed by the adversarial round: the capped
+    // case tore header/body/frame promotions down at the swap frame).
+    // The armed stop path clears them via hold(); a never-armed stop
+    // has nothing to clear; unmount owns its own teardown.
     pinned = 0;
   }
 
@@ -799,11 +835,30 @@ export function useSizeMorph(
     // Resident promotion on clip-mode surfaces (see residentWill): the
     // layer crosses no boundary during later step morphs. Applied here,
     // at the open edge — one promotion per open cycle instead of one
-    // per resize.
+    // per resize. The HOST CHROME RIDERS promote here too (see
+    // residentRideEls): collectRide at arm time returns exactly the
+    // chrome (no swap is registered mid-open), and their layers then
+    // live for the whole cycle — a sweep's stage promotes nothing but
+    // the small per-swap riders, so the phone GPU never rasterizes a
+    // big layer inside the morph window it cannot finish in time.
     const f0 = frame.value;
     if (f0 && clipMode(f0)) {
       f0.style.willChange = "clip-path";
       residentWill = true;
+      if (options.collectRide) {
+        residentRideEls = options.collectRide()
+          .map((entry) => entry.el)
+          .filter((el) => {
+            try {
+              return frame.value?.contains(el) ?? false;
+            } catch {
+              return false;
+            }
+          });
+        for (const el of residentRideEls) {
+          el.style.willChange = "transform";
+        }
+      }
     }
     if (typeof ResizeObserver === "undefined" || !content.value) {
       remeasure();

package/src/index.ts

@@ -435,6 +435,15 @@ export {
   type HAboutLinkIcon,
 } from "./components/HkAboutModal";
 export { HkLogWindow as HLogWindow, type HLogTab } from "./components/HkLogWindow";
+export {
+  HkSettingsBody as HSettingsBody,
+  HkSettingsDialog as HSettingsDialog,
+  HkSettingsGroup as HSettingsGroup,
+  HkSettingsSub as HSettingsSub,
+  HkSettingsHint as HSettingsHint,
+  type HkSettingsSection,
+} from "./components/HkSettingsDialog";
+
 export { HkCookieConsent as HCookieConsent } from "./components/HkCookieConsent";
 export {
   HkAttachmentModal as HAttachmentModal,