@dxos/app-framework 0.8.4-main.72ec0f3 → 0.8.4-main.74a063c4e0

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/composer-plugin.ts

@@ -0,0 +1,128 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Plugin } from 'vite';
+
+import { DEFAULT_PACKAGES } from './packages';
+
+const JSX_DEV_RUNTIME = 'react/jsx-dev-runtime';
+
+/** Regex patterns matching each shared package and all its subpath imports. */
+const EXTERNAL_DEPS = DEFAULT_PACKAGES.map((pkg) => new RegExp(`^${pkg.replace('/', '\\/')}(\\/|$)`));
+
+/** Checks whether an import should be externalized (all shared deps except jsx-dev-runtime). */
+const isExternal = (id: string) => id !== JSX_DEV_RUNTIME && EXTERNAL_DEPS.some((pattern) => pattern.test(id));
+
+/**
+ * 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 three concerns:
+ * 1. Build config — lib mode entry point, ES format output, rollup externals.
+ * 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).
+ */
+export const composerPlugin = (options?: { entry?: string; port?: number }): Plugin[] => {
+  const entry = options?.entry ?? 'src/plugin.tsx';
+  const port = options?.port ?? 3967;
+  const resolved = new Set<string>();
+  let base = '/';
+
+  return [
+    // Plugin 1: 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,
+          lib: {
+            entry,
+            formats: ['es'],
+          },
+          rolldownOptions: {
+            external: EXTERNAL_DEPS,
+          },
+        },
+      }),
+    },
+
+    // Plugin 2: 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 Plugin[]).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);
+            }
+          },
+        });
+      },
+    },
+
+    // Plugin 3: 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,
+    },
+  ];
+};

package/src/vite-plugin/import-map-plugin.ts

