@stacksjs/stx 0.2.119 → 0.2.121

package/dist/client-script-bundler.d.ts

@@ -10,16 +10,18 @@
  */
 export declare function hasUserImports(code: string): boolean;
 /**
- * Bundle a client script using Bun.build.
+ * Run one client bundle build at a time.
  *
- * Resolves local imports (@/, ./), npm packages, and tree-shakes unused exports.
- * stx runtime, @stores, and @composables are marked as external.
+ * Bun.build can return transient "Unseekable reading file" failures when
+ * separate builds concurrently traverse the same linked workspace dependency.
+ * Dashboard renders commonly compile the layout and page controllers together,
+ * so distinct content hashes still share much of their dependency graph.
  *
- * @param code - The script content (may contain import statements)
- * @param filePath - The .stx template file path (for relative import resolution)
- * @param options - Bundling options
- * @returns Bundled code with all imports resolved and inlined
+ * Cache reads remain concurrent and identical builds still share one promise.
+ * Only cold Bun.build work is queued, and a rejected task cannot stall the next
+ * build.
  */
+export declare function queueClientBundleBuild<T>(task: () => Promise<T>): Promise<T>;
 export declare function bundleClientScript(code: string, filePath: string, options?: {
     projectRoot?: string
     minify?: boolean

package/dist/client-script-bundler.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import fs from "node:fs";
 import { getPublicEnvDefine } from "./public-env.js";
 import { stateDir } from "./state-dir.js";
-const BUNDLE_CACHE_VERSION = 4, EXTERNAL_PATTERNS = [
+const BUNDLE_CACHE_VERSION = 5, BUNDLE_CACHE_METADATA_VERSION = 1, EXTERNAL_PATTERNS = [
   /^stx$/,
   /^@stacksjs\/stx$/,
   /^@stores$/,
@@ -98,9 +98,27 @@ function createBundlePlugin(projectRoot, templateDir, tmpEntry, inputFiles) {
         console.warn(`[stx:bundler] could not resolve ${args.path[0]}/ import:`, args.path);
         return { path: resolved };
       });
+      build.onLoad({ filter: /\.(?:[cm]?[jt]sx?|json)$/ }, (args) => {
+        const extension = path.extname(args.path).toLowerCase(), loader = extension === ".json" ? "json" : extension === ".tsx" ? "tsx" : extension === ".jsx" ? "jsx" : extension === ".ts" || extension === ".mts" || extension === ".cts" ? "ts" : "js";
+        inputFiles.add(args.path);
+        return {
+          contents: fs.readFileSync(args.path, "utf8"),
+          loader
+        };
+      });
     }
   };
 }
