sygnal 5.4.0 → 6.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sygnal",
-  "version": "5.4.0",
+  "version": "6.0.0",
   "description": "An intuitive framework for building fast and small components or applications based on Cycle.js",
   "main": "./dist/index.cjs.js",
   "types": "./dist/index.d.ts",
@@ -31,6 +31,47 @@
       "import": "./dist/diagnostics.esm.js",
       "require": "./dist/diagnostics.cjs.js"
     },
+    "./devtools": {
+      "types": "./src/devtools.d.ts",
+      "import": "./dist/devtools.esm.js",
+      "require": "./dist/devtools.cjs.js"
+    },
+    "./element": {
+      "types": "./src/element.d.ts",
+      "import": "./dist/element.esm.js",
+      "require": "./dist/element.cjs.js"
+    },
+    "./ui": {
+      "types": "./src/ui.d.ts",
+      "import": "./dist/ui.esm.js",
+      "require": "./dist/ui.cjs.js"
+    },
+    "./ui/menu": {
+      "types": "./src/ui-menu.d.ts",
+      "import": "./dist/ui-menu.esm.js",
+      "require": "./dist/ui-menu.cjs.js"
+    },
+    "./ui/select": {
+      "types": "./src/ui-select.d.ts",
+      "import": "./dist/ui-select.esm.js",
+      "require": "./dist/ui-select.cjs.js"
+    },
+    "./ui/combobox": {
+      "types": "./src/ui-combobox.d.ts",
+      "import": "./dist/ui-combobox.esm.js",
+      "require": "./dist/ui-combobox.cjs.js"
+    },
+    "./zag": {
+      "types": "./src/zag.d.ts",
+      "import": "./dist/zag.esm.js",
+      "require": "./dist/zag.cjs.js"
+    },
+    "./react": {
+      "types": "./src/react.d.ts",
+      "import": "./dist/react.esm.js",
+      "require": "./dist/react.cjs.js"
+    },
+    "./shims/globalthis": "./dist/shims/globalthis.cjs",
     "./vite": {
       "types": "./src/vite/plugin.d.ts",
       "import": "./dist/vite/plugin.mjs",
@@ -53,18 +94,15 @@
     },
     "./vike": {
       "types": "./src/vike/types.ts",
-      "import": "./dist/vike/+config.js",
-      "require": "./dist/vike/+config.cjs.js"
+      "default": "./dist/vike/config/+config.js"
     },
     "./vike/config": {
       "types": "./src/vike/types.ts",
-      "import": "./dist/vike/+config.js",
-      "require": "./dist/vike/+config.cjs.js"
+      "default": "./dist/vike/config/+config.js"
     },
     "./config": {
       "types": "./src/vike/types.ts",
-      "import": "./dist/vike/+config.js",
-      "require": "./dist/vike/+config.cjs.js"
+      "default": "./dist/vike/config/+config.js"
     },
     "./vike/onRenderHtml": {
       "import": "./dist/vike/onRenderHtml.mjs",
@@ -86,15 +124,19 @@
   "files": [
     "dist",
     "src",
-    "llms.txt"
+    "llms.txt",
+    "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "vitest run && npm run test:examples && npm run test:types && npm run test:browser",
+    "test": "vitest run && npm run test:examples && npm run test:types && npm run test:browser && npm run test:perf-gate",
+    "test:perf-gate": "node scripts/perf-gate.mjs",
     "test:examples": "node scripts/test-examples.mjs",
-    "test:types": "npx tsc --project type-tests/tsconfig.json 2>&1 | grep '^type-tests/' && exit 1 || exit 0",
+    "test:recipes": "node scripts/test-recipes.mjs",
+    "test:types": "npx tsc --project tsconfig.json --noEmit && npx tsc --project type-tests/tsconfig.json",
     "test:browser": "npm test --prefix browser-tests",
     "test:watch": "vitest",
-    "build": "npx rollup -c && npx rollup -c rollup.config.dts.mjs",
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && npx rollup -c && npx rollup -c rollup.config.dts.mjs && node scripts/copy-guides.mjs",
     "build:types": "npx rollup -c rollup.config.dts.mjs",
     "build:all": "npm run build",
     "build:devtools": "node devtools/build.mjs",
@@ -106,7 +148,7 @@
     "url": "git+https://github.com/tpresley/sygnal.git"
   },
   "engines": {
-    "node": ">=12.0.0"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "keywords": [
     "cycle",
@@ -122,20 +164,62 @@
   },
   "homepage": "https://github.com/tpresley/sygnal#readme",
   "dependencies": {
-    "extend": "^3.0.2",
+    "@tanstack/virtual-core": "^3.17.11",
     "snabbdom": "^3.6.3",
     "xstream": "^11.14.0"
   },
+  "peerDependencies": {
+    "@zag-js/combobox": "~1.45.0",
+    "@zag-js/menu": "~1.45.0",
+    "@zag-js/select": "~1.45.0",
+    "@zag-js/vanilla": "~1.45.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@zag-js/combobox": {
+      "optional": true
+    },
+    "@zag-js/menu": {
+      "optional": true
+    },
+    "@zag-js/select": {
+      "optional": true
+    },
+    "@zag-js/vanilla": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^25.0.4",
     "@rollup/plugin-node-resolve": "^15.2.1",
     "@rollup/plugin-terser": "^0.4.3",
     "@rollup/plugin-typescript": "^11.1.6",
+    "@zag-js/combobox": "1.45.0",
+    "@zag-js/dialog": "1.45.0",
+    "@zag-js/menu": "1.45.0",
+    "@zag-js/select": "1.45.0",
+    "@zag-js/vanilla": "1.45.0",
+    "flatpickr": "4.6.13",
     "jsdom": "^29.1.1",
+    "preact": "11.0.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
     "rollup": "^3.28.1",
     "rollup-plugin-dts": "^6.1.1",
     "tslib": "^2.6.2",
     "typescript": "^5.4.5",
-    "vitest": "^4.0.18"
+    "valibot": "^1.5.0",
+    "vitest": "^4.0.18",
+    "zod": "^4.6.5"
+  },
+  "overrides": {
+    "vite": "^7.3.6"
   }
 }

package/src/astro/client.ts

@@ -1,21 +1,26 @@
 // The public entry (external in the build), so islands share the app's
 // Sygnal core instead of a bundled copy (B-019).
 import { run } from 'sygnal'
+// PLAN-4 GS-11 / D120: the app-level error hook, the default export of the module the
+// integration's `onError` option names (undefined without it); served by sygnal/astro's Vite plugin
+// @ts-ignore — a virtual module
+import onError from 'virtual:sygnal/astro-on-error'
 
 interface SygnalComponent {
   (args: any): any;
-  isSygnalComponent?: boolean;
   model?: any;
   intent?: any;
-  hmrActions?: any;
+  connections?: any;
+  resources?: any;
+  route?: any;
+  head?: any;
+  persist?: any;
+  uses?: any;
+  timers?: any;
+  viewTransitions?: any;
   context?: any;
-  peers?: any;
-  components?: any;
   initialState?: any;
   calculated?: any;
-  storeCalculatedInState?: any;
-  DOMSourceName?: string;
-  stateSourceName?: string;
   onError?: (error: Error, info: { componentName: string }) => any;
   debug?: boolean;
   componentName?: string;
@@ -29,8 +34,7 @@ interface AstroMetadata {
 function looksLikeSygnalComponent(Component: any): Component is SygnalComponent {
   if (typeof Component !== 'function') return false
   return Boolean(
-    Component.isSygnalComponent ||
-      Component.model ||
+    Component.model ||
       Component.intent ||
       Component.initialState ||
       Component.componentName
@@ -61,23 +65,30 @@ export default (element: any) => {
     const Wrapped: any = (args: any) => Component({ ...islandProps, ...args, props: islandProps })
     Wrapped.model = Component.model
     Wrapped.intent = Component.intent
-    Wrapped.hmrActions = Component.hmrActions
     Wrapped.context = Component.context
-    Wrapped.peers = Component.peers
-    Wrapped.components = Component.components
     Wrapped.initialState = Component.initialState
     Wrapped.calculated = Component.calculated
-    Wrapped.storeCalculatedInState = Component.storeCalculatedInState
-    Wrapped.DOMSourceName = Component.DOMSourceName
-    Wrapped.stateSourceName = Component.stateSourceName
     Wrapped.onError = Component.onError
     Wrapped.debug = Component.debug
+    Wrapped.connections = Component.connections
+    Wrapped.resources = Component.resources
+    Wrapped.route = Component.route
+    Wrapped.head = Component.head
+    // PLAN-4 3-B2: more statics the core reads off the root view: persist (root only: the island
+    // is its app's root), uses, timers (they run only with a timer driver) and viewTransitions
+    Wrapped.persist = Component.persist
+    Wrapped.uses = Component.uses
+    Wrapped.timers = Component.timers
+    Wrapped.viewTransitions = Component.viewTransitions
     Wrapped.componentName = Component.componentName || Component.name
     // run() names the root by `name` first: diagnostics and devtools should
     // say 'Counter', not 'Wrapped'
     try { Object.defineProperty(Wrapped, 'name', { value: Wrapped.componentName, configurable: true }) } catch (_) {}
 
-    const app = run(Wrapped, {}, { mountPoint })
+    // G-206: a `uid` island prop is the island's uid root (as on the server); the view's own
+    // uid() function wins over the prop (args are spread last)
+    // 3-B2: `__hydrate` tells persist() whether the island starts over the server's markup
+    const app = run(Wrapped, { __hydrate: () => client !== 'only' && canHydrate }, { mountPoint, onError, uid: islandProps.uid })
     element.__sygnal = app
   }
 }

package/src/astro/index.d.ts

@@ -12,6 +12,7 @@ declare type SygnalAstroIntegration = {
       updateConfig: (config: any) => void;
       command?: 'dev' | 'build' | 'preview' | 'sync';
       logger?: { warn: (message: string) => void };
+      config?: { root?: URL | string; vite?: any };
     }) => void;
   };
 };
@@ -29,6 +30,29 @@ export interface SygnalAstroOptions {
    * @default true
    */
   check?: boolean | CheckPluginOptions;
+  /**
+   * Resolve xstream's `globalthis` dependency to a stub returning the native
+   * `globalThis` (see the sygnal/vite `nativeGlobalThis` option), in
+   * `astro dev` and `astro build`. false: keep the polyfill package.
+   * @default true
+   */
+  nativeGlobalThis?: boolean;
+  /**
+   * Install the DevTools bridge for islands in `astro dev` (see the sygnal/vite
+   * `devtools` option). Never in `astro build`.
+   * @default true
+   */
+  devtools?: boolean;
+  /**
+   * The islands' app-level error hook (PLAN-4 GS-11): the path of a module, relative to the
+   * Astro project root, whose default export is called as run()'s and renderToString's
+   * `onError`, in the browser and during SSR. Reporting only, after a component's onError
+   * boundary chose the fallback.
+   * @example sygnal({ onError: './src/onError.js' })
+   * // src/onError.js
+   * export default (error, { componentName, action, phase }) => report(error)
+   */
+  onError?: string;
 }
 
 /**

package/src/astro/index.ts

@@ -1,8 +1,38 @@
 import sygnalVite from '../vite/plugin'
+import { globalThisAlias } from '../vite/globalthis'
 import type { DiagnosticsMode, DiagnosticsPluginOptions, CheckPluginOptions } from '../vite/plugin'
+// Node built-ins (the integration runs in Node). The package has no @types/node.
+// @ts-ignore
+import path from 'node:path'
+// @ts-ignore
+import { fileURLToPath } from 'node:url'
 
 const SYGNAL_RENDERER_NAME = '@sygnal/astro'
 
+// PLAN-4 GS-11 / D120: both island entries import this; it re-exports the default export of the
+// module the `onError` option names (undefined without it)
+const ON_ERROR_ID = 'virtual:sygnal/astro-on-error'
+
+/** The Vite plugin serving ON_ERROR_ID; `file` is absolute (undefined: no hook) */
+function onErrorPlugin(file?: string) {
+  return {
+    name: 'sygnal:astro-on-error',
+    resolveId: (id: string) => id === ON_ERROR_ID ? '\0' + ON_ERROR_ID : undefined,
+    load: (id: string) => id === '\0' + ON_ERROR_ID
+      ? (file ? `export { default } from ${JSON.stringify(file)}` : 'export default undefined')
+      : undefined,
+    // Vite 6+ (Astro 6 renders in its own 'prerender' / 'ssr' environments): the island server
+    // entry imports the virtual module, so Vite must load it (not Node). `ssr.noExternal`
+    // below covers the 'ssr' environment and older Vite
+    configEnvironment: (name: string) => name === 'client' ? undefined : { resolve: { noExternal: ['sygnal'] } },
+  }
+}
+
+/** The project root as a directory path (Astro gives a file: URL) */
+const rootDir = (root: any): string =>
+  // @ts-ignore — Node's process
+  !root ? process.cwd() : typeof root === 'string' ? root : fileURLToPath(root)
+
 interface AstroRenderer {
   name: string;
   clientEntrypoint: string;
@@ -14,6 +44,7 @@ interface AstroConfigSetupArgs {
   updateConfig: (config: any) => void;
   command?: 'dev' | 'build' | 'preview' | 'sync';
   logger?: { warn: (message: string) => void };
+  config?: { root?: URL | string; vite?: { resolve?: { alias?: any } } };
 }
 
 export interface SygnalAstroOptions {
@@ -26,13 +57,34 @@ export interface SygnalAstroOptions {
   diagnostics?: DiagnosticsMode | DiagnosticsPluginOptions;
   /** Run sygnal-check in `astro dev` (see the sygnal/vite `check` option). @default true */
   check?: boolean | CheckPluginOptions;
+  /**
+   * Resolve xstream's `globalthis` dependency to a stub returning the native
+   * `globalThis` (see the sygnal/vite `nativeGlobalThis` option), in
+   * `astro dev` and `astro build`. false: keep the polyfill package.
+   * @default true
+   */
+  nativeGlobalThis?: boolean;
+  /**
+   * Install the DevTools bridge for islands in `astro dev` (see the sygnal/vite
+   * `devtools` option). Never in `astro build`.
+   * @default true
+   */
+  devtools?: boolean;
+  /**
+   * PLAN-4 GS-11: the islands' app-level error hook: the path of a module (relative to the Astro
+   * project root) whose default export is called as run()'s / renderToString's `onError`
+   * (error, { componentName, action, phase }), in the browser and during SSR. Reporting only,
+   * after a component's onError boundary chose the fallback.
+   * @example sygnal({ onError: './src/onError.js' })
+   */
+  onError?: string;
 }
 
 export default function sygnalAstroIntegration(options: SygnalAstroOptions = {}) {
   return {
     name: SYGNAL_RENDERER_NAME,
     hooks: {
-      'astro:config:setup': ({ addRenderer, updateConfig, command }: AstroConfigSetupArgs) => {
+      'astro:config:setup': ({ addRenderer, updateConfig, command, config }: AstroConfigSetupArgs) => {
         addRenderer({
           name: SYGNAL_RENDERER_NAME,
           clientEntrypoint: 'sygnal/astro/client',
@@ -44,12 +96,17 @@ export default function sygnalAstroIntegration(options: SygnalAstroOptions = {})
             jsx: 'automatic',
             jsxImportSource: 'sygnal',
           },
+          // D120: the island entries import the virtual onError module, so they stay on Vite:
+          // not pre-bundled with it, and not externalized (loaded by Node) during SSR
+          optimizeDeps: { exclude: [ON_ERROR_ID] },
+          ssr: { noExternal: ['sygnal'] },
         }
+        const hook = options.onError ? path.resolve(rootDir(config?.root), options.onError) : undefined
 
         // Dev mode (G-014): islands are started by sygnal/astro/client, which
         // user code never imports, so the sygnal Vite plugin wraps that entry
-        // in dev to set the dev flag and load the runtime checks first. It
-        // also runs sygnal-check. Nothing is added to `astro build`.
+        // in dev to install DevTools, set the dev flag and load the runtime checks first. It
+        // also runs sygnal-check. `astro build` only gets the `globalthis` alias.
         if (command === 'dev') {
           vite.plugins = [sygnalVite({
             disableJsx: true,
@@ -57,9 +114,18 @@ export default function sygnalAstroIntegration(options: SygnalAstroOptions = {})
             vitestSetup: false,
             diagnostics: options.diagnostics,
             check: options.check,
+            nativeGlobalThis: options.nativeGlobalThis,
+            devtools: options.devtools,
           })]
+        } else if (options.nativeGlobalThis !== false) {
+          // G-099: the same `globalthis` alias the plugin adds in dev (R2-7: unless the
+          // user's vite config already aliases `globalthis`)
+          const alias = globalThisAlias(config?.vite?.resolve?.alias)
+          if (alias.length) vite.resolve = { alias }
         }
 
+        vite.plugins = [...(vite.plugins || []), onErrorPlugin(hook)]
+
         updateConfig({ vite })
       },
     },

package/src/astro/server.ts

@@ -1,10 +1,12 @@
 import {renderToString} from '../extra/ssr'
+// PLAN-4 GS-11 / D120: the integration's `onError` module (see client.ts)
+// @ts-ignore — a virtual module
+import onError from 'virtual:sygnal/astro-on-error'
 
 function looksLikeSygnalComponent(Component: any): boolean {
   if (typeof Component !== 'function') return false
   return Boolean(
-    Component.isSygnalComponent ||
-      Component.model ||
+    Component.model ||
       Component.intent ||
       Component.initialState ||
       Component.componentName
@@ -27,6 +29,10 @@ export function renderToStaticMarkup(
     const html = renderToString(Component, {
       state: props.initialState || Component.initialState,
       props: {...props, props},
+      // PLAN-4 GS-11: the app-level error hook (as the client's run() gets)
+      onError,
+      // G-206: a `uid` island prop is its uid root (as on the client), for two islands on a page
+      uid: props.uid,
     })
     return {html, attrs: {}}
   } catch (err: any) {

package/src/collection.ts

@@ -1,101 +1,14 @@
-import isolate from './cycle/isolate/index';
-import {makeCollection} from './cycle/state/index';
-import {h} from './cycle/dom/index';
-import type {Lens} from './cycle/state/types';
-import {fail} from './extra/diagnostics/legacy';
-
-let COLLECTION_COUNT = 0;
-
-interface CollectionOptions {
-  combineList?: string[];
-  globalList?: string[];
-  stateSourceName?: string;
-  domSourceName?: string;
-  container?: string;
-  containerClass?: string;
-}
-
-export default function collection(
-  component: (...args: any[]) => any,
-  stateLense: string | Lens<any, any>,
-  opts: CollectionOptions = {}
-): (sources: any) => any {
-  if (typeof component !== 'function') {
-    fail('SYG411', 'collection', 'first argument (component) must be a function', 'Pass a component function');
-  }
-  const {
-    combineList = ['DOM'],
-    globalList = ['EVENTS'],
-    stateSourceName = 'STATE',
-    domSourceName = 'DOM',
-    container = 'div',
-    containerClass,
-  } = opts;
-
-  return (sources: any) => {
-    const key = `sygnal-collection-${COLLECTION_COUNT++}`;
-    const collectionOpts = {
-      item: component,
-      itemKey: (state: any, ind: number) =>
-        typeof state.id !== 'undefined' ? state.id : ind,
-      // B-009: prefix with the collection instance so two Collections in one parent whose
-      // items share ids get different DOM isolation scopes
-      itemScope: (itemKey: any) => `${key}-${itemKey}`,
-      channel: stateSourceName,
-      collectSinks: (instances: any) => {
-        return Object.entries(sources).reduce<Record<string, any>>(
-          (acc, [name]) => {
-            if (combineList.includes(name)) {
-              const combined = instances.pickCombine(name);
-              if (name === domSourceName && container) {
-                acc[domSourceName] = combined.map((children: any) => {
-                  const data = containerClass
-                    ? {props: {className: containerClass}}
-                    : {};
-                  return {
-                    sel: container,
-                    data,
-                    children,
-                    key,
-                    text: undefined,
-                    elm: undefined,
-                  };
-                });
-              } else {
-                acc[name] = combined;
-              }
-            } else {
-              acc[name] = instances.pickMerge(name);
-            }
-            return acc;
-          },
-          {}
-        );
-      },
-    };
-
-    const isolateOpts: Record<string, any> = {[stateSourceName]: stateLense};
-
-    globalList.forEach((global) => (isolateOpts[global] = null));
-    combineList.forEach((combine) => (isolateOpts[combine] = null));
-
-    return makeIsolatedCollection(collectionOpts, isolateOpts, sources);
-  };
-}
-
-function makeIsolatedCollection(
-  collectionOpts: any,
-  isolateOpts: any,
-  sources: any
-): any {
-  return isolate(makeCollection(collectionOpts), isolateOpts)(sources);
-}
+import {h} from './cycle/dom/snabbdom';
+// the core's handler for this marker, registered on import (D157)
+import './core/hosts/collection';
 
+/** `<Collection of={Item} from="items" />`: a marker vnode the core's Collection host renders */
 const Collection = (props: any) => {
   const {children, ...sanitizedProps} = props;
   return h('collection', {props: sanitizedProps}, children);
 };
-(Collection as any).label = 'collection';
+(Collection as any).componentName = 'collection';
 (Collection as any).preventInstantiation = true;
 
 export {Collection};
+export default Collection;