@dxos/app-framework 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/vite-plugin/boot-loader/loader-app/store.ts

@@ -0,0 +1,149 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Accessor, createSignal } from 'solid-js';
+
+import { type StatusPayload } from './types';
+
+//
+// Creep tuning. The ring auto-creeps toward a moving ceiling so a long
+// activation silence never reads as a frozen disc. See the original
+// hand-written driver for the rationale behind each constant.
+//
+
+/** Creep timer cadence, in milliseconds. */
+export const CREEP_TICK_MS = 100;
+/** State-1 ease rate — a gentle "we're alive" hint before real progress lands. */
+export const STATE_1_RATE = 0.05;
+/** State-1 asymptote (percent) the creep eases toward before host progress. */
+export const STATE_1_ASYMPTOTE = 40;
+/** State-2 ease rate — bridges the gap between sparse host `progress()` calls. */
+export const STATE_2_RATE = 0.05;
+/** State-2 lead (percent) the ceiling sits ahead of the last host value. */
+export const STATE_2_BUMP = 15;
+/** Hard ceiling the auto-creep never crosses (host must drive the rest). */
+export const ABSOLUTE_CEILING = 90;
+
+/** Loader lifecycle phase. */
+export type Phase = 'creep' | 'host' | 'dismissing';
+
+/** A single rendered status line; `id` keys the `<For>` and survives in-place range ticks. */
+export type StatusLine = {
+  id: number;
+  text: string;
+  event?: string;
+  module?: string;
+};
+
+/**
+ * Asymptotic ease — `next = raw + (ceiling - raw) * rate`, clamped so it never
+ * overshoots (or regresses past) the ceiling. Pure; unit-tested.
+ */
+export const easeToward = (raw: number, ceiling: number, rate: number): number =>
+  raw >= ceiling - 0.1 ? raw : raw + (ceiling - raw) * rate;
+
+/**
+ * Clamp a host-supplied fraction to a percent in [0, 100]. Invalid / negative /
+ * non-finite values collapse to 0 rather than poisoning the CSS var. Pure;
+ * unit-tested.
+ */
+export const clampPercent = (fraction?: number): number =>
+  typeof fraction !== 'number' || !Number.isFinite(fraction) || fraction < 0 ? 0 : Math.min(1, fraction) * 100;
+
+/** Display text for a payload — appends the `(index/total)` suffix when a range is present. */
+export const displayText = (payload: StatusPayload): string =>
+  payload.range ? `${payload.humanized} (${payload.range.index}/${payload.range.total})` : payload.humanized;
+
+/**
+ * Reactive loader store — owns the progress percent, the status-line log, and
+ * the lifecycle phase, plus the auto-creep timer. All DOM-free, so the creep
+ * math and status reduction are testable as plain functions; `Loader.tsx` binds
+ * the accessors to the DOM and `bridge.ts` wraps the mutators as the imperative
+ * `window.__bootLoader` facade.
+ */
+export type LoaderStore = {
+  /** Progress as a percent in [0, 100] (the CSS `--boot-loader-bar-progress` value). */
+  progress: Accessor<number>;
+  /** Appended status lines, newest last. */
+  lines: Accessor<StatusLine[]>;
+  /** Current lifecycle phase. */
+  phase: Accessor<Phase>;
+  /** Apply a status update (append, or replace-in-place for range ticks). */
+  pushStatus: (payload: StatusPayload) => void;
+  /** Enter host-driven progress with `fraction` ∈ [0, 1]; never regresses. */
+  setProgress: (fraction?: number) => void;
+  /** Snap to 100%, stop the creep, and enter the dismissing phase. */
+  ready: () => void;
+  /** Stop the creep timer (call on teardown). */
+  dispose: () => void;
+};
+
+export const createLoaderStore = (initialStatus?: string): LoaderStore => {
+  const [progress, setProgressPct] = createSignal(0);
+  const [lines, setLines] = createSignal<StatusLine[]>(initialStatus ? [{ id: 0, text: initialStatus }] : []);
+  const [phase, setPhase] = createSignal<Phase>('creep');
+
+  let creepCeiling = STATE_1_ASYMPTOTE;
+  let creepRate = STATE_1_RATE;
+  let nextId = initialStatus ? 1 : 0;
+  let timer: ReturnType<typeof setInterval> | null = null;
+
+  const startCreep = (): void => {
+    if (timer == null) {
+      timer = setInterval(() => setProgressPct((raw) => easeToward(raw, creepCeiling, creepRate)), CREEP_TICK_MS);
+    }
+  };
+
+  const stopCreep = (): void => {
+    if (timer != null) {
+      clearInterval(timer);
+      timer = null;
+    }
+  };
+
+  const pushStatus = (payload: StatusPayload): void => {
+    const text = displayText(payload);
+    setLines((current) => {
+      const previous = current.at(-1);
+      // Dedup back-to-back identical transitions (same text + structured fields).
+      if (
+        previous &&
+        previous.text === text &&
+        (previous.event ?? null) === (payload.event ?? null) &&
+        (previous.module ?? null) === (payload.module ?? null)
+      ) {
+        return current;
+      }
+      // Range tick — replace the current line in place rather than appending,
+      // so a counted phase produces one entry with an updating suffix.
+      if (payload.range && previous) {
+        return [...current.slice(0, -1), { ...previous, text }];
+      }
+      return [...current, { id: nextId++, text, event: payload.event, module: payload.module }];
+    });
+  };
+
+  const setProgress = (fraction?: number): void => {
+    setPhase('host');
+    const pct = clampPercent(fraction);
+    // The ring never regresses: hold the current value if the host reports lower.
+    setProgressPct((current) => Math.max(current, pct));
+    // Switch the creep to its state-2 cadence and lead the host value by a bump.
+    creepRate = STATE_2_RATE;
+    creepCeiling = Math.min(Math.max(creepCeiling, pct + STATE_2_BUMP), ABSOLUTE_CEILING);
+    startCreep();
+  };
+
+  const ready = (): void => {
+    stopCreep();
+    setProgressPct(100);
+    setPhase('dismissing');
+  };
+
+  const dispose = (): void => stopCreep();
+
+  startCreep();
+
+  return { progress, lines, phase, pushStatus, setProgress, ready, dispose };
+};