+const inFlightBundles = new Map, CLIENT_BUNDLE_QUEUE = Symbol.for("stx.client-bundle-build-queue");
+export function queueClientBundleBuild(task) {
+  const shared = globalThis, result = (shared[CLIENT_BUNDLE_QUEUE] ?? Promise.resolve()).then(task, task);
+  shared[CLIENT_BUNDLE_QUEUE] = result.then(() => {
+    return;
+  }, () => {
+    return;
+  });
+  return result;
+}
 export async function bundleClientScript(code, filePath, options = {}) {
   const projectRoot = options.projectRoot || process.cwd(), minify = options.minify ?? !1, cacheDir = options.cacheDir || stateDir(projectRoot, "bundle-cache"), hasher = new Bun.CryptoHasher("md5");
   hasher.update(`${BUNDLE_CACHE_VERSION}\x00${code}\x00${filePath}`);
@@ -111,7 +129,9 @@ export async function bundleClientScript(code, filePath, options = {}) {
     if (await depsFile.exists())
       try {
         const stored = JSON.parse(await depsFile.text());
-        for (const dep of stored.files)
+        if (stored.metadataVersion !== BUNDLE_CACHE_METADATA_VERSION || !Array.isArray(stored.files))
+          depsValid = !1;
+        for (const dep of Array.isArray(stored.files) ? stored.files : [])
           try {
             if (fs.statSync(dep.path).mtimeMs !== dep.mtimeMs) {
               depsValid = !1;
@@ -130,7 +150,19 @@ export async function bundleClientScript(code, filePath, options = {}) {
     }
     console.log("[stx:bundler] cache invalidated by dep change:", hash);
   }
-  const tmpDir = stateDir(projectRoot, "bundle-tmp"), tmpEntry = path.join(tmpDir, `${hash}.ts`), tmpOutDir = path.join(tmpDir, "out", hash);
+  const running = inFlightBundles.get(hash);
+  if (running)
+    return await running;
+  const build = queueClientBundleBuild(() => buildBundle(code, filePath, { projectRoot, minify, cacheDir, hash, cachePath, depsPath }));
+  inFlightBundles.set(hash, build);
+  try {
+    return await build;
+  } finally {
+    inFlightBundles.delete(hash);
+  }
+}
+async function buildBundle(code, filePath, options) {
+  const { projectRoot, minify, cacheDir, hash, cachePath, depsPath } = options, tmpDir = stateDir(projectRoot, "bundle-tmp"), tmpEntry = path.join(tmpDir, `${hash}.ts`), tmpOutDir = path.join(tmpDir, "out", hash);
   fs.mkdirSync(tmpDir, { recursive: !0 });
   fs.mkdirSync(tmpOutDir, { recursive: !0 });
   const templateDir = path.dirname(filePath), declNames = [], declRegex = /^(export\s+)?(?:const|let|var)\s+(?:\{([^}]+)\}|(\w+))/gm, funcRegex = /^(export\s+)?(?:async\s+)?function\s+(\w+)/gm;
@@ -207,6 +239,10 @@ return { ${returnedBindings} };
 })();
 ${publicAssignments}`.trim();
     console.log("[stx:bundler] bundled:", hash, "output:", bundled.length, "bytes");
+    if (declNames.length > 0 && exposedBindings.length === 0) {
+      console.warn(`[stx:bundler] dropped every binding for ${path.basename(filePath)} (${hash}); serving the unbundled source and not caching this result`);
+      return code;
+    }
     fs.mkdirSync(cacheDir, { recursive: !0 });
     await Bun.write(cachePath, bundled);
     const depsSnapshot = Array.from(inputFiles).map((p) => {
@@ -216,7 +252,10 @@ ${publicAssignments}`.trim();
         return null;
       }
     }).filter((d) => d !== null);
