sygnal 6.2.0 → 6.4.0

package/src/index.d.ts

@@ -156,7 +156,7 @@ type EventNextFunction = (action: string, data?: any, delay?: number) => void
 
 /** Payload function for `event()` / `emit()`: receives the reducer arguments, returns the event data. */
 export type EventPayloadFunction<TYPE extends string = string, STATE = any, DATA = any> =
-  (state: STATE, data: DATA, next: EventNextFunction, props: any) => EventPayload<TYPE>
+  (state: STATE, data: DATA, next: EventNextFunction, props: any) => EventPayload<TYPE> | ABORT
 
 /**
  * Remaining arguments of `event()` / `emit()` when the payload is a static value.
@@ -1977,7 +1977,8 @@ export function emit<TYPE extends EventName>(
  *   }
  *
  * The payload is either a function `(state, data, next, props) => payload` or a static value:
- *   `event('RESET')`, `event('SET_MODE', 'dark')`.
+ *   `event('RESET')`, `event('SET_MODE', 'dark')`. A payload function that returns `ABORT` sends
+ *   nothing: `event('SAVED', (state) => state.dirty ? { id: state.id } : ABORT)`.
  *
  * With a `SygnalEvents` registry, `type` must be a registered name and the payload must match
  * its type. When used inside a model, the payload function's `state` and `data` parameters are
@@ -2358,6 +2359,21 @@ export type FetchRequest = string | {
    * schema's (possibly transformed) value. A failure is an error with `issues`
    */
   validate?: StandardSchemaLike;
