npm - @dxos/app-framework - Versions diffs - 0.8.4-main.ead640a → 0.8.4-main.effb148878 - Mend

@dxos/app-framework 0.8.4-main.ead640a → 0.8.4-main.effb148878

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (572) hide show

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

@@ -0,0 +1,123 @@
+//
+// Copyright 2026 DXOS.org
+//
+import { type Plugin } from 'vite';
+import css from './boot-loader.css?raw';
+import driverScript from './boot-loader.js?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 above the progress bar.
+   * 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 bar.
+   */
+  markSvg?: string;
+};
+/**
+ * Vite plugin that injects a tiny native-DOM "boot loader" into the host app's
+ * `index.html`.
+ *
+ * The loader paints on the very first frame, before any JS bundle is fetched —
+ * so the user sees something immediately on cold load instead of staring at a
+ * blank document while the compiled module graph is parsed. The brand mark
+ * sits centred inside a thin determinate progress ring; both layers are
+ * composited so the ring's fill stays visually smooth even while the JS main
+ * thread is busy.
+ *
+ * The host app drives the loader from `main.tsx`:
+ * - `window.__bootLoader.status(text)` updates the status line per phase.
+ * - `window.__bootLoader.progress(fraction)` grows the determinate ring (0–1).
+ * - `window.__bootLoader.dismiss()` removes the loader once React has mounted.
+ *
+ * Inject order:
+ * - `<style>` → `<head>` (parses before any bundled stylesheet).
+ * - `<div id="boot-loader">…</div>` → start of `<body>` (sibling of `#root`).
+ * - inline `<script>` defining `window.__bootLoader` → start of `<body>`.
+ *
+ * Keeping the loader as a sibling of `#root` (rather than a child of it) means
+ * `createRoot(document.getElementById('root')).render(...)` does not fight the
+ * loader for ownership; the host explicitly calls `dismiss()` after the first
+ * React commit, which gives a deterministic handoff.
+ *
+ * Color tokens are exposed as CSS custom properties (`--boot-loader-bg-light`,
+ * `--boot-loader-bg-dark`, etc.) defined in `boot-loader.css`, so consumers can
+ * override them at the document level without us re-parameterizing this plugin.
+ */
+export const bootLoaderPlugin = ({ status, markSvg }: BootLoaderOptions = {}): Plugin => {
+  return {
+    name: 'app-framework:boot-loader',
+    transformIndexHtml() {
+      // The mark slot uses `children: <raw-svg>` (vite emits string children as
+      // raw HTML, not text-escaped) so the host can pass an SVG file's contents
+      // straight through. The mark and ring are siblings inside `#boot-loader-disc`
+      // so CSS grid-stacking can centre the mark inside the ring without the ring's
+      // radial-gradient mask clipping the SVG.
+      const markChildren = markSvg ? [{ tag: 'div', attrs: { id: 'boot-loader-mark' }, children: markSvg }] : [];
+      return [
+        {
+          tag: 'style',
+          injectTo: 'head',
+          children: css,
+        },
+        {
+          tag: 'div',
+          injectTo: 'body-prepend',
+          attrs: {
+            id: 'boot-loader',
+            role: 'status',
+            'aria-live': 'polite',
+            'aria-label': 'Initializing',
+          },
+          children: [
+            {
+              tag: 'div',
+              attrs: { id: 'boot-loader-disc' },
+              children: [
+                { tag: 'div', attrs: { id: 'boot-loader-bar' }, children: '' },
+                { tag: 'div', attrs: { id: 'boot-loader-dot' }, children: '' },
+                ...markChildren,
+              ],
+            },
+            {
+              tag: 'div',
+              attrs: { id: 'boot-loader-status' },
+              children: [
+                {
+                  tag: 'div',
+                  attrs: { id: 'boot-loader-status-fade' },
+                },
+                {
+                  tag: 'div',
+                  attrs: { id: 'boot-loader-status-track' },
+                  children: status
+                    ? [{ tag: 'div', attrs: { class: 'boot-loader-status-line' }, children: status }]
+                    : [],
+                },
+              ],
+            },
+          ],
+        },
+        {
+          tag: 'script',
+          injectTo: 'body-prepend',
+          children: driverScript,
+        },
+      ];
+    },
+  };
+};

package/src/vite-plugin/composer/index.ts ADDED Viewed

