@dxos/app-framework 0.8.4-main.40e3dcdf1b → 0.8.4-main.43cb759274

package/src/vite-plugin/boot-loader/BootLoader.solid-stories.tsx

@@ -0,0 +1,198 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { createSignal, onCleanup, onMount } from 'solid-js';
+import { type Meta, type StoryObj } from 'storybook-solidjs-vite';
+
+import bootLoaderCss from './loader-app/boot-loader.css?raw';
+import { mountLoader } from './loader-app/mount';
+
+//
+// Development surface for the boot loader. Mounts the *real* Solid `Loader`
+// (via `mountLoader` — the same entry the inlined production bundle runs) into a
+// `#boot-loader` backdrop, then drives it through `window.__bootLoader` exactly
+// as the host app does. There is no reconstruction of the loader DOM, so the
+// story and production cannot drift. Iterate the loader's look here with HMR.
+//
+
+/**
+ * Inlined snapshot of `packages/ui/brand/assets/icons/composer-icon.svg` — keeps
+ * the story self-contained (production pipes the same file in via the plugin's
+ * `markSvg` option) while previewing the real brand palette.
+ */
+const COMPOSER_MARK = `
+  <svg viewBox="0 0 256 256" xmlns="http://www.w3.org/2000/svg" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <g transform="matrix(0.969697,0,0,1,-570.182,0)">
+      <rect x="588" y="0" width="264" height="256" style="fill:none;"/>
+      <g transform="matrix(0.917198,0,0,1,-223.93,-876)">
+        <path d="M1065.83,1064L1029.14,1064C991.913,1064 961.684,1037.12 961.684,1004C961.684,971.197 991.282,944.542 1028.02,944.008L1028.02,944L1047.85,944L1039.21,968L1029.14,968C1006.79,968 988.669,984.118 988.669,1004C988.669,1023.87 1006.81,1040 1029.14,1040C1029.38,1040 1029.62,1040 1029.85,1040L1029.85,1040L1074.47,1040L1065.83,1064ZM1083.11,1040L1083.11,1040L1083.11,1064L1083.11,1064L1083.11,1040Z" style="fill:rgb(1,122,183);"/>
+      </g>
+      <path d="M761.579,164L720,164C699.51,164 682.875,147.869 682.875,128C682.875,108.452 698.942,92.543 718.969,92.014L718.969,92L729.238,92L721.317,116L720,116C713.165,116 707.625,121.373 707.625,128C707.625,134.623 713.17,140 720,140C720.072,140 720.144,139.999 720.216,139.998L720.216,140L769.5,140L761.579,164Z" style="fill:rgb(6,197,253);"/>
+      <path d="M745.738,212L720.025,212L720,212C672.202,212 633.389,174.377 633.375,128.024C633.361,81.958 671.591,44.542 718.969,44.006L718.969,44L719.975,44L745.079,44L737.159,68L719.982,68C685.809,68.01 658.115,94.88 658.125,128.017C658.135,161.126 685.858,188 720,188L720.018,188C720.378,188 720.738,187.997 721.098,187.991L721.098,188L753.659,188L745.738,212Z" style="fill:rgb(10,75,105);"/>
+      <g transform="matrix(1.03125,0,0,1,588,0)">
+        <path d="M128,236C68.393,236 20,187.607 20,128C20,68.353 68.353,20 128,20L160,20L152.319,44L128,44C81.608,44 44,81.608 44,128C44,174.361 81.639,212 128,212C127.756,212.004 127.878,212.004 128,212.003C128.122,212.002 128.244,212 128,212L152.958,212L145.277,236L128,236ZM128,236C128.628,236 127.372,236.011 128,236Z" style="fill:rgb(5,40,61);"/>
+      </g>
+    </g>
+  </svg>
+`;
+
+/** Approximate plugin count for the simulation (production count is dynamic). */
+const STORY_PLUGIN_COUNT = 80;
+/** Tick interval for the determinate-progress simulation, in ms. */
+const STORY_TICK_MS = 50;
+
+type SimState = 'creep' | 'progress' | 'done';
+
+/**
+ * Harness component: owns the `#boot-loader` backdrop, mounts the real loader,
+ * and emits `__bootLoader` calls to simulate the host. The driver is the source
+ * of truth — there is no React/Solid shadow of its progress.
+ */
+const LoaderHarness = () => {
+  let container!: HTMLDivElement;
+  let styleEl: HTMLStyleElement | undefined;
+  let dispose: (() => void) | undefined;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  const [sim, setSim] = createSignal<SimState>('creep');
+
+  const teardown = () => {
+    if (timer != null) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+    dispose?.();
+    dispose = undefined;
+  };
+
+  const mount = () => {
+    teardown();
+    // The loader treats its host element as the `#boot-loader` backdrop (styled
+    // by the inline CSS) and renders the disc + status into it — mirroring the
+    // static markup the plugin injects in production.
+    const backdrop = document.createElement('div');
+    backdrop.id = 'boot-loader';
+    backdrop.setAttribute('role', 'status');
+    backdrop.setAttribute('aria-live', 'polite');
+    backdrop.setAttribute('aria-label', 'Initializing');
+    container.appendChild(backdrop);
+    dispose = mountLoader(backdrop, { markSvg: COMPOSER_MARK, status: 'Loading…' });
+  };
+
+  const runCreepMessages = () => {
+    const phases = ['Loading framework…', 'Reading configuration…', 'Starting services…'];
+    let index = 0;
+    timer = setInterval(() => {
+      window.__bootLoader?.status({ humanized: phases[index] });
+      index += 1;
+      if (index >= phases.length && timer != null) {
+        clearInterval(timer);
+        timer = undefined;
+      }
+    }, 600);
+  };
+
+  const runProgress = () => {
+    let loaded = 0;
+    timer = setInterval(() => {
+      loaded += Math.min(1.5, 0.4 + (loaded % 3) * 0.3);
+      const fraction = Math.min(1, loaded / STORY_PLUGIN_COUNT);
+      window.__bootLoader?.progress(fraction);
+      window.__bootLoader?.status({
+        humanized: 'Loading plugins',
+        range: { index: Math.round(loaded), total: STORY_PLUGIN_COUNT },
+      });
+      if (loaded >= STORY_PLUGIN_COUNT && timer != null) {
+        clearInterval(timer);
+        timer = undefined;
+        window.__bootLoader?.status({ humanized: 'Starting Composer…' });
+        setSim('done');
+      }
+    }, STORY_TICK_MS);
+  };
+
+  const advance = () => {
+    if (sim() === 'creep') {
+      setSim('progress');
+      if (timer != null) {
+        clearInterval(timer);
+        timer = undefined;
+      }
+      runProgress();
+    } else if (sim() === 'progress' || sim() === 'done') {
+      // Play the dismissal outro, then re-mount for another run.
+      window.__bootLoader?.ready();
+      setSim('creep');
+      setTimeout(() => {
+        mount();
+        runCreepMessages();
+      }, 700);
+    }
+  };
+
+  onMount(() => {
+    styleEl = document.createElement('style');
+    styleEl.textContent = bootLoaderCss;
+    document.head.appendChild(styleEl);
+    mount();
+    runCreepMessages();
+  });
+
+  onCleanup(() => {
+    teardown();
+    styleEl?.remove();
+  });
+
+  return (
+    <>
+      {/* Float the controls above the loader's `z-index: 10` fixed backdrop. */}
+      <div
+        style={{
+          position: 'fixed',
+          top: '12px',
+          left: '12px',
+          'z-index': 9999,
+          display: 'flex',
+          gap: '12px',
+          'align-items': 'center',
+        }}
+      >
+        <button
+          type='button'
+          onClick={advance}
+          style={{
+            padding: '6px 14px',
+            'font-size': '13px',
+            'font-weight': '600',
+            color: '#fff',
+            background: '#017ab7',
+            border: 'none',
+            'border-radius': '6px',
+            cursor: 'pointer',
+            'box-shadow': '0 1px 3px rgba(0,0,0,0.25)',
+          }}
+        >
+          {sim() === 'creep' ? 'Start progress' : 'Finish + reset'}
+        </button>
+        <span style={{ 'font-family': 'ui-sans-serif, system-ui, sans-serif', 'font-size': '12px', color: '#888' }}>
+          {sim()}
+        </span>
+      </div>
+      <div ref={container as any} />
+    </>
+  );
+};
+
+const meta: Meta = {
+  title: 'sdk/app-framework/vite-plugin/BootLoader',
+  render: () => <LoaderHarness />,
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+export const Default: Story = {};

package/src/vite-plugin/boot-loader/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './loader';

package/src/vite-plugin/boot-loader/loader-app/Loader.tsx

@@ -0,0 +1,166 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Component, For, createEffect, createSignal, onCleanup, onMount } from 'solid-js';
+
+import { type LoaderStore } from './store';
+
+// Ring geometry in the SVG's `0 0 100 100` viewBox. The radius leaves a couple
+// of units of padding so the stroke, its round cap, and the end marker aren't
+// clipped at the viewBox edge.
+const RING_RADIUS = 48;
+const RING_CENTER = 50;
+// Leading-edge marker: a small dot drawn at the arc's head in an unmasked layer.
+const MARKER_RADIUS = 1; // viewBox units → ~3.8px on the 384px disc
+
+/**
+ * Read an element's *current animated* translateY (px) from its live transform
+ * matrix — the interpolated value mid-transition, not the last-written property.
+ * Used by the status FLIP so successive appends chain off the in-flight position
+ * instead of yanking the track back to a fixed invert target.
+ */
+const readTranslateY = (element: HTMLElement): number => {
+  const computed = getComputedStyle(element).transform;
+  if (!computed || computed === 'none') {
+    return 0;
+  }
+  const match = computed.match(/matrix.*\(([^)]+)\)/);
+  if (!match) {
+    return 0;
+  }
+  const values = match[1].split(',');
+  // 2D `matrix(a, b, c, d, tx, ty)` → ty at index 5; 3D `matrix3d(...)` → ty at 13.
+  if (values.length === 6) {
+    return Number.parseFloat(values[5]) || 0;
+  }
+  if (values.length === 16) {
+    return Number.parseFloat(values[13]) || 0;
+  }
+  return 0;
+};
+
+export type LoaderProps = {
+  /** Reactive source of truth for progress, status lines, and lifecycle phase. */
+  store: LoaderStore;
+  /** Inline SVG markup for the brand mark rendered inside the ring. */
+  markSvg?: string;
+};
+
+/**
+ * The boot loader, authored as a single Solid component — the one source of
+ * truth for the loader DOM. `bootLoaderPlugin` bundles this (Solid runtime
+ * inlined) into `index.html`; the storybook mounts the very same component, so
+ * the two can no longer drift. The DOM structure, ids, and classes mirror
+ * `boot-loader.css`.
+ *
+ * The full-screen backdrop (`#boot-loader`) is injected as static markup so it
+ * paints from CSS before this bundle executes; this component renders the disc
+ * and status log *into* that backdrop. The dismissal outro (fading `#boot-loader`)
+ * and its teardown are owned by {@link mountLoader}, which has the host element.
+ */
+export const Loader: Component<LoaderProps> = (props) => {
+  let trackRef: HTMLDivElement | undefined;
+  let previousCount = props.store.lines().length;
+
+  // FLIP-style slide on each appended line: snap the track down by one
+  // line-height (chained off any in-flight translate) with no transition, force
+  // a reflow, then animate back to translateY(0) so the new entry rises from
+  // below the bottom-anchored viewport. Range ticks (length unchanged) skip it.
+  createEffect(() => {
+    const count = props.store.lines().length;
+    const track = trackRef;
+    if (track && count > previousCount) {
+      const currentY = readTranslateY(track);
+      const lineHeight = track.lastElementChild?.getBoundingClientRect().height ?? 0;
+      track.style.transition = 'none';
+      track.style.transform = `translateY(${currentY + lineHeight}px)`;
+      void track.offsetHeight;
+      track.style.transition = '';
+      track.style.transform = 'translateY(0)';
+    }
+    previousCount = count;
+  });
+
+  // Eased display progress. A `<path>`'s `d` can't be CSS-transitioned, so the
+  // arc would snap on every store tick; instead we ease a displayed value toward
+  // the store's progress with a requestAnimationFrame loop (~per-frame lerp) and
+  // recompute the path each frame. This restores the compositor-smooth growth
+  // the old `transition: stroke-dashoffset` gave, while keeping the path +
+  // `marker-end` (the marker rides the arc's recomputed end automatically).
+  const [shown, setShown] = createSignal(props.store.progress());
+  let raf: number | undefined;
+  const animate = () => {
+    const target = props.store.progress();
+    const current = shown();
+    // Snap when within a hair to settle; otherwise lerp ~18% of the gap/frame.
+    const next = Math.abs(target - current) < 0.05 ? target : current + (target - current) * 0.18;
+    if (next !== current) {
+      setShown(next);
+    }
+    raf = requestAnimationFrame(animate);
+  };
+
+  onMount(() => {
+    raf = requestAnimationFrame(animate);
+  });
+
+  onCleanup(() => {
+    if (raf != null) {
+      cancelAnimationFrame(raf);
+    }
+  });
+
+  // Determinate ring as an SVG `<path>` arc: an anticlockwise sweep starting at
+  // 12 o'clock whose angle grows with the eased `shown()` progress. The sweep is
+  // capped just shy of a full turn so the single arc command never degenerates at
+  // 100%. The leading-edge dot is its `head` point, rendered separately (below) in
+  // an *unmasked* layer — drawing it via `marker-end` on this path would put it
+  // under the ring's conic fade mask, whose hard edge bisects the dot into a
+  // half-circle.
+  const arc = () => {
+    const fraction = Math.min(shown() / 100, 0.9999);
+    const sweep = fraction * 2 * Math.PI;
+    const start = -Math.PI / 2; // 12 o'clock
+    const end = start - sweep; // anticlockwise (decreasing angle)
+    const x0 = RING_CENTER + RING_RADIUS * Math.cos(start);
+    const y0 = RING_CENTER + RING_RADIUS * Math.sin(start);
+    const headX = RING_CENTER + RING_RADIUS * Math.cos(end);
+    const headY = RING_CENTER + RING_RADIUS * Math.sin(end);
+    const largeArc = sweep > Math.PI ? 1 : 0;
+    // sweep-flag 0 = anticlockwise (negative-angle) direction.
+    return { d: `M ${x0} ${y0} A ${RING_RADIUS} ${RING_RADIUS} 0 ${largeArc} 0 ${headX} ${headY}`, headX, headY };
+  };
+
+  // Once host-driven, the brand mark eases grayscale → colour and stays there.
+  const isHostDriven = () => props.store.phase() !== 'creep';
+
+  return (
+    <>
+      <div id='boot-loader-disc' data-host-driven={isHostDriven() ? '' : undefined}>
+        <svg
+          id='boot-loader-ring'
+          viewBox='0 0 100 100'
+          aria-hidden='true'
+          style={{ '--boot-loader-arc': String(shown()) }}
+        >
+          {shown() > 0 ? <path class='boot-loader-ring-progress' d={arc().d} /> : null}
+        </svg>
+        {/* Leading-edge dot in its own unmasked layer (see `arc()`), so the ring's fade mask
+            never clips it. Stacked over `#boot-loader-ring` via the disc grid. */}
+        {shown() > 0 ? (
+          <svg id='boot-loader-ring-head' viewBox='0 0 100 100' aria-hidden='true'>
+            <circle class='boot-loader-ring-marker' cx={arc().headX} cy={arc().headY} r={MARKER_RADIUS} />
+          </svg>
+        ) : null}
+        {props.markSvg ? <div id='boot-loader-mark' innerHTML={props.markSvg} /> : null}
+      </div>
+      <div id='boot-loader-status'>
+        <div id='boot-loader-status-fade' />
+        <div id='boot-loader-status-track' ref={trackRef}>
+          <For each={props.store.lines()}>{(line) => <div class='boot-loader-status-line'>{line.text}</div>}</For>
+        </div>
+      </div>
+    </>
+  );
+};