+  /**
+   * D472: send these sub-requests instead, in parallel (each inherits this request's fields:
+   * `url`, `headers`, `init`, ...; its own `json` / `body` / `parse` win), and deliver ONE reply:
+   * `combine(bodies, requests)`. One failure fails the request (once). The test fake
+   * (renderComponent) answers the request as one, by its own `url` / `json`. `decide()` makes these
+   */
+  batch?: ReadonlyArray<{ url?: string; method?: string; headers?: Record<string, string>; query?: Record<string, unknown>; json?: unknown; body?: BodyInit; parse?: 'auto' | 'json' | 'text' | ((response: Response) => any) }>;
+  /** D472: merges the parsed bodies of `batch` / `split` parts into the reply (default: the array) */
+  combine?: (bodies: any[], requests: any[]) => any;
+  /**
+   * D472: a request (or a `batch` part) that fails with an HTTP error is sent again as the
+   * requests this returns (≥ 2, in parallel, merged by `combine`), at most 3 times deep; null keeps
+   * the error. `decide()` halves its questions on a 400 / 413 that names a size limit
+   */
+  split?: (request: any, error: Error & { status?: number; body?: any }) => any[] | null | undefined;
   /** Your own fields (an id, ...): not sent, returned on the reply's `request` */
   [appData: string]: any;
 } | {
@@ -2990,6 +3006,12 @@ export interface ServiceWorkerCommand {
 
 export interface ServiceWorkerOptions {
   scope?: string;
+  /**
+   * `false`: the driver registers no service worker, ignores commands and emits nothing, so the
+   * app keeps its `SW` wiring where a worker must not run: `enabled: import.meta.env.PROD`.
+   * Default `true`.
+   */
+  enabled?: boolean;
 }
 
 export function makeServiceWorkerDriver(
@@ -3708,7 +3730,9 @@ declare global {
   namespace JSX {
     interface IntrinsicElements {
       [elemName: string]: any;
+      /** @deprecated since 6.3.0, removed in the next major: `import { Collection } from 'sygnal'` and write `<Collection …>` (SYG426) */
       collection: CollectionProps<any>;
+      /** @deprecated since 6.3.0, removed in the next major: `import { Switchable } from 'sygnal'` and write `<Switchable …>` (SYG426) */
       switchable: SwitchableProps<any>;
       slot: SlotProps;
     }
@@ -3721,6 +3745,15 @@ declare global {
       children: {};
     }
 
+    /**
+     * `key` on any tag (D456): on a component, its identity among its parent's children (before
+     * its `id` prop, then its position): a keyed instance survives a move or a reorder, and a new
+     * key makes a new instance. Never a prop of the component.
+     */
+    interface IntrinsicAttributes {
+      key?: string | number | null;
+    }
+
     /**
      * A component's view receives `state: STATE` and `context`, but in JSX the parent passes
      * an optional `state` slice name or lens (`<Editor state="editor" />`, `<Panel />`).
@@ -3754,6 +3787,21 @@ export type { ChatState, ChatStatus, ChatActions, ChatDone, ChatOptions } from '
 // PLAN-6 M-2 / M-3 (3-M)
 export { answers, commandBar } from './ai.d'
 export type { AnswerPick, AnswerPicks, CommandBarState, CommandBarStatus, CommandBarActions, CommandBarOptions, CommandBarResult, CommandBarUnsure } from './ai.d'
+// PLAN-9 (A): catalogs, the compose behavior, composeWith, the layout utilities
+export { defineCatalog, compose, composeWith, fromTree, toTree, removeNode } from './ai.d'
+// PLAN-9 H: chat client tools and cards
+export { openToolCalls, askCard } from './ai.d'
+export { Composed } from './ai.d'
+export type { ChatClientTool, ChatAskOptions, ChatCard, ChatCardStatus, ChatToolPart, ComposedProps } from './ai.d'
+export type { Catalog, CatalogDecl, CatalogPartDecl, CatalogContainerDecl, CatalogParam, CatalogParamValue, CatalogParamsOf, CatalogRecord, CatalogPart, CatalogContainer, CatalogOption, CatalogTree, CatalogTreeNode, ComposeTree, ContainerView, Layout, LayoutNode, ComposeRenderOptions, ComposeRenderable, ComposeBackend, ComposeNames, ComposeState, ComposeStatus, ComposeActions, ComposeOptions, ComposeAnswer } from './ai.d'
+
+/**
+ * PLAN-9 (D463): a `{ get, set }` lens to the element of the array `state[field]` whose `idKey`
+ * (default 'id') is `id`: a record part's state (`state: (node) => byId('projects',
+ * node.params.id)`) or any child's `state={byId('todos', 3)}`. `get` is undefined once the element
+ * is gone; `set` then leaves the state unchanged.
+ */
+export function byId<T = any, S = any>(field: string, id: unknown, idKey?: string): { get(state: S): T | undefined; set(state: S, value: T): S }
 // PLAN-6 X-1 (3-X)
 export { makeMcpAppDriver } from './ai.d'
 export type { McpAppDriverOptions, McpAppSource, McpAppRequest, McpAppError, McpToolResult, McpHostContext, McpContentBlock, McpAppDisplayMode } from './ai.d'

package/src/index.ts

@@ -68,6 +68,14 @@ export { anthropicMessages, agui, fromAISDK, strictSchemas } from './extra/ai/in
 export { makeMcpAppDriver } from './extra/ai/index'
 // A-3 (3-A3, experimental, D291)
 export { formTool } from './extra/ai/index'
+// PLAN-9 (A): catalogs, the compose behavior, composeWith, the layout utilities
+export { defineCatalog, compose, composeWith, fromTree, toTree, removeNode } from './extra/ai/index'
+// PLAN-9 H: chat client tools and cards
+export { openToolCalls, askCard } from './extra/ai/index'
+// PLAN-9 M-1: <Composed catalog from /> (documented import: 'sygnal/ai')
+export { Composed } from './extra/ai/index'
+// PLAN-9 (D463): a lens to an array element by id
+export { byId } from './extra/lens'
 
 // export dom helper functions (h, makeDOMDriver, etc.)
 export * from './cycle/dom/index'

package/src/lazy.ts

@@ -1,5 +1,5 @@
-// the core's resolver for lazy components, registered on import (D157)
-import './core/markers/lazy';
+// the core's resolver for lazy components (D157), registered by the first lazy() call (G-751)
+import {enableLazy} from './core/markers/lazy';
 
 /**
  * PLAN-5 B-4 (D103): `when` defers the import: 'visible' starts it when a placeholder enters the
@@ -24,6 +24,7 @@ export interface LazyOptions {
 const WHEN = 'data-sygnal-when';
 
 export function lazy(loadFn: () => Promise<any>, options?: LazyOptions): any {
+  enableLazy();
   let cachedComponent: any = null;
   let loadError: any = null;
   const g: any = globalThis, when = options?.when, ph = options?.placeholderHeight;

package/src/portal.ts

@@ -1,13 +1,16 @@
 import {h} from './cycle/dom/snabbdom';
-// the core's handler for this marker, registered on import (D157)
-import './core/markers/portal';
+// the core's handler for this marker (D157), registered when a tag uses it (G-751: the pragma calls
+// `$reg`; not on import, so a bundle that never uses the marker drops the handler)
+import {enablePortal as reg} from './core/markers/portal';
 
 const Portal = (props: any) => {
+  reg();
   const {children, ...sanitizedProps} = props;
   return h('portal', {props: sanitizedProps}, children);
 };
 (Portal as any).componentName = 'portal';
 (Portal as any).preventInstantiation = true;
+(Portal as any).$reg = reg;
 
 export {Portal};
 export default Portal;

package/src/pragma/index.ts

@@ -322,7 +322,8 @@ export const createElementWithModules = (modules: Record<string, any>) => {
     if (typeof text === 'undefined') plain = !!(flatten(children, kids = []) & +plain)
     // G-492: a custom element (bit 8) routes list as a prop, in its own cache
     const d = data ? sanitizeData(data, modules, isComponent ? croutes : t & 8 ? xroutes : routes, isComponent || t & 8 && 2) : {}
-    if (fn) d[fn.preventInstantiation ? 'm' : 'c'] = fn
+    // G-751: a marker's core handler registers on first use (`$reg`), not when its module loads
+    if (fn) d[fn.preventInstantiation ? 'm' : 'c'] = fn, fn.$reg?.()
     const key = k !== undefined ? k : data ? data.key : undefined
     const vnode = plain ? new (Plain as any)(sel, d, kids, text, key) : { sel, data: d, children: kids, text, elm: undefined, key }
     if (t & 2) applySvg(vnode)

package/src/suspense.ts

@@ -1,13 +1,16 @@
 import {h} from './cycle/dom/snabbdom';
-// the core's handler for this marker, registered on import (D157)
-import './core/markers/suspense';
+// the core's handler for this marker (D157), registered when a tag uses it (G-751: the pragma calls
+// `$reg`; not on import, so a bundle that never uses the marker drops the handler)
+import {enableSuspense as reg} from './core/markers/suspense';
 
 const Suspense = (props: any) => {
+  reg();
   const {children, ...sanitizedProps} = props;
   return h('suspense', {props: sanitizedProps}, children);
 };
 (Suspense as any).componentName = 'suspense';
 (Suspense as any).preventInstantiation = true;
+(Suspense as any).$reg = reg;
 
 export {Suspense};
 export default Suspense;

package/src/switchable.ts

@@ -1,5 +1,6 @@
 import {h} from './cycle/dom/snabbdom';
-// the core's handler for this marker, registered on import (D157)
+// the core's host for this marker, registered on import (D157): unlike Portal, Transition and
+// Suspense (G-751), not on first use, because the lowercase tag works without an import (docs)
 import './core/hosts/switchable';
 
 /** `<Switchable of={{ a: A, b: B }} current={state.tab} />`: a marker vnode the core's Switchable host renders */

package/src/transition.ts

@@ -1,13 +1,16 @@
 import {h} from './cycle/dom/snabbdom';
-// the core's handler for this marker, registered on import (D157)
-import './core/markers/transition';
+// the core's handler for this marker (D157), registered when a tag uses it (G-751: the pragma calls
+// `$reg`; not on import, so a bundle that never uses the marker drops the handler)
+import {enableTransition as reg} from './core/markers/transition';
 
 const Transition = (props: any) => {
+  reg();
   const {children, ...sanitizedProps} = props;
   return h('transition', {props: sanitizedProps}, children);
 };
 (Transition as any).componentName = 'transition';
 (Transition as any).preventInstantiation = true;
+(Transition as any).$reg = reg;
 
 export {Transition};
 export default Transition;

package/src/vike/onRenderClient.ts

@@ -105,7 +105,8 @@ function componentVNode(comp: any, key: string, stateField: any, children: any[]
     children,
     text: undefined,
     elm: undefined,
-    key: '__vike_' + key + '__',
+    // no vnode key: it would be the instance identity (D456); `id` is (G-207)
+    key: undefined,
   }
 }
 
@@ -132,7 +133,7 @@ function pageChildVNode(pageState: any, stateField: any = 'page'): any {
     children: [],
     text: undefined,
     elm: undefined,
-    key: '__vike_page__',
+    key: undefined,
   }
 }
 

package/src/vite/plugin.ts

@@ -117,6 +117,12 @@
  *      /__sygnal/mcp (./mcp.ts: streamable HTTP, loopback / local Host / local Origin only)
  *      and the dev entries also import 'virtual:sygnal/mcp', which connects the page over the
  *      HMR channel (installMcpBridge from 'sygnal/devtools'). Never in `vite build` or Vitest.
+ *  11. SYG103 view words (dev server with diagnostics on; never `vite build`, SSR or Vitest): a
+ *      module that sets `X.intent` or `X.uses` gets a tail registering, for each such X, the
+ *      words of its string literals and of the relative modules it imports, in
+ *      `globalThis.__SYGNAL_VIEW_TOKENS__`. The runtime SYG103 check then takes a selector drawn
+ *      by a view helper (`{state.open && panel()}`) as conditionally rendered, as it does for
+ *      markup in the view function itself (see viewTokensTail).
  *
  * Why not Vite's `define`? Vite's dependency optimizer does not apply user
  * `define` replacements to pre-bundled dependencies (only process.env.NODE_ENV),
@@ -483,8 +489,17 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
     transform(this: any, code: string, id: string, opts?: { ssr?: boolean }) {
       // SYG666 (PLAN-5 W-2): an adapter entry imported without its optional peers; every mode
       const adapters = adapterImports(this, code, id)
-      if (adapters) return checkPeers(this, adapters, id).then(() => devTransform.call(this, code, id, opts))
-      return devTransform.call(this, code, id, opts)
+      const result = adapters
+        ? checkPeers(this, adapters, id).then(() => devTransform.call(this, code, id, opts))
+        : devTransform.call(this, code, id, opts)
+      // 11. the words SYG103 may take as conditionally rendered markup (dev server, diagnostics on)
+      const tokens = isServe && !isVitest && devOn && !opts?.ssr ? viewTokensTail(this, code, id) : null
+      if (!tokens) return result
+      return Promise.all([result, tokens]).then(([r, tail]: [any, string]) => {
+        if (!tail) return r
+        if (r == null) return withSourcemap(code, [], tail, id)
+        return typeof r == 'string' ? r + tail : { ...r, code: r.code + tail }
+      })
     },
   }
 
@@ -572,6 +587,52 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
   }
 }
 