package/src/vite-plugin/boot-loader/loader-app/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js",
+    "strict": false,
+    "noEmit": true,
+    "composite": false
+  },
+  "include": ["."]
+}

package/src/vite-plugin/boot-loader/loader-app/types.ts

@@ -0,0 +1,78 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * Status payload accepted by `window.__bootLoader.status(...)`. The caller owns
+ * formatting — `humanized` is the exact text rendered — while `event` / `module`
+ * carry the structured activation ids for the boot trace, and `range` drives an
+ * in-place `(index/total)` counter for long counted phases.
+ */
+export type StatusPayload = {
+  /**
+   * Raw activation event key (e.g. `dxos.org/plugin/observability/activate`)
+   * when the transition is event-level.
+   */
+  event?: string;
+
+  /**
+   * Raw module id (e.g. `org.dxos.plugin.observability.module.ReactSurface`)
+   * when the transition is module-level.
+   */
+  module?: string;
+
+  /** Exact text to display (e.g. "Activating Observability: react-surface"). */
+  humanized: string;
+
+  /**
+   * Optional `(index/total)` tick. When present the loader replaces the current
+   * line in place ("Loading plugins (12/80)") instead of appending a new entry —
+   * keeps the visible log compact during long counted phases.
+   */
+  range?: { index: number; total: number };
+};
+
+/**
+ * Imperative facade exposed on `window.__bootLoader`, installed by the inlined
+ * loader bundle and driven by the host app (the React relay forwards `useApp`'s
+ * startup progress through it).
+ */
+export type BootLoaderApi = {
+  /** Update the visible status line. */
+  status: (payload: StatusPayload) => void;
+  /** Enter host-driven progress — `fraction` ∈ [0, 1]. */
+  progress: (fraction?: number) => void;
+  /** Play the dismissal outro, then remove the loader DOM (graceful path). */
+  ready: () => void;
+  /** Remove the loader DOM immediately (fast-load backstop / terminal). */
+  dismiss: () => void;
+};
+
+/**
+ * Config baked into `index.html` by `bootLoaderPlugin` ahead of the loader
+ * bundle, so the compiled app stays static (compiled once, independent of the
+ * host's brand mark / initial status).
+ */
+export type BootLoaderConfig = {
+  /**
+   * Id of the static backdrop element the plugin injects and the loader mounts
+   * into — the single coupling between `transformIndexHtml` and the app. The
+   * plugin owns the authoritative value and passes it here so `entry.tsx` reads
+   * it rather than hardcoding (the CSS selector mirrors it — see `boot-loader.css`).
+   */
+  rootId?: string;
+  /** Inline SVG markup for the brand mark rendered inside the ring. */
+  markSvg?: string;
+  /** Initial status text rendered before the host fires its first `status(...)`. */
+  status?: string;
+};
+
+/** Fallback backdrop id when no config is present (kept in sync with `loader.ts` + the CSS). */
+export const DEFAULT_ROOT_ID = 'boot-loader';
+
+declare global {
+  interface Window {
+    __bootLoader?: BootLoaderApi;
+    __BOOT_LOADER_CONFIG__?: BootLoaderConfig;
+  }
+}

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