package/src/vite-plugin/boot-loader/loader-app/boot-loader.css

@@ -0,0 +1,311 @@
+/*
+ * Boot loader stylesheet — injected into the host's `<head>` by `bootLoaderPlugin`
+ * so the full-screen backdrop paints before any JS bundle is fetched. The Solid
+ * `Loader` renders the ring + status into the `#boot-loader` backdrop; this
+ * sheet styles both. Class/id names here form a contract with `Loader.tsx`,
+ * guarded by `BootLoader.solid-stories.tsx` (it mounts the real component).
+ */
+
+body {
+  margin: 0;
+  overflow: hidden;
+}
+
+/*
+ * Defaults match `@dxos/ui-theme`'s `--color-base-surface`, which resolves to
+ * Tailwind's `neutral-50` / `neutral-950` in light / dark mode respectively
+ * (see `packages/ui/ui-theme/src/css/theme/semantic.css`). Hosts can override
+ * with the `--boot-loader-bg-*` / `--boot-loader-fg-*` custom properties on
+ * `:root` if they need a different palette. Keeping the boot loader's
+ * background identical to the app's `body` eliminates the flash on handoff
+ * to the rendered React shell.
+ */
+#boot-loader {
+  --color-composer-100: rgb(5 40 61);
+  --color-composer-200: rgb(10 75 105);
+  --color-composer-300: rgb(1 122 183);
+  --color-composer-400: rgb(6 197 253);
+
+  /*
+   * Caps the disc / mark at the design pixel sizes on roomy viewports while
+   * shrinking proportionally on narrow ones (`vmin` follows the smaller of
+   * width / height) so neither the ring nor the mark crops on phones.
+   */
+  --boot-loader-disc-size: min(384px, 80vmin);
+  /*
+   * Match the React `Placeholder`'s logo box (`h-[300px] w-[300px]` at the
+   * `stage >= 1` keyframe) so the brand mark doesn't visibly jump size when
+   * the loader hands off — the responsive cap keeps the same 300/384 ratio
+   * (≈78%) at any viewport width.
+   */
+  --boot-loader-mark-size: min(300px, 62.5vmin);
+  --boot-loader-status-gap: 32px;
+
+  position: fixed;
+  inset: 0;
+  z-index: 10;
+  font-size: 13px;
+  font-family:
+    ui-sans-serif,
+    system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    'Segoe UI',
+    sans-serif;
+  /*
+   * Dismissal outro — `mountLoader` toggles `data-dismissing` on this element
+   * when the host calls `__bootLoader.ready()`; the loader cross-fades out over
+   * the real app shell rendering beneath it, and removes itself once this
+   * opacity transition completes (a fallback timer covers reduced-motion).
+   */
+  transition: opacity 500ms ease-out;
+}
+
+#boot-loader {
+  background: var(--boot-loader-bg-light, #fafafa);
+  color: var(--boot-loader-fg-light, #0a0a0a);
+  --boot-loader-accent: var(--boot-loader-accent-light, var(--color-composer-200));
+}
+
+@media (prefers-color-scheme: dark) {
+  #boot-loader {
+    background: var(--boot-loader-bg-dark, #0a0a0a);
+    color: var(--boot-loader-fg-dark, #fafafa);
+    --boot-loader-accent: var(--boot-loader-accent-dark, var(--color-composer-300));
+  }
+}
+
+#boot-loader[data-dismissing] {
+  opacity: 0;
+}
+
+/* Gently shrink the disc + mark as the loader fades, echoing the prior handoff. */
+#boot-loader[data-dismissing] #boot-loader-disc {
+  transform: translate(-50%, -50%) scale(0.92);
+  transition: transform 500ms ease-out;
+}
+
+/*
+ * Stack the ring (the SVG `#boot-loader-ring`) and the brand mark in the same
+ * grid cell so the mark sits centered inside the circle.
+ */
+#boot-loader-disc {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  display: grid;
+  place-items: center;
+  width: var(--boot-loader-disc-size);
+  height: var(--boot-loader-disc-size);
+  transform: translate(-50%, -50%);
+}
+
+#boot-loader-disc > * {
+  grid-column: 1;
+  grid-row: 1;
+}
+
+/*
+ * Default to grayscale so the mark reads as a quiet monochrome silhouette
+ * before any host-driven progress lands; the brand palette swaps in once
+ * `Loader.tsx` sets `data-host-driven` on the disc (the first
+ * `__bootLoader.progress()` call). Hover keeps a parallel reveal affordance
+ * for inspection in the storybook. The 1000ms ease lets the grayscale → color
+ * transition play through the activation phase rather than snapping.
+ */
+#boot-loader-mark {
+  width: var(--boot-loader-mark-size);
+  height: var(--boot-loader-mark-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  filter: grayscale(100%);
+  transition: filter 1000ms ease-out;
+}
+
+/*
+ * `grayscale(0%)` (identity) rather than `none` — `filter: none` changes
+ * the filter function list and most engines treat that as a discrete
+ * transition (snap, not ease). Keeping `grayscale(...)` on both sides of
+ * the rule lets the browser interpolate the percentage smoothly.
+ */
+#boot-loader-disc[data-host-driven] #boot-loader-mark,
+#boot-loader-mark:hover {
+  filter: grayscale(0%);
+}
+
+#boot-loader-mark svg {
+  width: 100%;
+  height: 100%;
+  /*
+   * The host SVG carries its own brand-palette fills, so we don't apply a
+   * `color` cascade here. SVGs that intentionally use `fill="currentColor"`
+   * still pick up the loader's text colour via `#boot-loader`'s `color`.
+   */
+}
+
+/*
+ * Circular determinate progress — a single SVG `<path>` arc that sweeps
+ * anticlockwise from 12 o'clock, its angle growing with progress (the `d` is
+ * recomputed by the component each tick). There is no static track;
+ * `stroke-linecap: round` rounds the trailing edge, and `marker-end` paints the
+ * leading-edge dot. Stroke width is in viewBox units so it scales with the disc.
+ */
+#boot-loader-ring {
+  width: var(--boot-loader-disc-size);
+  height: var(--boot-loader-disc-size);
+  overflow: visible;
+  /*
+   * Fade the arc linearly from the head (the marker, fully opaque) back to the
+   * tail (12 o'clock, transparent). A conic-gradient mask does this along the
+   * curve — `Loader.tsx` writes the eased progress into `--boot-loader-arc`
+   * (0–100), and the arc occupies the conic range `(100 - arc)%`…`100%`, so the
+   * head sits at `(100 - arc)%` (opaque) and the tail at `100%` (transparent).
+   * NOTE: We start at -1.16deg so that we don't mask the marker.
+   */
+  --boot-loader-arc: 0;
+  mask: conic-gradient(
+    from -1.16deg at 50% 50%,
+    transparent 0,
+    transparent calc((100 - var(--boot-loader-arc)) * 1%),
+    #000 calc((100 - var(--boot-loader-arc)) * 1%),
+    transparent 100%
+  );
+  -webkit-mask: conic-gradient(
+    from -1.16deg at 50% 50%,
+    transparent 0,
+    transparent calc((100 - var(--boot-loader-arc)) * 1%),
+    #000 calc((100 - var(--boot-loader-arc)) * 1%),
+    transparent 100%
+  );
+}
+
+/*
+ * The leading-edge dot's layer — same geometry as `#boot-loader-ring` but with no
+ * mask, so the dot renders as a full circle (the ring's conic fade mask would
+ * otherwise bisect it where it sits on the mask's transparent→opaque edge).
+ */
+#boot-loader-ring-head {
+  width: var(--boot-loader-disc-size);
+  height: var(--boot-loader-disc-size);
+  overflow: visible;
+}
+
+.boot-loader-ring-progress {
+  fill: none;
+  stroke: var(--boot-loader-accent);
+  /* viewBox units: ~1.9px on the 384px disc, scaling down on smaller viewports. */
+  stroke-width: 0.5;
+  opacity: 0.5;
+  stroke-linecap: butt;
+  overflow: visible;
+  /* Dashed line: dash + gap lengths in viewBox units (~2 units ≈ 7.7px @384px). */
+  /* stroke-dasharray: 2 1; */
+}
+
+/* The `marker-end` dot at the arc's leading edge. */
+.boot-loader-ring-marker {
+  fill: var(--boot-loader-accent);
+  stroke: none;
+  overflow: visible;
+  /* opacity: 0.5; */
+}
+
+#boot-loader-status {
+  position: absolute;
+  top: 50%;
+  left: 0;
+  right: 0;
+  /* 
+   * Sit just below the centered disc — half the disc plus the configured gap.
+   */
+  transform: translate(0, calc(var(--boot-loader-disc-size) / 2 + var(--boot-loader-status-gap)));
+  /*
+   * Slightly de-emphasised vs body text so the brand mark + ring stay the
+   * dominant focus, but high enough to remain legible on both light and dark
+   * backgrounds without a custom palette.
+   */
+  opacity: 0.5;
+  /*
+   * Terminal-style log viewport (3 rows at the default `line-height`) over
+   * a vertically-stacked track of every status the driver has emitted. The
+   * track is bottom-anchored via `justify-content: flex-end` so the newest
+   * line always sits on the last visible row, older lines stack above it,
+   * and anything that doesn't fit is clipped at the top by
+   * `overflow: hidden`. The driver runs a FLIP-style transform animation
+   * per append so each new line slides up from below the bottom edge —
+   * independent of any `scroll-behavior` smooth-scroll support, which
+   * Playwright/headless Chrome strips even from spec-compliant
+   * `scrollTo({ behavior: 'smooth' })` calls.
+   */
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-end;
+  height: 4.5em;
+  line-height: 1.5;
+  letter-spacing: 0.01em;
+  /* 
+   * Fixed-width digits so the `(i/n)` counter on range-bearing status
+   * updates ("Loading plugins (12/80)") doesn't jitter as the index
+   * ticks through different glyph widths. 
+   */
+  font-variant-numeric: tabular-nums;
+  text-align: center;
+  overflow: hidden;
+}
+
+#boot-loader-status-fade {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 32px;
+  background: linear-gradient(to bottom, var(--boot-loader-bg-light, #fafafa), transparent);
+  z-index: 1;
+}
+@media (prefers-color-scheme: dark) {
+  #boot-loader-status-fade {
+    background: linear-gradient(to bottom, var(--boot-loader-bg-dark, #0a0a0a), transparent);
+  }
+}
+
+#boot-loader-rss {
+  background: var(--boot-loader-bg-light, #fafafa);
+  text-wrap: balance;
+}
+@media (prefers-color-scheme: dark) {
+  #boot-loader-rss {
+    background: var(--boot-loader-bg-dark, #0a0a0a);
+  }
+}
+
+/*
+ * Track of every appended `.boot-loader-status-line`.
+ */
+#boot-loader-status-track {
+  display: flex;
+  flex-direction: column;
+  /*
+   * Resting transform is `translateY(0)` — the bottom-anchored flex parent
+   * already positions the newest line on the last visible row. On each append
+   * `Loader.tsx` runs a one-shot FLIP: snap to `translateY(<lineHeight>px)` with
+   * no transition (placing the new line just below the viewport), force a
+   * reflow, then animate back to 0 so the track rises by one line-height and the
+   * new entry slides up into the bottom row.
+   */
+  transform: translateY(0);
+  transition: transform 500ms ease-out;
+}
+
+/* Honour reduced-motion preferences explicitly — `transition` doesn't auto-respect it. */
+@media (prefers-reduced-motion: reduce) {
+  #boot-loader-status-track {
+    transition: none;
+  }
+}
+
+.boot-loader-status-line {
+  flex: 0 0 auto;
+  height: 1.5em;
+  white-space: nowrap;
+}