@@ -0,0 +1,306 @@
+//
+// Copyright 2026 DXOS.org
+//
+import { type Plugin as VitePlugin } from 'vite';
+import { PLUGIN_DEV_SERVER_PORT } from '../../core';
+import { type BuildMeta, ENTRY_FILENAME, MANIFEST_ASSET_NAME, serializeManifest } from '../manifest';
+import { DEFAULT_PACKAGES, isSharedPackage } from '../packages';
+export { ENTRY_FILENAME, MANIFEST_ASSET_NAME, serializeManifest };
+export type { BuildMeta };
+const JSX_DEV_RUNTIME = 'react/jsx-dev-runtime';
+/**
+ * Whether an import should be externalized by the plugin bundle.
+ * Uses the shared-package predicate directly so plugins automatically pick up any
+ * new `@dxos/*` (non-plugin) package the host provides, without a code change here.
+ */
+const isExternal = (id: string) => id !== JSX_DEV_RUNTIME && isSharedPackage(id);
+/**
+ * Banner injected at the top of every plugin bundle.
+ *
+ * Why: rolldown emits ESM `import` for externalized deps, but when a *bundled* module
+ * is CJS and contains `require('react')` (or any other external), rolldown keeps the
+ * `require(...)` call in the output and relies on a runtime `require` function. The
+ * browser doesn't have `require`, so rolldown's fallback shim throws:
+ * `Calling `require` for "react" in an environment that doesn't expose the `require`
+ *  function`.
+ *
+ * The full dependency graphs of non-trivial plugins unavoidably drag in CJS-only
+ * helpers (`use-sync-external-store` via xstate / zustand / preact-signals / … ),
+ * and waiting for every one of those packages to ship ESM isn't realistic. Instead
+ * we install a tiny module-local `require` at the top of the bundle that looks up
+ * a handful of well-known host-provided modules by name and returns their already
+ * ESM-imported namespaces. Rolldown's own shim honours an existing `require`
+ * before falling through to the throw path, so this entirely removes the runtime
+ * error without changing how externalization itself works.
+ *
+ * Keep the list aligned with the externals that CJS code actually reaches for;
+ * adding entries here is safe (unused imports get tree-shaken), but the list is
+ * deliberately small to keep the banner noise-free.
+ */
+const REQUIRE_SHIM_BANNER = [
+  '// --- composer-plugin: CJS require shim ---',
+  '// See @dxos/app-framework/vite-plugin/composer-plugin.ts for rationale.',
+  "import * as __composerReact from 'react';",
+  "import * as __composerReactDom from 'react-dom';",
+  "import * as __composerReactJsxRuntime from 'react/jsx-runtime';",
+  'const __composerRequireShim = new Map([',
+  "  ['react', __composerReact.default ?? __composerReact],",
+  "  ['react-dom', __composerReactDom.default ?? __composerReactDom],",
+  "  ['react/jsx-runtime', __composerReactJsxRuntime],",
+  ']);',
+  "// Module-local binding: rolldown's CJS fallback does a `typeof require` check",
+  '// and uses whichever `require` is in lexical scope. Declaring this as `const`',
+  "// (instead of `globalThis.require ??=`) keeps each bundle's shim isolated from",
+  '// the host page and from other plugins sharing the window.',
+  'const require = (id) => {',
+  '  if (__composerRequireShim.has(id)) return __composerRequireShim.get(id);',
+  "  throw new Error('composer-plugin: unsupported CJS require at runtime: ' + id);",
+  '};',
+  '// --- end CJS require shim ---',
+].join('\n');
+export type ComposerPluginOptions = {
+  /** Entry point for the plugin bundle. Defaults to `src/plugin.tsx`. */
+  entry?: string;
+  /** Dev server port. Defaults to {@link PLUGIN_DEV_SERVER_PORT}. */
+  port?: number;
+  /**
+   * Plugin metadata. When provided, a `manifest.json` asset is emitted alongside the bundle
+   * listing every emitted file. The host fetches this manifest at install time and persists
+   * the declared assets in its offline cache so the plugin works without network. The bundle's
+   * entry module is always written as {@link ENTRY_FILENAME} (`index.mjs`).
+   */
+  meta?: BuildMeta;
+};
+/**
+ * Vite plugin for **external Composer plugin projects**. Configures the build to produce
+ * an ESM bundle that externalizes all framework dependencies, which the Composer host app
+ * provides at runtime via import map.
+ *
+ * Handles:
+ * 1. Build config — lib mode entry point, ES format output, rollup externals, code-split chunks.
+ * 2. Dev externalization — marks shared deps as external during `vite serve` and strips
+ *    the `/@id/` prefix that Vite's import analysis adds to external bare specifiers.
+ * 3. JSX dev runtime shim — bridges `react/jsx-dev-runtime` (used by React refresh in dev)
+ *    to `react/jsx-runtime` (which is what the externalized React provides).
+ * 4. Manifest emit — when `meta` is supplied, writes `manifest.json` next to the bundled
+ *    module listing every emitted asset (entry, CSS, chunks, etc.) so the host can eagerly
+ *    cache them for offline use.
+ */
+export const composerPlugin = (options?: ComposerPluginOptions): VitePlugin[] => {
+  const entry = options?.entry ?? 'src/plugin.tsx';
+  const port = options?.port ?? PLUGIN_DEV_SERVER_PORT;
+  const meta = options?.meta;
+  const resolved = new Set<string>();
+  let base = '/';
+  const plugins: VitePlugin[] = [
+    // Configure vite for library-mode builds with externalized deps.
+    {
+      name: 'composer-plugin',
+      config: () => ({
+        server: {
+          port,
+          // Allow the Composer host (different origin) to dynamically import plugin modules.
+          cors: true,
+        },
+        preview: { port },
+        build: {
+          sourcemap: true,
+          // Transitively-bundled WASM modules (automerge, tiktoken, …) emit top-level
+          // await; `esnext` lets rolldown pass that through without an explicit polyfill.
+          target: 'esnext',
+          lib: {
+            entry,
+            formats: ['es'],
+            fileName: () => ENTRY_FILENAME,
+          },
+          rolldownOptions: {
+            external: (id: string) => isExternal(id),
+            output: {
+              chunkFileNames: 'chunks/[name]-[hash].js',
+              assetFileNames: 'assets/[name]-[hash][extname]',
+              // Install the CJS require shim at the top of plugin.mjs so transitively
+              // bundled CJS helpers (that call `require('react')` et al. at runtime) can
+              // resolve against the host-provided externals instead of throwing.
+              banner: REQUIRE_SHIM_BANNER,
+            },
+          },
+        },
+      }),
+    },
+    // Dev-time externalization.
+    // Vite's dev server doesn't use rollup externals, so we need to handle it manually.
+    // We intercept imports of shared deps at resolve time, mark them external, and then
+    // strip the `/@id/` prefix that Vite's import analysis injects for external modules.
+    {
+      name: 'composer-plugin:externalize',
+      enforce: 'pre',
+      apply: 'serve',
+      // Exclude shared packages from Vite's dependency pre-bundling.
+      config: () => ({
+        optimizeDeps: {
+          exclude: DEFAULT_PACKAGES,
+        },
+      }),
+      // Mark shared deps as external so Vite doesn't try to bundle them.
+      resolveId: (id) => {
+        if (isExternal(id)) {
+          resolved.add(id);
+          return { id, external: true };
+        }
+      },
+      // Return a stub for any externalized module that Vite tries to load directly.
+      load: (id) => {
+        if (resolved.has(id)) {
+          return { code: 'export default {};' };
+        }
+      },
+      // After all plugins are resolved, inject a late-stage transform plugin that strips
+      // the `/@id/` prefix from externalized bare specifiers in the output.
+      // This must run after Vite's internal import analysis which rewrites bare specifiers.
+      configResolved: (config) => {
+        base = config.base ?? '/';
+        (config.plugins as VitePlugin[]).push({
+          name: 'composer-plugin:strip-prefix',
+          transform: (code: string) => {
+            if (resolved.size === 0) {
+              return;
+            }
+            const escaped = [...resolved].map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+            const pattern = new RegExp(`${base}@id/(${escaped})`, 'g');
+            if (pattern.test(code)) {
+              return code.replace(pattern, (_: string, dep: string) => dep);
+            }
+          },
+        });
+      },
+    },
+    // JSX dev runtime shim.
+    // React refresh (used by @vitejs/plugin-react) imports from `react/jsx-dev-runtime`,
+    // but the externalized React only exposes `react/jsx-runtime`. This virtual module
+    // bridges the gap by re-exporting jsx-runtime's functions under jsx-dev-runtime's API.
+    {
+      name: 'composer-plugin:jsx-dev-shim',
+      enforce: 'pre',
+      apply: 'serve',
+      resolveId: (id) => (id === JSX_DEV_RUNTIME ? `\0${JSX_DEV_RUNTIME}` : undefined),
+      load: (id) =>
+        id === `\0${JSX_DEV_RUNTIME}`
+          ? [
+              'import { jsx, jsxs, Fragment } from "react/jsx-runtime";',
+              'export { Fragment };',
+              'export function jsxDEV(type, props, key, isStaticChildren) {',
+              '  return isStaticChildren ? jsxs(type, props, key) : jsx(type, props, key);',
+              '}',
+            ].join('\n')
+          : undefined,
+    },
+    // React Refresh preamble stub.
+    //
+    // @vitejs/plugin-react's JSX transform prepends a runtime check to every module:
+    //   if (!window.$RefreshReg$) throw new Error("@vitejs/plugin-react can't detect preamble…");
+    // In a normal single-origin app, vite injects a `<script type="module">` preamble
+    // into `index.html` that sets up `$RefreshReg$` / `$RefreshSig$` on `window` before any
+    // app code runs. When a community plugin is dev-served at its own origin and then
+    // dynamic-imported into the Composer host at a different origin, the host's window
+    // never receives that preamble, so every JSX module throws on first import.
+    //
+    // Inject a no-op refresh shim on the host's window from the plugin's entrypoint: fast-
+    // refresh itself doesn't work cross-origin anyway, so silencing the check lets the
+    // plugin load and ordinary page reloads take care of picking up edits. Production
+    // builds are untouched (`apply: 'serve'`).
+    {
+      name: 'composer-plugin:react-refresh-shim',
+      enforce: 'pre',
+      apply: 'serve',
+      transform(code, id) {
+        // Only patch the plugin entrypoint (an absolute path ending in the configured entry).
+        // Matching by suffix keeps us from prepending the shim to every transformed module,
+        // which would both bloat the output and defeat vite's caching.
+        if (!id.endsWith(entry.replace(/^\.?\//, '/'))) {
+          return;
+        }
+        const shim = [
+          '// composer-plugin: no-op React Refresh shim so cross-origin plugin modules',
+          "// don't throw the @vitejs/plugin-react preamble check at dynamic-import time.",
+          'if (typeof window !== "undefined") {',
+          '  window.$RefreshReg$ = window.$RefreshReg$ || (() => {});',
+          '  window.$RefreshSig$ = window.$RefreshSig$ || (() => (type) => type);',
+          '  window.__vite_plugin_react_preamble_installed__ = true;',
+          '}',
+          '',
+        ].join('\n');
+        return { code: shim + code, map: null };
+      },
+    },
+  ];
+  if (meta) {
+    // Emit `manifest.json` alongside the built module listing every emitted asset, so the
+    // dist directory can be uploaded as-is to a GitHub Release for the DXOS community
+    // registry to pick up. The host loader fetches this file at install time and eagerly
+    // caches every listed asset for offline use.
+    plugins.push({
+      name: 'composer-plugin:emit-manifest',
+      apply: 'build',
+      // `enforce: 'post'` is load-bearing: vite's CSS extraction plugin emits sibling
+      // `.css` assets in its own `generateBundle` hook. Without `post`, ours runs first
+      // and sees only the JS chunks — the manifest then omits CSS, so the host can't
+      // inject `<link>` tags for the plugin's stylesheet at install time.
+      enforce: 'post',
+      generateBundle(_options, bundle) {
+        // Source maps are large and only fetched when devtools opens — exclude them
+        // from the manifest so the host doesn't precache megabytes of debug data.
+        const assets = Object.keys(bundle)
+          .filter((name) => name !== MANIFEST_ASSET_NAME && !name.endsWith('.map'))
+          .sort();
+        this.emitFile({
+          type: 'asset',
+          fileName: MANIFEST_ASSET_NAME,
+          source: serializeManifest(meta, { assets }),
+        });
+      },
+    });
+    // Dev-server manifest. `vite dev` can't enumerate transitive chunks/CSS up front
+    // (they resolve on demand), so we serve a `devEntry`-flavored manifest at the dev
+    // root and let the host loader skip eager caching + static stylesheet injection.
+    // The host imports `entry` directly from the dev server, where Vite handles
+    // JSX transforms, externalization, and runtime CSS injection.
+    plugins.push({
+      name: 'composer-plugin:serve-manifest',
+      apply: 'serve',
+      configureServer(server) {
+        const body = serializeManifest(meta, { assets: [], devEntry: entry.replace(/^\.?\//, '') });
+        server.middlewares.use(`/${MANIFEST_ASSET_NAME}`, (req, res, next) => {
+          // Only intercept the bare manifest URL — let any sub-paths fall through.
+          if (req.url && req.url !== '/' && req.url !== '') {
+            return next();
+          }
+          // CORS mirrors `server.cors: true` (see plugin config above) so the host
+          // app at a different origin can read the manifest. Vite's built-in CORS
+          // covers most paths but middlewares mounted before its `cors` middleware
+          // need to set the header themselves.
+          res.setHeader('Access-Control-Allow-Origin', '*');
+          res.setHeader('Content-Type', 'application/json');
+          res.setHeader('Cache-Control', 'no-store');
+          res.statusCode = 200;
+          res.end(body);
+        });
+      },
+    });
+  }
+  return plugins;
+};