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

package/src/ui/hooks/useLoading.tsx

@@ -0,0 +1,76 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useEffect, useRef, useState } from 'react';
+
+export enum LoadingState {
+  Loading = 0,
+  FadeIn = 1,
+  FadeOut = 2,
+  Done = 3,
+}
+
+/**
+ * To avoid "flashing" the placeholder, we wait a period of time before starting the loading animation.
+ * If loading completes during this time the placehoder is not shown, otherwise is it displayed for a minimum period of time.
+ *
+ * States:
+ * 0: Loading   - Wait for a period of time before starting the loading animation.
+ * 1: Fade-in   - Display a loading animation.
+ * 2: Fade-out  - Fade out the loading animation.
+ * 3: Done      - Remove the placeholder.
+ */
+export const useLoading = (ready: boolean, debounce = 0) => {
+  const [stage, setStage] = useState<LoadingState>(LoadingState.Loading);
+  // Mirror `ready` into a ref so the interval's `setStage` callback can read
+  // the latest value without depending on the effect re-running. The pure
+  // closure-capture pattern (with `ready` in deps) sticks the FSM at
+  // `FadeIn` whenever HMR doesn't propagate the dep change end-to-end —
+  // a ref sidesteps that entirely and fires the read on every tick.
+  const readyRef = useRef(ready);
+  readyRef.current = ready;
+
+  useEffect(() => {
+    if (!debounce) {
+      return;
+    }
+
+    const i = setInterval(() => {
+      setStage((stage) => {
+        const isReady = readyRef.current;
+        switch (stage) {
+          case LoadingState.Loading: {
+            if (!isReady) {
+              return LoadingState.FadeIn;
+            }
+            clearInterval(i);
+            return LoadingState.Done;
+          }
+
+          case LoadingState.FadeIn: {
+            if (isReady) {
+              return LoadingState.FadeOut;
+            }
+            break;
+          }
+
+          case LoadingState.FadeOut: {
+            clearInterval(i);
+            return LoadingState.Done;
+          }
+        }
+
+        return stage;
+      });
+    }, debounce);
+
+    return () => clearInterval(i);
+  }, [debounce]);
+
+  if (!debounce) {
+    return ready ? LoadingState.Done : LoadingState.Loading;
+  }
+
+  return stage;
+};

package/src/ui/hooks/useProcessManagerRuntime.ts

@@ -0,0 +1,78 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { type DependencyList, use, useCallback, useMemo } from 'react';
+
+import { Operation, ServiceResolver } from '@dxos/compute';
+import { EffectEx } from '@dxos/effect';
+import type { SpaceId } from '@dxos/keys';
+
+import { Capabilities } from '../../common';
+import { useCapability } from './useCapabilities';
+
+/**
+ * Resolve the shared {@link Capabilities.ProcessManagerRuntime} from the plugin context.
+ */
+export const useProcessManagerRuntime = (): Capabilities.ProcessManagerRuntime =>
+  useCapability(Capabilities.ProcessManagerRuntime);
+
+/**
+ * Build a callback that runs an effect on the {@link Capabilities.ProcessManagerRuntime}
+ * with space-scoped services resolved via {@link ServiceResolver.provide}.
+ *
+ * The `tags` tuple must list every service the effect requires (beyond the
+ * fixed {@link Capabilities.ProcessManagerRuntimeServices}); these services are
+ * resolved for the given `spaceId` through the runtime's service resolver.
+ *
+ * Nested `Operation.invoke` / `Operation.schedule` calls within the effect
+ * inherit `spaceId` as a default {@link Operation.InvokeOptions} so that
+ * spawned operation processes have a space context (and therefore can resolve
+ * space-scoped services like `Database.Service`) without each call site having
+ * to thread the id through manually.
+ */
+export const useSpaceCallback = <const Tags extends readonly Context.Tag<any, any>[], T>(
+  spaceId: SpaceId | undefined,
+  tags: Tags,
+  fn: () => Effect.Effect<T, any, Context.Tag.Identifier<Tags[number]> | Capabilities.ProcessManagerRuntimeServices>,
+  deps?: DependencyList,
+): (() => Promise<T>) => {
+  const runtime = useProcessManagerRuntime();
+  return useCallback(() => {
+    if (spaceId === undefined) {
+      throw new TypeError('Space not provided to useSpaceCallback');
+    }
+    const layer = Layer.merge(
+      ServiceResolver.provide({ space: spaceId }, ...tags),
+      Operation.withInvocationOptions({ spaceId }),
+    );
+    return runtime.runPromise(fn().pipe(Effect.provide(layer)) as Effect.Effect<T, any, any>);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [runtime, spaceId, ...(deps ?? [])]);
+};
+
+/**
+ * Suspensefully resolve a single space-scoped service via the
+ * {@link Capabilities.ProcessManagerRuntime}'s service resolver.
+ */
+export const useSpaceService = <T extends Context.Tag<any, any>>(
+  tag: T,
+  spaceId: SpaceId | undefined,
+): Context.Tag.Service<T> | undefined => {
+  const runtime = useProcessManagerRuntime();
+  const promise = useMemo(() => {
+    if (spaceId === undefined) {
+      return undefined;
+    }
+    const layer = ServiceResolver.provide({ space: spaceId }, tag);
+    const effect = Effect.flatMap(tag, (service) => Effect.succeed(service)).pipe(Effect.provide(layer));
+    return runtime.runPromiseExit(effect as Effect.Effect<Context.Tag.Service<T>, any, any>);
+  }, [runtime, spaceId, tag]);
+  if (!promise) {
+    return undefined;
+  }
+  return EffectEx.unwrapExit(use(promise));
+};

package/src/ui/hooks/useSettingsState.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom, RegistryContext, useAtomValue } from '@effect-atom/atom-react';
+import { useCallback, useContext } from 'react';
+
+/**
+ * Hook to read and update a settings atom.
+ * Returns the current value and an update function.
+ */
+export const useSettingsState = <T>(
+  atom: Atom.Writable<T>,
+): { settings: T; updateSettings: (fn: (current: T) => T) => void } => {
+  const registry = useContext(RegistryContext);
+  const settings = useAtomValue(atom);
+
+  const updateSettings = useCallback(
+    (fn: (current: T) => T) => {
+      registry.set(atom, fn(registry.get(atom)));
+    },
+    [registry, atom],
+  );
+
+  return { settings, updateSettings };
+};

package/src/ui/hooks/useSurface.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useContext } from 'react';
+
+import { raise } from '@dxos/debug';
+
+import { Surface } from '../components';
+
+export const useSurface = (): Surface.Context => {
+  return useContext(Surface.Context) ?? raise(new Error('Missing SurfaceContext'));
+};

package/src/ui/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './components';
+export * from './hooks';

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