-    await Bun.write(depsPath, JSON.stringify({ files: depsSnapshot }));
+    await Bun.write(depsPath, JSON.stringify({
+      metadataVersion: BUNDLE_CACHE_METADATA_VERSION,
+      files: depsSnapshot
+    }));
     return bundled;
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error), bunErrors = error?.errors, detail = Array.isArray(bunErrors) && bunErrors.length > 0 ? `

package/dist/client-script.d.ts

@@ -33,11 +33,31 @@ export declare function extractAndStripCssImports(code: string, options: { fileP
  * below un-layered rules, so vendor styles default to lowest precedence.
  */
 export declare function renderVendorStyleTags(styles: VendorCssImport[]): string;
+/**
+ * Turn bare core browser helper usage into a real module import before the
+ * client bundler runs.
+ *
+ * Inline signal scripts execute synchronously while the document is parsed.
+ * Loading `window.StacksBrowser` from a later module script is therefore too
+ * late. A real import lets Bun inline and tree-shake the selected browser
+ * helpers together with the component, exactly like an explicit user import.
+ */
+export declare function injectBrowserCoreAutoImports(code: string): BrowserCoreAutoImportResult;
 /**
  * Generate destructuring statements for auto-imported symbols
  * These access globals set up by the STX runtime and @stacksjs/browser
  */
 export declare function generateAutoImportDestructuring(stxImports: string[], browserImports: string[]): string;
+/**
+ * Generate the browser-runtime bindings needed by a signal setup wrapper.
+ *
+ * Signal pages and Vue-like signal components use specialized scoped wrappers
+ * instead of {@link processClientScript}. They already pull every STX runtime
+ * global from `window.stx`, but still need the selected Stacks browser helpers
+ * used by their script. Keeping detection here makes classic scripts, signal
+ * pages, and signal components share the same browser auto-import contract.
+ */
+export declare function generateBrowserAutoImportDestructuring(code: string, exclude?: readonly string[]): string;
 /**
  * Build the server → client bridge payload from a template context: the
  * top-level, JSON-serializable values (excluding internal `__`/`$` keys and
@@ -71,6 +91,10 @@ export declare interface VendorCssImport {
   resolvedPath: string
   contents: string
 }
+export declare interface BrowserCoreAutoImportResult {
+  code: string
+  imports: string[]
+}
 // =============================================================================
 // Types
 // =============================================================================

package/dist/client-script.js

@@ -162,6 +162,7 @@ const STX_AUTO_IMPORTS = [
   "useQuery",
   "useMutation",
   "useOptimistic",
+  "useId",
   "useReactiveProp",
   "useLocalStorage",
   "useSessionStorage",
@@ -185,6 +186,7 @@ const STX_AUTO_IMPORTS = [
   "useColorMode",
   "useDark",
   "useMediaQuery",
+  "useScrollLock",
   "usePreferredDark",
   "usePreferredLight",
   "usePreferredReducedMotion",
@@ -230,8 +232,53 @@ const STX_AUTO_IMPORTS = [
   "getBrowserConfig",
   "createBrowserDb",
   "createBrowserModel",
-  "isBrowser"
-], JS_BUILTINS = new Set([
+  "isBrowser",
+  "debounce",
+  "throttle",
+  "retry",
+  "sleep",
+  "wait",
+  "delay",
+  "waitUntil",
+  "waitWhile",
+  "lazy",
+  "clamp",
+  "rand",
+  "readableSize",
+  "useDocumentVisibility",
+  "useIntervalFn"
+];
+export function injectBrowserCoreAutoImports(code) {
+  const explicitlyImported = new Set;
+  for (const match of code.matchAll(/^\s*import\s+(?:type\s+)?\{([^}]*)\}\s+from\s+['"][^'"]+['"]\s*;?\s*$/gm))
+    for (const specifier of match[1].split(",")) {
+      const localName = specifier.trim().split(/\s+as\s+/).pop()?.replace(/^type\s+/, "").trim();
+      if (localName)
+        explicitlyImported.add(localName);
+    }
+  const locallyDeclared = new Set;
+  for (const match of code.matchAll(/\b(?:const|let|var|function|class)\s+([A-Za-z_$][\w$]*)/g))
+    locallyDeclared.add(match[1]);
+  for (const match of code.matchAll(/\b(?:const|let|var)\s*\{([^}]*)\}/g))
+    for (const binding of match[1].split(",")) {
+      const localName = binding.trim().split(/[:=]/).pop()?.trim();
+      if (localName)
+        locallyDeclared.add(localName);
+    }
+  const imports = BROWSER_CORE_IMPORTS.filter((symbol) => {
+    if (explicitlyImported.has(symbol) || locallyDeclared.has(symbol))
+      return !1;
+    return new RegExp(`\\b${symbol}\\b`).test(code);
+  });
+  if (imports.length === 0)
+    return { code, imports };
+  return {
+    code: `import { ${imports.join(", ")} } from '@stacksjs/browser'
+${code}`,
+    imports
+  };
+}
+const JS_BUILTINS = new Set([
   "Promise",
   "Object",
   "Array",
@@ -350,6 +397,10 @@ ${lines.join(`
 ${generateAutoImportGuard(stxImports, browserImports)}`;
   return "";
 }
+export function generateBrowserAutoImportDestructuring(code, exclude = []) {
+  const { browserImports } = transformAutoImports(code), excluded = new Set(exclude);
+  return generateAutoImportDestructuring([], browserImports.filter((name) => !excluded.has(name)));
+}
 function generateAutoImportGuard(stxImports, browserImports) {
   const entries = [
     ...stxImports.map((name) => `['${name}', typeof ${name}, 'stx']`),
@@ -753,13 +804,16 @@ function extractTemplateReferences(templateHtml) {
   return refs;
 }
 export async function processClientScript(scriptContent, options = {}) {
-  let code = scriptContent, autoImportCode = "", wasBundled = !1;
+  let code = scriptContent, autoImportCode = "", wasBundled = !1, bundledBrowserImports = [];
   const cssExtraction = extractAndStripCssImports(code, {
     filePath: options.filePath,
     projectRoot: options.projectRoot
   });
   code = cssExtraction.code;
-  const vendorStyleTags = renderVendorStyleTags(cssExtraction.styles), { hasUserImports, bundleClientScript } = await import("./client-script-bundler.js");
+  const vendorStyleTags = renderVendorStyleTags(cssExtraction.styles), browserCoreImports = injectBrowserCoreAutoImports(code);
+  code = browserCoreImports.code;
+  bundledBrowserImports = browserCoreImports.imports;
+  const { hasUserImports, bundleClientScript } = await import("./client-script-bundler.js");
   if (hasUserImports(code)) {
     console.log("[stx:bundler] user imports detected, bundling...");
     code = await bundleClientScript(code, options.filePath || "", {
@@ -771,7 +825,7 @@ export async function processClientScript(scriptContent, options = {}) {
   if (options.autoImports !== !1) {
     const autoImportResult = transformAutoImports(code);
     code = autoImportResult.code;
-    autoImportCode = generateAutoImportDestructuring(autoImportResult.stxImports, autoImportResult.browserImports);
+    autoImportCode = generateAutoImportDestructuring(autoImportResult.stxImports, autoImportResult.browserImports.filter((name) => !bundledBrowserImports.includes(name)));
   }
   autoImportCode = `${generateServerDataBridge(code, options.serverData)}${autoImportCode}`;
   code = transformStoreImports(code);

package/dist/component-library.js

@@ -58,7 +58,13 @@ function extractClientMethods(source, file) {
   for (const script of scripts) {
     if (!/\bclient\b/i.test(script[1]) || /\bcomponent\b|\bstx:component\b/i.test(script[1]))
       continue;
-    const code = script[2], functionPattern = /(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(([^)]*)\)\s*\{/g;
+    let code;
+    try {
+      code = new Bun.Transpiler({ loader: "ts" }).transformSync(script[2]);
+    } catch (error) {
+      throw Error(`${file}: failed to transpile <script client> (${error.message})`);
+    }
+    const functionPattern = /(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(([^)]*)\)\s*\{/g;
     let match;
     while (match = functionPattern.exec(code)) {
       const name = match[1];
@@ -673,17 +679,29 @@ ${components.map((component) => `import type { ${component.name}Props } from './
   let bundle;
   if (config.bundle !== !1) {
     bundle = path.join(outputDir, "bundle.js");
-    const result = await Bun.build({
-      entrypoints: [path.join(outputDir, "index.js")],
-      outdir: outputDir,
-      naming: "bundle.js",
-      target: "browser",
-      format: "esm",
-      minify: config.minify ?? !0,
-      sourcemap: config.sourcemap || "none"
-    });
-    if (!result.success)
-      throw AggregateError(result.logs, "Failed to bundle component library");
+    let result;
+    try {
+      result = await Bun.build({
+        entrypoints: [path.join(outputDir, "index.js")],
+        outdir: outputDir,
+        naming: "bundle.js",
+        target: "browser",
+        format: "esm",
+        minify: config.minify ?? !0,
+        sourcemap: config.sourcemap || "none"
+      });
+    } catch (error) {
+      const logs = error instanceof AggregateError ? error.errors : [error], details = logs.map((log) => String(log).trim()).filter(Boolean).join(`
+`);
+      throw AggregateError(logs, `Failed to bundle component library${details ? `
+${details}` : ""}`);
+    }
+    if (!result.success) {
+      const details = result.logs.map((log) => String(log).trim()).filter(Boolean).join(`
+`);
+      throw AggregateError(result.logs, `Failed to bundle component library${details ? `
+${details}` : ""}`);
+    }
     files.push(bundle);
     if (config.sourcemap === "external")
       files.push(`${bundle}.map`);

package/dist/component-registry.d.ts

@@ -27,6 +27,7 @@ export declare interface RenderContext {
  */
 export declare interface ResolvedProps {
   static: Record<string, string | boolean>
+  staticNames: Record<string, string>
   serverDynamic: Record<string, unknown>
   clientReactive: Record<string, string>
   events: Record<string, string>

package/dist/component-renderer.js

@@ -176,6 +176,7 @@ const BOOLEAN_ATTRIBUTE_SENTINEL = "\x00stx-boolean-attribute", htmlTags = new S
 function parseComponentProps(rawProps, context, options) {
   const resolved = {
     static: {},
+    staticNames: {},
     serverDynamic: {},
     clientReactive: {},
     events: {}
@@ -199,7 +200,14 @@ function parseComponentProps(rawProps, context, options) {
   ]), kebabToCamel = (key) => {
     if (!key.includes("-") || key.startsWith("@") || key.startsWith(":") || key.startsWith("x-") || key.startsWith("__"))
       return key;
+    if (key.startsWith("aria-") || key.startsWith("data-"))
+      return key;
     return key.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+  }, setStatic = (attrName, value) => {
+    const propName = kebabToCamel(attrName);
+    resolved.static[propName] = value;
+    if (propName !== attrName)
+      resolved.staticNames[propName] = attrName;
   };
   for (const [rawAttrName, attrValue] of Object.entries(rawProps)) {
     const attrName = rawAttrName.startsWith("x-") && !ALPINE_PASSTHROUGH.has(rawAttrName) && !rawAttrName.startsWith("x-bind:") && !rawAttrName.startsWith("x-on:") ? `:${rawAttrName.slice(2)}` : rawAttrName;
@@ -242,16 +250,16 @@ function parseComponentProps(rawProps, context, options) {
           const expression = singleExprMatch[1];
           if (isExpressionSafe(expression)) {
             const evaluated = createSafeFunction(expression, Object.keys(context))(...Object.values(context));
-            resolved.static[attrName] = evaluated != null ? String(evaluated) : "";
+            setStatic(attrName, evaluated != null ? String(evaluated) : "");
           } else {
             if (options.debug)
               console.error(`Unsafe expression in ${attrName}: ${expression}`);
-            resolved.static[attrName] = attrValue;
+            setStatic(attrName, attrValue);
           }
         } catch (error) {
           if (options.debug)
             console.error(`Error evaluating expression for ${attrName}:`, error);
-          resolved.static[attrName] = attrValue;
+          setStatic(attrName, attrValue);
         }
       else {
         let result = attrValue;
@@ -271,11 +279,11 @@ function parseComponentProps(rawProps, context, options) {
             if (options.debug)
               console.error(`Error evaluating expression in ${attrName}:`, error);
           }
-        resolved.static[attrName] = result;
+        setStatic(attrName, result);
       }
       continue;
     }
-    resolved.static[attrName] = attrValue === BOOLEAN_ATTRIBUTE_SENTINEL ? "true" : attrValue;
+    setStatic(attrName, attrValue === BOOLEAN_ATTRIBUTE_SENTINEL ? "true" : attrValue);
   }
   return resolved;
 }

package/dist/composables/index.d.ts

@@ -62,6 +62,7 @@ export {
   breakpoints,
   type MediaQueryRef,
 } from './use-media-query';
+export { useScrollLock } from './use-scroll-lock';
 // Network
 export {
   useNetwork,

package/dist/composables/index.js

@@ -31,6 +31,7 @@ export {
   useIsDesktop,
   breakpoints
 } from "./use-media-query.js";
+export { useScrollLock } from "./use-scroll-lock.js";
 export {
   useNetwork,
   useOnline

package/dist/composables/use-scroll-lock.d.ts

@@ -0,0 +1,13 @@
+import type { Signal } from '../signals-api';
+/**
+ * Reactively lock scrolling on an element, defaulting to the document body.
+ *
+ * Multiple locks on the same element are reference counted, so releasing one
+ * overlay cannot restore scrolling while another overlay is still open.
+ */
+export declare function useScrollLock(target?: ScrollLockTarget): Signal<boolean>;
+declare type ScrollLockTarget = | HTMLElement
+  | null
+  | undefined
+  | { current?: HTMLElement | null, value?: HTMLElement | null }
+  | (() => HTMLElement | null | undefined);

package/dist/composables/use-scroll-lock.js

@@ -0,0 +1,55 @@
+import { onDestroy, state } from "../signals-api.js";
+const scrollLockStates = new WeakMap;
+function resolveTarget(target) {
+  let value = target;
+  if (typeof value === "function")
+    value = value();
+  if (value && typeof value === "object" && "current" in value)
+    value = value.current;
+  if (value && typeof value === "object" && !("nodeType" in value) && "value" in value)
+    value = value.value;
+  return value || document.body || document.documentElement;
+}
+function acquire(element) {
+  const existing = scrollLockStates.get(element);
+  if (existing) {
+    existing.count += 1;
+    return;
+  }
+  scrollLockStates.set(element, { count: 1, overflow: element.style.overflow });
+  element.style.overflow = "hidden";
+}
+function release(element) {
+  const existing = scrollLockStates.get(element);
+  if (!existing)
+    return;
+  existing.count -= 1;
+  if (existing.count > 0)
+    return;
+  element.style.overflow = existing.overflow;
+  scrollLockStates.delete(element);
+}
+export function useScrollLock(target) {
+  const locked = state(!1);
+  let lockedElement = null;
+  const unsubscribe = locked.subscribe((value) => {
+    if (value) {
+      if (lockedElement)
+        return;
+      lockedElement = resolveTarget(target);
+      if (lockedElement)
+        acquire(lockedElement);
+    } else if (lockedElement) {
+      release(lockedElement);
+      lockedElement = null;
+    }
+  });
+  onDestroy(() => {
+    unsubscribe();
+    if (lockedElement) {
+      release(lockedElement);
+      lockedElement = null;
+    }
+  });
+  return locked;
+}

package/dist/composition-api.d.ts

@@ -74,7 +74,7 @@ export declare function setGlobalProvide<T>(key: string | symbol, value: T): voi
  * emit('change', 'newValue')
  * ```
  */
-export declare function defineEmits<T extends Record<string, any[]> = Record<string, any[]>>(_events?: string[] | T): EmitFn<Extract<keyof T, string>>;
+export declare function defineEmits<T extends Record<string, any[]> = Record<string, any[]>>(events?: string[] | T): EmitFn<Extract<keyof T, string>>;
 /**
  * Expose public properties from a component instance.
  * These properties become accessible via template refs from the parent.

package/dist/composition-api.js

@@ -55,16 +55,25 @@ const globalProvides = new Map;
 export function setGlobalProvide(key, value) {
   globalProvides.set(key, value);
 }
-export function defineEmits(_events) {
-  const instance = currentInstance, emit = (event, ...args) => {
+export function defineEmits(events) {
+  const instance = currentInstance, element = instance?.el, declaredEvents = Array.isArray(events) ? events : events && typeof events === "object" ? Object.keys(events) : [];
+  if (element && declaredEvents.length > 0) {
+    const emittedEvents = element.__stx_component_emits ||= Object.create(null);
+    for (const event of declaredEvents)
+      emittedEvents[event] = !0;
+  }
+  const emit = (event, ...args) => {
     if (typeof document > "u")
       return;
-    if (instance?.el)
-      instance.el.dispatchEvent(new CustomEvent(event, {
+    if (element) {
+      const emittedEvents = element.__stx_component_emits ||= Object.create(null);
+      emittedEvents[event] = !0;
+      element.dispatchEvent(new CustomEvent(event, {
         detail: args.length === 1 ? args[0] : args,
         bubbles: !0,
         cancelable: !0
       }));
+    }
   };
   if (instance)
     instance.emit = emit;

package/dist/craft-bridge.d.ts

@@ -186,6 +186,12 @@ else if (data.type === 'event' && data.method) {
     });
   }
 
+  // Live component handles, keyed by id, so an event coming back from the host
+  // can be routed to the callbacks registered on the right one. Without this
+  // the onSelect/onSpaceChange callbacks were stored and never invoked.
+  const sidebars = new Map();
+  const spacesSidebars = new Map();
+
   function createNativeUIFacade() {
     class Sidebar {
       constructor(id) {
@@ -205,10 +211,42 @@ else if (data.type === 'event' && data.method) {
         return this;
       }
       destroy() {
+        sidebars.delete(this.id);
         sendNativeUI('destroyComponent', { id: this.id, type: 'sidebar' });
       }
     }
 
+    /**
+     * An Arc-style sidebar of swipeable spaces.
+     *
+     * Separate from Sidebar rather than an option on it: a source list selects
+     * one row out of many, while a spaces sidebar selects one whole SCENE, and
+     * a host that renders the switcher natively (a segmented control in the
+     * toolbar, a Touch Bar strip) needs the space list, not the item list.
+     */
+    class SpacesSidebar {
+      constructor(id) {
+        this.id = id;
+        this._spaceCallbacks = [];
+      }
+      setSpaces(spaces) {
+        sendNativeUI('setSidebarSpaces', { sidebarId: this.id, spaces });
+        return this;
+      }
+      setActiveSpace(spaceId) {
+        sendNativeUI('setActiveSpace', { sidebarId: this.id, spaceId });
+        return this;
+      }
+      onSpaceChange(callback) {
+        this._spaceCallbacks.push(callback);
+        return this;
+      }
+      destroy() {
+        spacesSidebars.delete(this.id);
+        sendNativeUI('destroyComponent', { id: this.id, type: 'spacesSidebar' });
+      }
+    }
+
     class FileBrowser {
       constructor(id) {
         this.id = id;
@@ -245,12 +283,33 @@ else if (data.type === 'event' && data.method) {
       }
     }
 
+    // Host -> page. The host names the component in the payload; we look up the
+    // handle and fan out to whatever the page registered on it.
+    on('sidebar.select', function(params) {
+      const sidebar = sidebars.get(params && params.sidebarId);
+      if (sidebar) sidebar._selectCallbacks.forEach(fn => fn(params.itemId));
+    });
+    on('sidebar.spaceChange', function(params) {
+      const sidebar = spacesSidebars.get(params && params.sidebarId);
+      if (sidebar) sidebar._spaceCallbacks.forEach(fn => fn(params.spaceId));
+    });
+
     return {
       createSidebar(options) {
         const opts = options || {};
         const id = opts.id || 'sidebar-' + Date.now() + '-' + Math.random().toString(36).slice(2);
         sendNativeUI('createSidebar', Object.assign({}, opts, { id }));
-        return new Sidebar(id);
+        const sidebar = new Sidebar(id);
+        sidebars.set(id, sidebar);
+        return sidebar;
+      },
+      createSpacesSidebar(options) {
+        const opts = options || {};
+        const id = opts.id || 'spaces-' + Date.now() + '-' + Math.random().toString(36).slice(2);
+        sendNativeUI('createSpacesSidebar', Object.assign({}, opts, { id }));
+        const sidebar = new SpacesSidebar(id);
+        spacesSidebars.set(id, sidebar);
+        return sidebar;
       },
       createFileBrowser(options) {
         const opts = options || {};
@@ -399,6 +458,26 @@ else if (data.type === 'event' && data.method) {
       platform: () => request('process.platform'),
     },
 
+    // Gesture stream
+    //
+    // A webview's wheel events carry no phase information, so a page can only
+    // guess where a trackpad swipe begins and ends — typically with an idle
+    // timeout, which mistimes the release and cannot see momentum at all. The
+    // host holds the real NSEvent, so it forwards the phases instead:
+    //
+    //   { axis: 'horizontal' | 'vertical',
+    //     phase: 'begin' | 'change' | 'end',
+    //     deltaX, deltaY,            // points since the last event
+    //     velocityX, velocityY,      // points per second, at 'end'
+    //     momentum: boolean }        // the OS is coasting, not the finger
+    //
+    // Consumers must stay correct when nothing ever arrives: a host without
+    // gesture support simply never emits, so keep the wheel path bound and let
+    // a begin phase take over from it.
+    gestures: {
+      onSwipe: (callback) => on('gesture.swipe', callback),
+    },
+
     // Native component helpers
     nativeUI,
     components: componentAPI