@@ -0,0 +1,204 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @ts-ignore — @types/babel__core present transitively but not declared here.
+import * as babel from '@babel/core';
+// @ts-ignore — @babel/preset-typescript ships no .d.ts.
+import babelPresetTypeScript from '@babel/preset-typescript';
+// @ts-ignore — babel-preset-solid ships no .d.ts.
+import babelPresetSolid from 'babel-preset-solid';
+import { build, type Plugin as EsbuildPlugin } from 'esbuild';
+import { basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { type Plugin } from 'vite';
+
+import css from './loader-app/boot-loader.css?raw';
+// The loader-app Solid sources are inlined as raw text (never parsed by
+// dx-compile — app-framework is a React package, so its build can't compile
+// Solid JSX). They are compiled to a self-contained browser IIFE at the
+// consuming app's build time by {@link compileLoaderBundle} below.
+import bridgeSrc from './loader-app/bridge.ts?raw';
+import entrySrc from './loader-app/entry.tsx?raw';
+import loaderSrc from './loader-app/Loader.tsx?raw';
+import mountSrc from './loader-app/mount.tsx?raw';
+import storeSrc from './loader-app/store.ts?raw';
+import typesSrc from './loader-app/types.ts?raw';
+
+/**
+ * Options for {@link bootLoaderPlugin}.
+ */
+export type BootLoaderOptions = {
+  /**
+   * Initial status text rendered by the loader (replaced via
+   * `window.__bootLoader.status(...)` once the host starts firing phase callbacks).
+   */
+  status?: string;
+
+  /**
+   * Inline SVG markup for an optional brand mark rendered inside the progress
+   * ring. The mark renders at full opacity with whatever fills the SVG declares,
+   * so pass a colour-palette logo for the strongest visual identity. SVGs that
+   * use `fill="currentColor"` still inherit the loader's `prefers-color-scheme`
+   * text colour. Leave empty/undefined to render only the ring.
+   */
+  markSvg?: string;
+
+  /**
+   * HTML entry filenames to inject the loader into. Defaults to `index.html` only
+   * so auxiliary pages (`recovery.html`, `reset.html`, etc.) stay unobstructed.
+   */
+  include?: string[];
+};
+
+const VIRTUAL_NS = 'boot-loader-app';
+
+// Relative-import graph of the loader-app, keyed by module name (no extension).
+// `tsx` modules carry JSX (compiled via `babel-preset-solid`); `ts` modules are
+// type-stripped only. `solid-js` imports introduced by the Solid transform
+// resolve from `node_modules` against `resolveDir`.
+const MODULES: Record<string, { contents: string; tsx: boolean }> = {
+  entry: { contents: entrySrc, tsx: true },
+  mount: { contents: mountSrc, tsx: true },
+  Loader: { contents: loaderSrc, tsx: true },
+  bridge: { contents: bridgeSrc, tsx: false },
+  store: { contents: storeSrc, tsx: false },
+  types: { contents: typesSrc, tsx: false },
+};
+
+// Walk up from the compiled plugin to find a `node_modules` containing
+// `solid-js` (a dependency of this package). Used as esbuild's `resolveDir`.
+const resolveDir = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Compile the loader-app from its inlined raw sources into a single
+ * self-contained IIFE (Solid runtime bundled in) suitable for inlining into
+ * `index.html`. Mirrors dx-compile's Solid pipeline: `@babel/preset-typescript`
+ * strips types, then `babel-preset-solid` compiles JSX into reactive primitives.
+ */
+const compileLoaderBundle = async (): Promise<string> => {
+  const virtualSolid = (): EsbuildPlugin => ({
+    name: 'boot-loader-app-virtual',
+    setup: (esbuild) => {
+      esbuild.onResolve({ filter: /^\.\// }, (args) => {
+        const name = args.path.replace(/^\.\//, '').replace(/\.(tsx?|jsx?)$/, '');
+        return name in MODULES ? { path: name, namespace: VIRTUAL_NS } : undefined;
+      });
+
+      esbuild.onLoad({ filter: /.*/, namespace: VIRTUAL_NS }, async (args) => {
+        const module = MODULES[args.path];
+        const result = await babel.transformAsync(module.contents, {
+          filename: `${args.path}.${module.tsx ? 'tsx' : 'ts'}`,
+          babelrc: false,
+          configFile: false,
+          // Presets run last-to-first: TS strips first, then Solid sees plain JSX.
+          presets: [
+            [babelPresetSolid, { generate: 'dom', hydratable: false }],
+            [babelPresetTypeScript, { allowDeclareFields: true }],
+          ],
+        });
+        if (!result?.code) {
+          throw new Error(`babel-preset-solid returned no code for ${args.path}`);
+        }
+        return { contents: result.code, loader: 'js', resolveDir };
+      });
+    },
+  });
+
+  const result = await build({
+    stdin: { contents: "import './entry';", loader: 'ts', resolveDir, sourcefile: 'boot-loader-entry.ts' },
+    bundle: true,
+    format: 'iife',
+    platform: 'browser',
+    target: 'es2020',
+    minify: true,
+    write: false,
+    legalComments: 'none',
+    define: { 'process.env.NODE_ENV': '"production"' },
+    plugins: [virtualSolid()],
+  });
+
+  return result.outputFiles[0].text;
+};
+
+let bundlePromise: Promise<string> | undefined;
+const getLoaderBundle = (): Promise<string> => (bundlePromise ??= compileLoaderBundle());
+
+/**
+ * Vite plugin that injects a Solid "boot loader" app into the host app's
+ * `index.html`.
+ *
+ * The full-screen backdrop paints on the very first frame from an inline
+ * `<style>` (before any JS bundle is fetched), so the user sees the loading
+ * surface immediately on cold load instead of a blank document. A compiled,
+ * self-contained Solid IIFE — inlined ahead of the app bundle — then renders
+ * the determinate progress ring + status log into that backdrop and exposes the
+ * host-facing driver on `window.__bootLoader`.
+ *
+ * The host app drives the loader (the React relay forwards `useApp`'s startup
+ * progress):
+ * - `window.__bootLoader.status(payload)` updates the status line per phase.
+ * - `window.__bootLoader.progress(fraction)` grows the determinate ring (0–1).
+ * - `window.__bootLoader.ready()` plays the dismissal outro, then self-removes.
+ * - `window.__bootLoader.dismiss()` removes the loader immediately (fast path).
+ *
+ * Inject order (all at the start of `<body>`, except the stylesheet):
+ * - `<style>` → `<head>` (parses before any bundled stylesheet).
+ * - `<div id="boot-loader">` → the static backdrop the CSS styles instantly.
+ * - inline `<script>` config (`window.__BOOT_LOADER_CONFIG__`) → before the bundle.
+ * - inline `<script>` loader bundle → renders the Solid app into the backdrop.
+ *
+ * Keeping the loader a sibling of `#root` (rather than a child) means
+ * `createRoot(document.getElementById('root')).render(...)` does not fight the
+ * loader for ownership; the framework explicitly dismisses after the first
+ * React commit for a deterministic handoff.
+ *
+ * Color tokens are exposed as CSS custom properties (`--boot-loader-bg-light`,
+ * etc.) in `boot-loader.css`, so consumers can override them at the document
+ * level without re-parameterizing this plugin.
+ */
+export const bootLoaderPlugin = ({ status, markSvg, include = ['index.html'] }: BootLoaderOptions = {}): Plugin => {
+  return {
+    name: 'app-framework:boot-loader',
+    async transformIndexHtml(_html, ctx) {
+      const filename = basename(ctx.filename ?? 'index.html');
+      if (!include.includes(filename)) {
+        return;
+      }
+
+      const bundle = await getLoaderBundle();
+      // Authoritative backdrop id: injected here, passed to the bundle via
+      // config (so `entry.tsx` reads it), and mirrored by the CSS selector in
+      // `boot-loader.css`. The inner DOM ↔ CSS contract is guarded by the story.
+      const rootId = 'boot-loader';
+      return [
+        {
+          tag: 'style',
+          injectTo: 'head',
+          children: css,
+        },
+        {
+          tag: 'div',
+          injectTo: 'body-prepend',
+          attrs: {
+            id: rootId,
+            role: 'status',
+            'aria-live': 'polite',
+            'aria-label': 'Initializing',
+          },
+          children: '',
+        },
+        {
+          tag: 'script',
+          injectTo: 'body-prepend',
+          children: `window.__BOOT_LOADER_CONFIG__=${JSON.stringify({ rootId, markSvg, status })};`,
+        },
+        {
+          tag: 'script',
+          injectTo: 'body-prepend',
+          children: bundle,
+        },
+      ];
+    },
+  };
+};