@celestia-island/hikari 0.55.202 → 0.55.204

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.202",
+  "version": "0.55.204",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/animation/registerAnimations.ts

@@ -66,6 +66,9 @@ export function isCssAnimationsEnabled(): boolean {
 registerCssAnimation("s-nav-item-badge-pulse", { infinite: true });
 // styles/admin-tokens.scss — auth card entrance (plays once).
 registerCssAnimation("s-auth-card-in");
+// HkPaneHolder's reveal (opacity-only, one shot) — the keep-mounted pane
+// slot's entry, the dissolve-family language for persistent panes.
+registerCssAnimation("hk-pane-holder-in");
 // styles/admin-tokens.scss — status-bar recovery flash (plays once):
 // the traffic light's green background blink when a dropped connection
 // comes back.

package/src/components/HkAdminShell.tsx

@@ -1,5 +1,5 @@
-import { computed, defineComponent, ref } from "vue";
-import { HDrawer, HScrollContainer, useBreakpoint } from "@celestia-island/hikari";
+import { computed, defineComponent, ref, type PropType } from "vue";
+import { HkCrossfade, HDrawer, HScrollContainer, useBreakpoint } from "@celestia-island/hikari";
 import { provideActionBar } from "../composables/useActionBar";
 import { useI18n } from "../i18n/context";
 
@@ -162,6 +162,13 @@ export const HkAdminShell = defineComponent({
      *  verbatim at every width unless the page opts into
      *  `contentBleedOnMobile`. */
     contentPadding: { type: String, default: "1.5rem" },
+    /** Identity of the content page on stage (task-4, 2026-10-24):
+     *  pass the current view/route key and the content area swaps pages
+     *  through the family crossfade — the library owns the page-slot
+     *  mechanism instead of every host hand-wrapping it. Omitted (or
+     *  null) renders the slot bare: canvas-like hosts that mount one
+     *  persistent stage opt out. */
+    contentKey: { type: [String, Number] as PropType<string | number | null>, default: null },
     /** Whether the content on screen is a CANVAS — a 2D board or the 3D
      *  scene — that must span the full phone width. OPT-IN, declared by
      *  the page that renders the canvas (2026-10-04 user direction: the
@@ -257,7 +264,15 @@ export const HkAdminShell = defineComponent({
               {/* Padding lives INSIDE the scroll viewport (an inner
                   wrapper) so card box-shadows are not clipped at the
                   viewport edges. */}
-              <div style={contentStyle.value}>{slots.content?.()}</div>
+              <div style={contentStyle.value}>
+                {props.contentKey != null ? (
+                  <HkCrossfade swapKey={props.contentKey} class="s-admin-shell-swap">
+                    {slots.content?.()}
+                  </HkCrossfade>
+                ) : (
+                  slots.content?.()
+                )}
+              </div>
             </HScrollContainer>
           </main>
 

package/src/components/HkAdminTablePage.tsx

@@ -1,5 +1,6 @@
 import { defineComponent, type Component, type PropType } from "vue";
 import { HAlert, HCard, HEmptyState, HSpinner, HTable, useI18n } from "@celestia-island/hikari";
+import HkCrossfade from "./HkCrossfade";
 import { HkPageHeader } from "./HkPageHeader";
 import type { HkRowManageGate } from "./HkTable";
 
@@ -98,37 +99,53 @@ export const HkAdminTablePage = defineComponent({
            *  render alongside the error branch (its precondition — rows on
            *  screen — is exactly what the error branch removes). */}
           {props.staleError && !props.error ? <HAlert message={props.staleError} /> : null}
-          {props.error ? (
-            <HAlert message={props.error} />
-          ) : props.loading && !props.rows.length ? (
-            <HSpinner center />
-          ) : !props.rows.length ? (
-            <HEmptyState
-              boxed
-              title={emptyTitle}
-              description={props.emptyDescription}
-            >
-              {emptySlots}
-            </HEmptyState>
-          ) : slots.body ? (
-            <div class="hk-admin-table-page-body">{slots.body()}</div>
-          ) : (
-            <HCard padded={false}>
-              <HTable
-                columns={props.columns}
-                rows={props.rows}
-                rowKey={props.rowKey}
-                draggable={props.draggable}
-                manageable={props.manageable}
-                onReorder={(from: number, to: number) => emit("reorder", from, to)}
-                onManage={(row: Record<string, unknown>, opener: HTMLElement) =>
-                  emit("manage", row, opener)
-                }
+          {/* The body is a page slot with three generations — error,
+              loading/empty, content (task-4, 2026-10-24): the family
+              crossfade owns the exchange, so every admin table page in
+              every host dissolves between them instead of popping. The
+              key collapses loading-vs-empty into one "placeholder"
+              generation: spinner → empty is a data arrival, not a slot
+              identity change worth animating. */}
+          <HkCrossfade
+            swapKey={
+              props.error ? "error"
+                : props.loading && !props.rows.length ? "placeholder"
+                  : !props.rows.length ? "placeholder"
+                    : "content"
+            }
+          >
+            {props.error ? (
+              <HAlert message={props.error} />
+            ) : props.loading && !props.rows.length ? (
+              <HSpinner center />
+            ) : !props.rows.length ? (
+              <HEmptyState
+                boxed
+                title={emptyTitle}
+                description={props.emptyDescription}
               >
-                {slots}
-              </HTable>
-            </HCard>
-          )}
+                {emptySlots}
+              </HEmptyState>
+            ) : slots.body ? (
+              <div class="hk-admin-table-page-body">{slots.body()}</div>
+            ) : (
+              <HCard padded={false}>
+                <HTable
+                  columns={props.columns}
+                  rows={props.rows}
+                  rowKey={props.rowKey}
+                  draggable={props.draggable}
+                  manageable={props.manageable}
+                  onReorder={(from: number, to: number) => emit("reorder", from, to)}
+                  onManage={(row: Record<string, unknown>, opener: HTMLElement) =>
+                    emit("manage", row, opener)
+                  }
+                >
+                  {slots}
+                </HTable>
+              </HCard>
+            )}
+          </HkCrossfade>
           {slots["create-modal"]?.()}
           {slots["edit-modal"]?.()}
         </div>

package/src/components/HkMarkdownRenderer.scss

@@ -78,6 +78,43 @@
   margin: 0;
 }
 
+/* Markdown tables size to their content, so a wide one (many columns, or
+   a single unbreakable cell) pushes every ancestor's min-content width
+   past its box — clipping hosts (the modal reading region, chat bubbles,
+   report cards) then leave the far columns unreachable. The renderer wraps
+   every table in the same two-level shape as code above: this wrap is the
+   rail HOST (track host for the scroller below — it contains ONLY the
+   scrolling box, so the rail hugs the table instead of spanning the whole
+   markdown body, useOverlayScrollbar's host contract) and carries the
+   table's vertical margin, because a scroll container never collapses
+   margins with its children and the margin must keep collapsing with the
+   surrounding flow exactly as the bare table's did. */
+.hk-md-table-wrap {
+  position: relative;
+  margin: 0.75em 0;
+}
+
+/* The horizontal rail itself — the viewport the overlay scrollbar attaches
+   to. Only a genuinely overflowing table grows the scroll; normal tables
+   keep their full-width layout. Same hidden-native-chrome contract as
+   .hk-md-code (the 2026-10-01 native-bar regression rule). */
+.hk-md-table-scroll {
+  overflow-x: auto;
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+
+/* The railed table renders flush inside its scroller — its old vertical
+   margin lives on the host wrap above. Outranks `.hk-markdown table`
+   (two classes + one type vs one class + one type); GFM tables cannot
+   nest, so no other table is ever matched. */
+.hk-markdown .hk-md-table-wrap table {
+  margin: 0;
+}
+
 .hk-md-code-lang {
   position: absolute;
   top: 0.25em;

package/src/components/HkMarkdownRenderer.tsx

@@ -61,7 +61,8 @@ async function renderMarkdown(content: string): Promise<string> {
     return renderPlain(content);
   }
 
-  const renderer = new (marked as unknown as { Renderer: new () => Record<string, unknown> }).Renderer();
+  const RendererCtor = (marked as unknown as { Renderer: new () => Record<string, unknown> }).Renderer;
+  const renderer = new RendererCtor();
 
   (renderer as Record<string, unknown>).code = function (tok: { text: string; lang?: string }) {
     const highlighted = tryHighlight(tok.text, tok.lang);
@@ -74,6 +75,21 @@ async function renderMarkdown(content: string): Promise<string> {
     return `<div class="hk-md-code-wrap"><div class="hk-md-code">${langLabel}<pre><code class="hljs${langAttr}">${highlighted}</code></pre></div></div>`;
   };
 
+  (renderer as Record<string, unknown>).table = function (token: unknown) {
+    // Tables size to their content: a wide one (many columns, or a single
+    // unbreakable cell) pushes every ancestor's min-content width past its
+    // box, and clipping hosts (modal reading region, chat bubbles, report
+    // cards) leave the far columns unreachable. Same two-level shape as the
+    // code override above: `.hk-md-table-wrap` is the rail HOST (a plain
+    // positioned box wrapping only the scroller — the engine anchors the
+    // track in the viewport's parent), `.hk-md-table-scroll` is the
+    // viewport that actually rails. Rail the TABLE itself — normal tables
+    // keep their full-width layout; only a genuinely overflowing one grows
+    // the horizontal scroll (see .hk-md-table-scroll).
+    const inner = (RendererCtor.prototype as { table: (t: unknown) => string }).table.call(this, token);
+    return `<div class="hk-md-table-wrap"><div class="hk-md-table-scroll">${inner}</div></div>`;
+  };
+
   const raw = marked.parse(content, { renderer, async: false });
   const html = typeof raw === "string" ? raw : "";
   return DOMPurify.sanitize(html);
@@ -114,33 +130,34 @@ export default defineComponent({
       { immediate: true },
     );
 
-    // Overlay scrollbars (shared chrome) on markdown code blocks. The
-    // body is innerHTML-rendered and fully replaced on every parse, so
-    // the attachment set is reconciled after each render pass: handles
-    // whose block left the DOM detach, fresh blocks attach.
+    // Overlay scrollbars (shared chrome) on the markdown blocks that can
+    // rail horizontally: code blocks and table scrollers. The body is
+    // innerHTML-rendered and fully replaced on every parse, so the
+    // attachment set is reconciled after each render pass: handles whose
+    // block left the DOM detach, fresh blocks attach.
     const bodyRef = ref<HTMLElement>();
-    const codeScrollbars: Array<{ el: HTMLElement; handle: OverlayScrollbarHandle }> = [];
+    const overlayScrollbars: Array<{ el: HTMLElement; handle: OverlayScrollbarHandle }> = [];
 
-    function syncCodeScrollbars() {
-      for (let i = codeScrollbars.length - 1; i >= 0; i--) {
-        if (!codeScrollbars[i].el.isConnected) {
-          codeScrollbars[i].handle.detach();
-          codeScrollbars.splice(i, 1);
+    function syncOverlayScrollbars() {
+      for (let i = overlayScrollbars.length - 1; i >= 0; i--) {
+        if (!overlayScrollbars[i].el.isConnected) {
+          overlayScrollbars[i].handle.detach();
+          overlayScrollbars.splice(i, 1);
         }
       }
-      for (const el of bodyRef.value?.querySelectorAll<HTMLElement>(".hk-md-code") ?? []) {
-        if (codeScrollbars.some((c) => c.el === el)) continue;
-        codeScrollbars.push({ el, handle: attachOverlayScrollbars(el, { axis: "horizontal" }) });
+      for (const el of bodyRef.value?.querySelectorAll<HTMLElement>(".hk-md-code, .hk-md-table-scroll") ?? []) {
+        if (overlayScrollbars.some((c) => c.el === el)) continue;
+        overlayScrollbars.push({ el, handle: attachOverlayScrollbars(el, { axis: "horizontal" }) });
       }
     }
 
     watch(renderedHtml, () => {
-      void nextTick(syncCodeScrollbars);
+      void nextTick(syncOverlayScrollbars);
     });
 
     onBeforeUnmount(() => {
-      for (const c of codeScrollbars) c.handle.detach();
-      codeScrollbars.length = 0;
+      for (const c of overlayScrollbars) c.handle.detach();
+      overlayScrollbars.length = 0;
     });
 
     return () => (

package/src/components/HkPaneHolder.scss

@@ -0,0 +1,33 @@
+// HkPaneHolder — the keep-mounted pane slot (see the TSX doc for when to
+// choose it over the dissolve primitives).
+
+.hk-pane-holder {
+  display: none;
+
+  // Active: back in the layout with the family dissolve's own language —
+  // a one-shot opacity reveal. No transform: a pane sliding in would
+  // disagree with every crossfade around it.
+  &[data-active] {
+    display: block;
+    animation: hk-pane-holder-in var(--duration-normal, 0.3s) ease-out;
+  }
+}
+
+@keyframes hk-pane-holder-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+// Opt-outs: the global animation switch is the host's, reduced motion is
+// the OS's — the holder obeys both (an inline-less rule; the animation is
+// declared here in the sheet, so unlike HkTransitionContainer's inline
+// duration a media query CAN reach it).
+html[data-css-animations="0"] .hk-pane-holder[data-active] {
+  animation: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hk-pane-holder[data-active] {
+    animation-duration: var(--duration-fast, 0.15s);
+  }
+}

package/src/components/HkPaneHolder.test.tsx

@@ -0,0 +1,99 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import sass from "sass";
+
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref, type App } from "vue";
+
+import HkPaneHolder from "./HkPaneHolder";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const containers: HTMLElement[] = [];
+
+function mountHolder(active: boolean): {
+  app: App;
+  root: HTMLElement;
+  child: HTMLElement;
+  setActive: (v: boolean) => void;
+} {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+  const isActive = ref(active);
+  const Child = defineComponent({
+    setup() {
+      // The point of the holder: the pane's instance state SURVIVES
+      // deactivation. A counter proves the component never unmounted.
+      const mounts = ref(0);
+      const tick = () => { mounts.value += 1; };
+      return () => h("button", { type: "button", onClick: tick, "data-mounts": String(mounts.value) }, "pane");
+    },
+  });
+  const Wrapper = defineComponent({
+    render: () =>
+      h(HkPaneHolder, { active: isActive.value }, { default: () => h(Child) }),
+  });
+  const app = createApp(Wrapper);
+  app.mount(container);
+  const root = container.firstElementChild as HTMLElement;
+  const child = root.firstElementChild as HTMLElement;
+  return { app, root, child, setActive: (v: boolean) => { isActive.value = v; } };
+}
+
+afterEach(() => {
+  for (const c of containers.splice(0)) c.remove();
+});
+
+describe("HkPaneHolder — DOM contract", () => {
+  it("renders the holder class and the data-active attribute only when active", async () => {
+    const t = mountHolder(false);
+    expect(t.root.classList.contains("hk-pane-holder")).toBe(true);
+    expect(t.root.hasAttribute("data-active")).toBe(false);
+    expect(t.child).toBeDefined(); // mounted, not unmounted
+    t.setActive(true);
+    await nextTick();
+    expect(t.root.hasAttribute("data-active")).toBe(true);
+    t.app.unmount();
+  });
+
+  it("keeps component state across deactivate/reactivate (the entire point)", async () => {
+    const t = mountHolder(true);
+    (t.child as HTMLButtonElement).click();
+    (t.child as HTMLButtonElement).click();
+    await new Promise((r) => setTimeout(r, 0));
+    expect(t.child.getAttribute("data-mounts")).toBe("2");
+    t.setActive(false);
+    await new Promise((r) => setTimeout(r, 0));
+    t.setActive(true);
+    await new Promise((r) => setTimeout(r, 0));
+    const childAfter = t.root.firstElementChild as HTMLElement;
+    // Same instance: the counter did not reset to 0.
+    expect(childAfter.getAttribute("data-mounts")).toBe("2");
+    t.app.unmount();
+  });
+});
+
+describe("HkPaneHolder — stylesheet contract", () => {
+  const css = sass.compile(join(here, "HkPaneHolder.scss")).css;
+  const scss = readFileSync(join(here, "HkPaneHolder.scss"), "utf-8");
+
+  it("hides the base holder and reveals on [data-active]", () => {
+    expect(css).toMatch(/\.hk-pane-holder\s*\{[^}]*display:\s*none/s);
+    expect(css).toMatch(/\.hk-pane-holder\[data-active\]\s*\{[^}]*display:\s*block/s);
+  });
+
+  it("reveals with opacity only — no transform, ever", () => {
+    const keyframe = /@keyframes\s+hk-pane-holder-in\s*\{([^}]*)\}/s.exec(css);
+    expect(keyframe).not.toBeNull();
+    expect(keyframe![1]).toContain("opacity");
+    expect(keyframe![1]).not.toContain("transform");
+    expect(keyframe![1]).not.toContain("translate");
+  });
+
+  it("obeys the global animation switch and reduced motion", () => {
+    expect(css).toMatch(/html\[data-css-animations="0"\][^{]*\{[^}]*animation:\s*none/s);
+    expect(css).toMatch(/prefers-reduced-motion[^{]*\{[^}]*animation-duration/s);
+  });
+});

package/src/components/HkPaneHolder.tsx

@@ -0,0 +1,57 @@
+import { defineComponent } from "vue";
+
+import "./HkPaneHolder.scss";
+
+/**
+ * HkPaneHolder — the keep-mounted pane slot.
+ *
+ * The third pane-swap surface, for the class of content the dissolve
+ * primitives cannot serve: PERSISTENT panes whose instance must survive
+ * while another pane is active — draft stores (an editor whose unsaved
+ * state lives in the component), canvases/WebGL stages that are too
+ * expensive to rebuild, or sockets that must not unplug.
+ *
+ * `HkCrossfade` / `HkTransitionContainer` swap by keying: the leaving
+ * generation UNMOUNTS when the dissolve completes — exactly wrong for a
+ * draft store. This holder instead keeps every pane in the tree and
+ * toggles reachability: `display: none` while inactive (out of layout,
+ * inert), `display: block` plus a one-shot opacity reveal when it
+ * becomes active. The reveal is opacity-ONLY at the family's
+ * `--duration-normal`, matching the dissolve language — no movement,
+ * ever.
+ *
+ * Contract:
+ * - `active` is a boolean, not a key: the holder IS one pane. A tab
+ *   surface renders one holder per persistent pane beside the ordinary
+ *   panel slots it already has.
+ * - The inactive pane is `display: none` (inert, out of the layout,
+ *   unreadable by assistive tech) but its component instances, state
+ *   and watchers all LIVE — that is the entire point.
+ * - The reveal animation is `hk-pane-holder-in` (opacity 0→1, one
+ *   shot, registered with the animation registry); reduced motion and
+ *   the global `data-css-animations="0"` switch clamp it to instant,
+ *   so the holder never animates for users who opted out.
+ * - No leave animation: the outgoing pane simply hides (it is usually
+ *   being covered by an incoming ordinary panel whose own dissolve is
+ *   the visible exchange).
+ */
+export const HkPaneHolder = defineComponent({
+  name: "HkPaneHolder",
+  props: {
+    /** Whether THIS pane is the active one. */
+    active: { type: Boolean, required: true },
+    tag: { type: String, default: "div" },
+  },
+  setup(props, { slots }) {
+    return () => {
+      const Tag = props.tag as "div" | "section";
+      return (
+        <Tag class="hk-pane-holder" data-active={props.active || undefined}>
+          {slots.default?.()}
+        </Tag>
+      );
+    };
+  },
+});
+
+export default HkPaneHolder;

package/src/components/__tests__/hkMarkdownTableWrap.test.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Source contract for the markdown table rail (2026-10-24: a wide table —
+ * many columns or one unbreakable cell — pushed every ancestor's
+ * min-content width past its box, and clipping hosts (the chest report
+ * modal's reading region, chat bubbles, report cards) left the far columns
+ * unreachable).
+ *
+ * vitest never resolves stylesheets, and the renderer's marked/DOMPurify
+ * are lazy dynamic imports, so this pins the moving parts as source
+ * contracts in the same idiom as hkMarkdownLang.test.ts:
+ *
+ *   - the renderer overrides `table` to wrap the emitted table in the
+ *     two-level rail shape (host + scroller), delegating to the base
+ *     Renderer for the table markup itself;
+ *   - the stylesheet gives the scroller the horizontal rail with the
+ *     hidden-native-chrome contract (the 2026-10-01 native-bar rule) and
+ *     makes the wrap a positioned rail host carrying the vertical margin;
+ *   - the overlay-scrollbar reconciliation covers the scroller alongside
+ *     `.hk-md-code`, so the rail gets the shared chrome and detaches with
+ *     the block.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const tsx = readFileSync(join(here, "../HkMarkdownRenderer.tsx"), "utf-8");
+const scss = readFileSync(join(here, "../HkMarkdownRenderer.scss"), "utf-8");
+
+describe("markdown table rail contract", () => {
+  it("the renderer wraps tables in the rail via the base renderer", () => {
+    // The override must DELEGATE (base table markup) and then wrap — a
+    // replacement that dropped the delegation would lose marked's table
+    // rendering; a wrap without the override is the dead-selector shape.
+    // The wrap is TWO-level (`.hk-md-table-wrap` host containing the
+    // `.hk-md-table-scroll` viewport): the overlay engine anchors its
+    // track in the viewport's PARENT, so a single-level wrap would rail
+    // against the whole `.hk-markdown-body` instead of the table.
+    expect(tsx).toMatch(
+      /return\s*`<div class="hk-md-table-wrap"><div class="hk-md-table-scroll">\$\{inner\}<\/div><\/div>`;/,
+    );
+    expect(tsx).toMatch(
+      /RendererCtor\.prototype as \{ table: \(t: unknown\) => string \}\)\.table\.call\(this, token\)/,
+    );
+  });
+
+  it("the rail stylesheet keeps native chrome hidden on the scroller", () => {
+    expect(scss).toMatch(
+      /\.hk-md-table-scroll\s*\{[^}]*overflow-x:\s*auto/,
+    );
+    expect(scss).toMatch(
+      /\.hk-md-table-scroll\s*\{[^}]*scrollbar-width:\s*none/,
+    );
+  });
+
+  it("the wrap is a positioned host carrying the table's vertical margin", () => {
+    // Host: wraps ONLY the scroller and is positioned, so the rail hugs
+    // the table (no guard promotion of `.hk-markdown-body`); the margin
+    // lives here because the scroll box never collapses margins with its
+    // children — this keeps normal tables' surrounding rhythm identical
+    // to the pre-wrap bare table.
+    expect(scss).toMatch(
+      /\.hk-md-table-wrap\s*\{[^}]*position:\s*relative/,
+    );
+    expect(scss).toMatch(
+      /\.hk-md-table-wrap\s*\{[^}]*margin:\s*0\.75em\s+0/,
+    );
+    expect(scss).toMatch(
+      // `0\s*;` — a bare `margin:\s*0` would also prefix-match the
+      // bare-table `margin: 0.75em 0` and false-pass the very double-margin
+      // regression this reset exists to prevent.
+      /\.hk-markdown \.hk-md-table-wrap table\s*\{[^}]*margin:\s*0\s*;/,
+    );
+  });
+
+  it("the overlay reconciliation covers the rail alongside code blocks", () => {
+    expect(tsx).toMatch(
+      /querySelectorAll<HTMLElement>\("\.hk-md-code, \.hk-md-table-scroll"\)/,
+    );
+  });
+});

package/src/components/paneSwap.contract.test.ts

@@ -11,6 +11,22 @@ const componentsDir = here;
  * Pane-swap contract — the enforcement half of the family's transition
  * primitives (user audit 2026-10-23).
  *
+ * THE DECISION TABLE (which surface for which class of slot):
+ *
+ *   ┌──────────────────────────────┬───────────────────────────────┐
+ *   │ the content can UNMOUNT      │ HkTransitionContainer (frame │
+ *   │ when it leaves the stage     │ must morph) / HkCrossfade    │
+ *   │                              │ (same-box dissolve)          │
+ *   ├──────────────────────────────┼───────────────────────────────┤
+ *   │ the instance must SURVIVE    │ HkPaneHolder (draft stores,  │
+ *   │ (draft store, canvas, sock)  │ canvases, sockets)           │
+ *   ├──────────────────────────────┼───────────────────────────────┤
+ *   │ a WIZARD STEPPER inside a    │ HkStepFlow — see its exception│
+ *   │ modal sheet                  │ below; it is a sibling with a │
+ *   │                              │ different contract, not a    │
+ *   │                              │ rogue pane slot              │
+ *   └──────────────────────────────┴───────────────────────────────┘
+ *
  * THE RULE. A "pane slot" is a container whose visible content is selected
  * by a state key while the container stays put: tabs, settings sections,
  * step bodies, view areas. Every such slot must swap through the standard
@@ -51,6 +67,11 @@ const STANDARD_PANE_HOSTS: Array<{ file: string; marker: string; why: string }>
     marker: "<HkTransitionContainer",
     why: "settings sections are a page-scale pane slot (migrated 2026-10-23)",
   },
+  {
+    file: "HkAdminTablePage.tsx",
+    marker: "<HkCrossfade",
+    why: "the error/placeholder/content body is a page slot every admin table page inherits (2026-10-24)",
+  },
 ];
 
 /** Justified bespoke mechanisms: "<scss file>: <animation identifier>" → reason. */
@@ -66,6 +87,14 @@ const SANCTIONED_SWAP_KEYFRAMES: Record<string, string> = {
  *  animation must be argued, decorative pulses and spinners do not. */
 const SWAP_VOCABULARY = /(pane|swap|crossfade|morph|sheet)/;
 
+/** The primitives' own stylesheets ARE the sanctioned mechanism — their
+ *  keyframes are the family language itself, not bespoke swaps. */
+const PRIMITIVE_SHEETS = new Set([
+  "HkCrossfade.scss",
+  "HkTransitionContainer.scss",
+  "HkPaneHolder.scss",
+]);
+
 function readComponent(file: string): string {
   return readFileSync(join(componentsDir, file), "utf-8");
 }
@@ -100,7 +129,34 @@ describe("pane-swap contract", () => {
       // wrapped by the standard above or justified here.
       "HkTabs.tsx", // wrapped by HkTransitionContainer (pinned above)
       "HkSettingsDialog.tsx", // wrapped by HkTransitionContainer (pinned above)
-      "HkStepFlow.tsx", // justified: frozen-sheet two-window protocol + direction axis
+      // HkStepFlow is NOT a rogue pane slot — it is a sibling mechanism
+      // with a contract the generic primitives deliberately do not
+      // offer (2026-10-24 deep-dive ruling; do not re-litigate without
+      // reading this):
+      //  1. SEQUENTIAL two-window choreography (slide with the hosting
+      //     sheet's height FROZEN, then the morph plays ALONE) — the
+      //     inversion of HkTransitionContainer's concurrent morph, born
+      //     from the 2026-09-23 round-16 user directive after the
+      //     concurrent form overloaded phone GPU raster threads
+      //     (whole-region black flashes no layering fix absorbed).
+      //  2. A direction axis (translateX travel + RTL mirroring) that
+      //     HkCrossfade's contract forbids — its tests pin
+      //     opacity-only, no transform, ever.
+      //  3. The hk-stepflow-swap sheet protocol: HkModal freezes its
+      //     height pin on "swap", safety-unfreezes (ms+650), and
+      //     height-morphs alone on "morph".
+      //  4. Six round-numbered field incidents live in its logic:
+      //     r16 align-self:start (grid stretch zeroed every shrink's
+      //     delta), r17 near-instant clip sweep (moving clip edges
+      //     re-raster per frame), r18 announce-AFTER-patch (a shrink
+      //     read the leaving body's geometry and no-opped), r22
+      //     Android-autofill strobe (dropFlowFocus before the swap),
+      //     r24 sticky-pin vs modal gutter-cover layering, and
+      //     preemptSwap keeping whichever body is actually visible
+      //     (opacity > 0.05) when interrupted mid-slide.
+      // Merging any of this into the generic container would change its
+      // semantics for every existing call site. Permanent exception.
+      "HkStepFlow.tsx",
       "HkAdminShell.tsx", // content slot is host-owned; hosts key it (chest wraps HkCrossfade)
       "HkThemePanelContent.tsx", // forwards to HTabs (HkTabs), inherits the mechanism
       "HkMenuPanel.tsx", // menu items, not a pane swap
@@ -124,6 +180,7 @@ describe("pane-swap contract", () => {
       for (const match of text.matchAll(/@keyframes\s+([\w-]+)/g)) {
         const name = match[1];
         if (!SWAP_VOCABULARY.test(name)) continue;
+        if (PRIMITIVE_SHEETS.has(file)) continue;
         const key = `${file}: ${name}`;
         if (!SANCTIONED_SWAP_KEYFRAMES[key]) offenders.push(`@keyframes ${key}`);
       }

package/src/index.ts

@@ -614,6 +614,7 @@ export { default as HkCopyBadge } from "./components/HkCopyBadge";
 export { default as HkConfirmDialog } from "./components/HkConfirmDialog";
 export { default as HkCrossfade } from "./components/HkCrossfade";
 export { default as HkTransitionContainer } from "./components/HkTransitionContainer";
+export { default as HkPaneHolder } from "./components/HkPaneHolder";
 export { default as HkWindowControls, isApplePlatform } from "./components/HkWindowControls";
 export { default as HkStatusRow } from "./components/HkStatusRow";
 export type { HkStatusRowTone } from "./components/HkStatusRow";