+// 11. SYG103 (the dev runtime check of an intent selector that never matched) lets a selector
+// through as conditionally rendered when its words appear in the component's view; the runtime
+// can read only the view function's own source. A component module (one that sets `X.intent` or
+// `X.uses`) gets, in dev, a tail registering for each such component the words of its string
+// literals and those of the relative modules it imports, where view helpers live
+// (globalThis.__SYGNAL_VIEW_TOKENS__, a WeakMap read by checks/dom.ts).
+const COMPONENT_WITH_SELECTORS_RE = /(?:^|[^\w$.])([A-Z][\w$]*)\.(?:intent|uses)\s*=(?!=)/g
+const STRING_RE = /(['"])((?:\\.|(?!\1)[^\\\n])*)\1|`((?:\\[\s\S]|[^\\`])*)`/g
+const RELATIVE_IMPORT_RE = /(?:\bfrom|\bimport)\s*\(?\s*(['"])(\.{1,2}\/[^'"]+)\1/g
+
+// A string that is itself a selector ('.save', '#id', 'form.ask', '[data-x]') or a path / URL: its
+// words aren't markup (the intent's own DOM.click('.svae') would otherwise vouch for its typo)
+const NOT_MARKUP_RE = /(?:^|[\s>+~,(])[\w-]*[.#[][\w-]|^\s*(?:\/|[\w+-]+:\/\/)/
+
+/** the class / id / tag-like words in a module's string and template literals (comments skipped) */
+function stringWords(code: string, into: Set<string>): void {
+  for (const m of blankOut(code, false).matchAll(STRING_RE)) {
+    const text = m[2] ?? m[3] ?? ''
+    if (NOT_MARKUP_RE.test(text)) continue
+    for (const w of text.match(/[A-Za-z_][\w-]*/g) || []) into.add(w)
+  }
+}
+
+function viewTokensTail(ctx: any, code: string, id: string): Promise<string> | null {
+  const file = cleanId(id)
+  if (!/\.[jt]sx?$/.test(file) || id.includes('node_modules') || id.startsWith('\0')) return null
+  const names = new Set<string>()
+  for (const m of blankOut(code, true).matchAll(COMPONENT_WITH_SELECTORS_RE)) names.add(m[1])
+  if (!names.size) return null
+  const words = new Set<string>()
+  stringWords(code, words)
+  const specs = new Set(Array.from(blankOut(code, false).matchAll(RELATIVE_IMPORT_RE), m => m[2]))
+  return Promise.all([...specs].map(async (spec) => {
+    try {
+      const r = await ctx.resolve(spec, id)
+      const dep = r && !r.external && cleanId(r.id)
+      if (!dep || !/\.[cm]?[jt]sx?$/.test(dep) || dep.includes('node_modules')) return
+      ctx.addWatchFile?.(dep)
+      stringWords(await fs.promises.readFile(dep, 'utf8'), words)
+    } catch (_) { /* unreadable: its words are just not added */ }
+  })).then(() => {
+    const comps = [...names].map(n => `typeof ${n} == 'function' && ${n}`).join(', ')
+    return `\n;(() => { try { const m = globalThis.__SYGNAL_VIEW_TOKENS__ ||= new WeakMap(), t = ${JSON.stringify([...words].join(' '))}; for (const c of [${comps}]) if (c) m.set(c, t) } catch (_) {} })();\n`
+  })
+}
+
 // PLAN-5 W-2 (D209): the adapter entries and the optional peer dependencies each one imports
 // (the Zag packages pinned together: they depend on each other's exact versions)
 const ZAG = '~1.45.0'