@@ -0,0 +1,314 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { init as initCjsLexer, parse as parseCjs } from 'cjs-module-lexer';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire as nodeCreateRequire } from 'node:module';
+import path from 'node:path';
+import { type Plugin } from 'vite';
+
+import { DEFAULT_PACKAGES } from './packages';
+
+const require = nodeCreateRequire(import.meta.url);
+
+//
+// Import map helpers.
+// These utilities support `importMapPlugin` by resolving package entrypoints,
+// detecting module formats (ESM vs CJS), and extracting named exports from CJS bundles.
+//
+
+/** Strips vite query strings (e.g. `?v=123`) from resolved module IDs. */
+const trimQueryString = (id: string) => id.replace(/\?.*$/, '');
+
+/**
+ * Determines whether a resolved file is an ESM module by checking file extension
+ * first (.mjs/.cjs), then walking up to the nearest package.json for `"type": "module"`.
+ */
+const resolvedIdIsEsmModule = (resolvedId: string): boolean => {
+  const file = trimQueryString(resolvedId);
+  if (file.endsWith('.mjs') || file.endsWith('.mts')) {
+    return true;
+  }
+  if (file.endsWith('.cjs') || file.endsWith('.cts')) {
+    return false;
+  }
+
+  let directory = path.dirname(file);
+  while (directory !== path.dirname(directory)) {
+    const packageJsonPath = path.join(directory, 'package.json');
+    if (existsSync(packageJsonPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { type?: string };
+        return pkg.type === 'module';
+      } catch {
+        return false;
+      }
+    }
+    directory = path.dirname(directory);
+  }
+
+  return false;
+};
+
+/**
+ * Walks up from a resolved file path to find the package.json whose `"name"` matches
+ * the given package name. Returns the path to that package.json, or undefined.
+ */
+const findPackageJsonPath = (resolvedId: string, packageName: string): string | undefined => {
+  let directory = path.dirname(trimQueryString(resolvedId));
+
+  while (directory !== path.dirname(directory)) {
+    const packageJsonPath = path.join(directory, 'package.json');
+    if (existsSync(packageJsonPath)) {
+      try {
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { name?: string };
+        if (packageJson.name === packageName) {
+          return packageJsonPath;
+        }
+      } catch {}
+    }
+
+    directory = path.dirname(directory);
+  }
+
+  return undefined;
+};
+
+/** Resolves a package name to its package.json path using Node's require.resolve. */
+const resolvePackageJsonPath = (packageName: string): string | undefined => {
+  try {
+    return findPackageJsonPath(require.resolve(packageName), packageName);
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Subpath exports that should be excluded from the import map.
+ * These are node-only entrypoints (vite plugins, native addons) that shouldn't be pre-bundled for the browser.
+ */
+const importMapExcludedSubpaths: Readonly<Record<string, ReadonlySet<string>>> = {
+  '@dxos/app-framework': new Set(['vite-plugin']),
+  '@dxos/ui-theme': new Set(['plugin']),
+};
+
+/**
+ * Reads a package's `exports` field and returns all JS subpath entrypoints as bare specifiers
+ * (e.g. `@dxos/client`, `@dxos/client/echo`). Skips wildcard patterns, non-JS assets,
+ * and excluded subpaths. Falls back to just the package name if exports is absent or simple.
+ */
+const getPackageEntrypoints = (packageName: string, packageJsonPath: string): string[] => {
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
+    exports?: Record<string, unknown> | string | string[];
+  };
+  const exportsField = packageJson.exports;
+
+  if (!exportsField || typeof exportsField === 'string' || Array.isArray(exportsField)) {
+    return [packageName];
+  }
+
+  const exportKeys = Object.keys(exportsField);
+  if (!exportKeys.some((key) => key.startsWith('.'))) {
+    return [packageName];
+  }
+
+  const excluded = importMapExcludedSubpaths[packageName];
+  const modules = exportKeys.flatMap((key) => {
+    if (key === '.') {
+      return [packageName];
+    }
+
+    if (!key.startsWith('./') || key === './package.json' || key.includes('*')) {
+      return [];
+    }
+
+    const subpath = key.slice(2);
+    if (excluded?.has(subpath)) {
+      return [];
+    }
+
+    if (/\.(css|pcss|scss|less|json|node|wasm|html|svg|png|jpg)$/.test(subpath)) {
+      return [];
+    }
+
+    return [`${packageName}/${subpath}`];
+  });
+
+  return modules.length > 0 ? modules : [packageName];
+};
+
+/**
+ * Statically analyzes a CJS file to extract named exports using cjs-module-lexer.
+ * Follows re-exports (e.g. react's index.js re-exports from cjs/react.development.js)
+ * and deduplicates. Filters out `default` and `__esModule` pseudo-exports.
+ */
+const getCjsNamedExports = (filePath: string, seen = new Set<string>()): string[] => {
+  const normalized = trimQueryString(filePath);
+  if (seen.has(normalized)) {
+    return [];
+  }
+  seen.add(normalized);
+
+  try {
+    const source = readFileSync(normalized, 'utf8');
+    const { exports: directExports, reexports } = parseCjs(source);
+
+    const reexportedNames = reexports.flatMap((reexport) => {
+      const resolved = path.resolve(path.dirname(normalized), reexport);
+      const candidates = [resolved, `${resolved}.js`, `${resolved}.cjs`];
+      const found = candidates.find((candidate) => existsSync(candidate));
+      return found ? getCjsNamedExports(found, seen) : [];
+    });
+
+    return [...new Set([...directExports, ...reexportedNames])].filter(
+      (name) => name !== 'default' && name !== '__esModule',
+    );
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Vite plugin for the **host app** (Composer). Generates a browser import map so that
+ * shared packages are loaded once and reused by both the host and any remote plugins.
+ *
+ * In dev mode, maps bare specifiers directly to resolved file paths.
+ * In production, emits a dedicated chunk per specifier via virtual wrapper modules,
+ * then injects a `<script type="importmap">` tag into the HTML with the chunk URLs.
+ *
+ * Virtual wrappers are needed because directly emitting chunks for CJS packages loses
+ * their named exports due to Rollup's interop. The wrapper re-exports them explicitly.
+ */
+export const importMapPlugin = (options?: { packages?: string[] }): Plugin[] => {
+  const packages = options?.packages ?? DEFAULT_PACKAGES;
+  const WRAPPER_PREFIX = '\0import-map:';
+  const chunkRefIds: Record<string, string> = {};
+  const resolvedIds: Record<string, string> = {};
+  let imports: Record<string, string> = {};
+  let modules: string[] = [];
+  let importMapIsDev = false;
+  let base = '/';
+
+  return [
+    // Phase 1: Resolve all package entrypoints and emit chunks (or record dev paths).
+    {
+      name: 'import-map:get-chunk-ref-ids',
+      configResolved(config) {
+        base = config.base ?? '/';
+      },
+      async buildStart() {
+        importMapIsDev = this.environment.mode === 'dev';
+        await initCjsLexer();
+
+        // Expand each package name into its full set of subpath entrypoints
+        // (e.g. '@dxos/client' -> ['@dxos/client', '@dxos/client/echo', ...]).
+        modules = [
+          ...new Set(
+            (
+              await Promise.all(
+                packages.map(async (packageName) => {
+                  const packageJsonPath = resolvePackageJsonPath(packageName);
+                  if (!packageJsonPath) {
+                    this.warn(`Unable to locate package.json for import map package: ${packageName}`);
+                    return [packageName];
+                  }
+
+                  return getPackageEntrypoints(packageName, packageJsonPath);
+                }),
+              )
+            ).flat(),
+          ),
+        ];
+
+        for (const specifier of modules) {
+          const resolved = await this.resolve(specifier);
+          if (!resolved) {
+            this.warn(`Import map: unable to resolve "${specifier}"; omitting from import map.`);
+            continue;
+          }
+
+          if (importMapIsDev) {
+            // Dev: map bare specifier directly to the resolved file path.
+            imports[specifier] = trimQueryString(resolved.id);
+          } else {
+            // Prod: emit a virtual wrapper chunk that re-exports from the real module.
+            resolvedIds[specifier] = resolved.id;
+            chunkRefIds[specifier] = this.emitFile({
+              type: 'chunk',
+              id: `${WRAPPER_PREFIX}${specifier}`,
+              preserveSignature: 'strict',
+            });
+          }
+        }
+      },
+
+      // Intercept virtual wrapper IDs so Rollup doesn't try to resolve them as files.
+      resolveId(id) {
+        if (id.startsWith(WRAPPER_PREFIX)) {
+          return id;
+        }
+      },
+
+      // Generate the source for each virtual wrapper module.
+      // For CJS packages, explicitly re-export named exports (discovered via static analysis)
+      // because Rollup's `export *` interop doesn't preserve them for CJS.
+      load(id) {
+        if (!id.startsWith(WRAPPER_PREFIX)) {
+          return;
+        }
+        const specifier = id.slice(WRAPPER_PREFIX.length);
+        const resolvedId = resolvedIds[specifier];
+        if (!resolvedId) {
+          return `export * from ${JSON.stringify(specifier)};\n`;
+        }
+
+        const filePath = trimQueryString(resolvedId);
+        const isCjs = filePath.endsWith('.cjs') || (!filePath.endsWith('.mjs') && !resolvedIdIsEsmModule(filePath));
+
+        if (isCjs) {
+          const named = getCjsNamedExports(filePath);
+          if (named.length > 0) {
+            return `export { default, ${named.join(', ')} } from ${JSON.stringify(specifier)};\n`;
+          }
+        }
+        return `export * from ${JSON.stringify(specifier)};\n`;
+      },
+
+      // After bundling, map each specifier to the URL of its emitted chunk.
+      generateBundle() {
+        if (importMapIsDev) {
+          return;
+        }
+
+        imports = Object.fromEntries(
+          modules
+            .filter((specifier) => chunkRefIds[specifier] !== undefined)
+            .map((specifier) => [specifier, `${base}${this.getFileName(chunkRefIds[specifier])}`]),
+        );
+      },
+    },
+
+    // Phase 2: Inject the import map into the HTML as a <script type="importmap"> tag.
+    {
+      name: 'import-map:transform-index-html',
+      enforce: 'post',
+      transformIndexHtml(html: string) {
+        const tags = [
+          {
+            tag: 'script',
+            attrs: {
+              type: 'importmap',
+            },
+            children: JSON.stringify({ imports }, null, 2),
+          },
+        ];
+
+        return {
+          html,
+          tags,
+        };
+      },
+    },
+  ];
+};

package/src/vite-plugin/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './composer-plugin';
+export * from './import-map-plugin';

package/src/vite-plugin/packages.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * Packages shared between the Composer host app and remote plugins.
+ * The host provides these via import map so plugins don't bundle their own copies.
+ * Used as the default list for both `importMapPlugin` (host) and `composerPlugin` (plugin).
+ */
+export const DEFAULT_PACKAGES = [
+  '@dxos/app-framework',
+  '@dxos/app-graph',
+  '@dxos/app-toolkit',
+  '@dxos/client',
+  '@dxos/client-protocol',
+  '@dxos/client-services',
+  '@dxos/config',
+  '@dxos/echo',
+  '@dxos/lit-ui',
+  '@dxos/react-client',
+  '@dxos/react-ui',
+  '@dxos/schema',
+  '@dxos/ui-theme',
+  '@effect/platform',
+  'effect',
+  'lit',
+  'react',
+  'react-dom',
+];

package/tsconfig.json

@@ -15,13 +15,13 @@
       "path": "../../common/debug"
     },
     {
-      "path": "../../common/invariant"
+      "path": "../../common/effect"
     },
     {
-      "path": "../../common/keys"
+      "path": "../../common/errors"
     },
     {
-      "path": "../../common/local-storage"
+      "path": "../../common/invariant"
     },
     {
       "path": "../../common/log"
@@ -33,52 +33,37 @@
       "path": "../../common/storybook-utils"
     },
     {
-      "path": "../../common/util"
+      "path": "../../common/test-utils"
     },
     {
-      "path": "../../core/ai"
+      "path": "../../common/util"
     },
     {
-      "path": "../../core/assistant"
+      "path": "../../common/web-context"
     },
     {
-      "path": "../../core/blueprints"
+      "path": "../../common/web-context-react"
     },
     {
       "path": "../../core/echo/echo"
     },
     {
-      "path": "../../core/echo/echo-signals"
+      "path": "../../core/echo/echo-db"
     },
     {
-      "path": "../../core/echo/live-object"
+      "path": "../../core/operation"
     },
     {
-      "path": "../../core/functions"
+      "path": "../../ui/react-primitives/react-error-boundary"
     },
     {
-      "path": "../../ui/primitives/react-hooks"
+      "path": "../../ui/react-primitives/react-hooks"
     },
     {
       "path": "../../ui/react-ui"
     },
     {
-      "path": "../../ui/react-ui-syntax-highlighter"
-    },
-    {
-      "path": "../../ui/react-ui-theme"
-    },
-    {
-      "path": "../app-graph"
-    },
-    {
-      "path": "../client-protocol"
-    },
-    {
-      "path": "../schema"
-    },
-    {
-      "path": "../types"
+      "path": "../../ui/ui-theme"
     }
   ]
 }

package/tsconfig.node.json

@@ -2,10 +2,8 @@
   "compilerOptions": {
     "composite": true,
     "module": "ESNext",
-    "moduleResolution": "Node",
+    "moduleResolution": "Bundler",
     "allowSyntheticDefaultImports": true
   },
-  "include": [
-    "vite.config.ts"
-  ]
+  "include": ["vite.config.ts"]
 }

package/typedoc.json

@@ -1,7 +1,5 @@
 {
   "$schema": "https://typedoc.org/schema.json",
   "includeVersion": true,
-  "entryPoints": [
-    "src/index.ts"
-  ]
-}
+  "entryPoints": ["src/index.ts"]
+}

package/vitest.config.ts

@@ -9,6 +9,6 @@ import { createConfig } from '../../../vitest.base.config';
 
 export default createConfig({
   dirname: typeof __dirname !== 'undefined' ? __dirname : path.dirname(fileURLToPath(import.meta.url)),
-  node: true,
+  node: { environment: 'jsdom' },
   storybook: true,
 });