@stacksjs/stx 0.2.118 → 0.2.120

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

@@ -9,17 +9,6 @@
  * - `import { ... } from '@composables'` (handled by transformStoreImports)
  */
 export declare function hasUserImports(code: string): boolean;
-/**
- * Bundle a client script using Bun.build.
- *
- * Resolves local imports (@/, ./), npm packages, and tree-shakes unused exports.
- * stx runtime, @stores, and @composables are marked as external.
- *
- * @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
- */
 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$/,
@@ -101,6 +101,7 @@ function createBundlePlugin(projectRoot, templateDir, tmpEntry, inputFiles) {
     }
   };
 }
+const inFlightBundles = new Map;
 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 +112,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 +133,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 = 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 +222,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 +235,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-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/composables/use-timer.d.ts

@@ -39,7 +39,7 @@ export declare function useThrottle<T extends (...args: any[]) => any>(fn: T, li
  * // counter increments every second
  * ```
  */
-export declare function useInterval(interval?: number, options?: IntervalOptions): IntervalRef;
+export declare function useInterval(interval?: number | ((counter: number) => void), options?: IntervalOptions | number): IntervalRef;
 /**
  * One-shot timeout with start/stop control and auto-cleanup.
  *

package/dist/composables/use-timer.js

@@ -95,16 +95,26 @@ export function useThrottle(fn, limit = 250) {
   return throttled;
 }
 export function useInterval(interval = 1000, options = {}) {
+  let callback = null;
+  if (typeof interval === "function") {
+    callback = interval;
+    interval = typeof options === "number" ? options : 1000;
+    options = {};
+  }
+  const delay = interval || 1000, config = typeof options === "number" ? {} : options;
   let count = 0, id = null, running = !1;
-  const listeners = new Set, tick = () => {
+  const listeners = new Set;
+  if (callback)
+    listeners.add(callback);
+  const tick = () => {
     count++;
     listeners.forEach((fn) => fn(count));
   }, resume = () => {
     if (running)
       return;
     running = !0;
-    id = setInterval(tick, interval);
-    if (options.immediate)
+    id = setInterval(tick, delay);
+    if (config.immediate)
       tick();
   }, pause = () => {
     if (!running)

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