sygnal 6.3.0 → 6.4.0

package/llms.txt

@@ -79,7 +79,7 @@ SaveButton.intent = ({ DOM }) => ({ SAVE: DOM.click('.save') })
 SaveButton.model = {
   SAVE: {
     STATE:  (state) => ({ ...state, saving: true }),
-    EVENTS: event('DOC_SAVED', (state) => ({ id: state.id })),  // or event('RESET'), event('MODE', 'dark')
+    EVENTS: event('DOC_SAVED', (state) => ({ id: state.id })),  // or event('RESET'), event('MODE', 'dark'); return ABORT to send nothing
   },
 }
 function Toast({ state }) {   // anywhere in the tree: EVENTS is a global bus

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sygnal",
-  "version": "6.3.0",
+  "version": "6.4.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",

package/src/extra/diagnostics/checks/dom.ts

@@ -25,8 +25,10 @@
  *      that matches in one Collection item is fine for all of them.
  *
  * SYG103 noise control (conditional rendering is normal): a selector whose
- * class/id/tag tokens all appear in the component's view source is assumed
- * to be conditionally rendered and is not reported. A selector that does not
+ * class/id/tag tokens all appear in the component's view source (or in the
+ * words sygnal/vite registered for it: markup drawn by view helpers in its
+ * module and its relative imports) is assumed to be conditionally rendered
+ * and is not reported. A selector that does not
  * appear in the view (typo, or an element rendered elsewhere) is reported as
  * info on the first sweep, and escalated per the rule above.
  *
@@ -71,12 +73,18 @@ onReset(() => {
 
 const unref = (t: any) => { if (t && typeof t.unref === 'function') t.unref(); return t }
 
+/**
+ * The view's source, plus the words sygnal/vite registered for the component (its module's and
+ * its relative imports' string literals: markup a view helper draws), when it did
+ */
 function viewSource(component: any): string {
   const view = component && component.view
   if (typeof view !== 'function') return ''
   let src = viewTokens.get(view)
   if (src === undefined) {
     try { src = Function.prototype.toString.call(view) } catch (_) { src = '' }
+    const registered = (globalThis as any).__SYGNAL_VIEW_TOKENS__?.get?.(view)
+    if (typeof registered == 'string') src += '\n' + registered
     viewTokens.set(view, src as string)
   }
   return src as string

package/src/extra/diagnostics/checks/next.ts

@@ -66,6 +66,18 @@ function removed(component: any, name: string, anchor: string, detail?: string):
   })
 }
 
+/** SYG427: CHILD.select(x) with no component (an import of a name the module doesn't export) */
+function notComponent(f: any, x: any): void {
+  if (!once(`SYG427:${f.name}`)) return
+  const got = x === null ? 'null' : typeof x == 'object' ? 'an object' : String(x)
+  devReport('SYG427', {
+    component: f.name,
+    message: `${f.name}'s intent calls CHILD.select(${got}): that is not a component, so it never emits`,
+    fix: "Pass the child component itself, and check its import: a name its module doesn't export is undefined (Vitest runs on; the browser fails to link the module). Export it: export function Child() { … }",
+    data: {got},
+  })
+}
+
 /** the removed forms a definition shows (statics, view arity, model keys), once per function */
 let seenDefs = new WeakSet<object>()
 // G-332: resetChecks() forgets them (as the once() dedupe)
@@ -381,7 +393,11 @@ export function nextHooks(_api: any): any {
         get(t: any, k: any) {
           const v = t[k]
           if (k !== 'CHILD' || !v || typeof v.select != 'function') return v
-          return {...v, select: (x: any, ...r: any[]) => { if (typeof x == 'string') removed(f, f.name, 'child-select-name', `CHILD.select('${x}')`); return v.select(x, ...r) }}
+          return {...v, select: (x: any, ...r: any[]) => {
+            if (typeof x == 'string') removed(f, f.name, 'child-select-name', `CHILD.select('${x}')`)
+            else if (typeof x != 'function') notComponent(f, x)
+            return v.select(x, ...r)
+          }}
         },
       })
     },

package/src/extra/diagnostics/checks/persist.ts

@@ -6,7 +6,8 @@
  *          or restored. Under Vike's Layout/Wrapper shell (the `__vike` source) the message says
  *          persist isn't supported on Vike pages, layouts or wrappers yet.
  * SYG223 (warn)  — a `pick` / `omit` key of persist() that isn't a key of the component's
- *          `initialState` static (a typo: that key is never saved, or never left out).
+ *          `initialState` static or of its `uses` (a behavior's slice, such as a chat's), so it is
+ *          a typo: that key is never saved, or never left out.
  * Once per component name. Mechanism: onModel reads the static `view.persist` (the persist()
  * value carries its options) and `view.initialState`.
  */
@@ -38,7 +39,8 @@ export const persistCheck: DiagnosticCheck = {
     }
     const o = p.options, init = view.initialState
     if (!o || !init || typeof init != 'object') return
-    const keys = Object.keys(init)
+    // a behavior's slice (`uses = { chat: chat() }`) is a state key too
+    const keys = [...Object.keys(init), ...Object.keys(view.uses || {})]
     for (const opt of ['pick', 'omit']) {
       for (const k of Array.isArray(o[opt]) ? o[opt] : []) {
         if (keys.includes(k) || !once(`SYG223:${name}:${opt}:${k}`)) continue

package/src/extra/diagnostics/checks/wiring.ts

@@ -36,12 +36,20 @@ const underTest = (c: any) => {
   const dom = c?.sources?.[c.DOMSourceName || 'DOM']
   return !!dom && typeof dom == 'object' && '_hub' in dom
 }
-// G-620: an LLM / chat sink gets the chat driver's fix, not makeFetchDriver's
-const driverFix = (sink: string) =>
-  `Pass a driver named ${sink} to run(): ` + (/^(LLM|CHAT|AI|ASSISTANT)$/.test(sink)
-    ? `run(App, { ${sink}: makeChatDriver({ transport: openResponses({ baseURL: 'http://localhost:11434/v1', model: 'llama3.2' }) }) }) (from 'sygnal/ai'; uiMessageStream('/api/chat') for an AI SDK server)`
-    : `run(App, { ${sink}: makeFetchDriver() }) for HTTP, or driverFromAsync(fn) / your own driver`) +
-  `. Check the spelling against the drivers you pass`
+// G-620: the usual driver for a known sink name (an LLM / chat sink gets the chat driver's fix,
+// SW the service worker's), the generic text for any other name
+const DRIVER_FOR: Array<[RegExp, (sink: string) => string]> = [
+  [/^(LLM|CHAT|AI|ASSISTANT)$/, (s) => `run(App, { ${s}: makeChatDriver({ transport: openResponses({ baseURL: 'http://localhost:11434/v1', model: 'llama3.2' }) }) }) (from 'sygnal/ai'; uiMessageStream('/api/chat') for an AI SDK server)`],
+  [/^(SW|SERVICE_WORKER)$/, (s) => `run(App, { ${s}: makeServiceWorkerDriver('/sw.js', { enabled: import.meta.env.PROD }) }) (enabled: false keeps the driver, with no service worker, on a dev server)`],
+  [/^(HTTP|API|FETCH)$/, (s) => `run(App, { ${s}: makeFetchDriver() })`],
+  [/^(WS|SOCKET)$/, (s) => `run(App, { ${s}: makeSocketDriver() })`],
+]
+const driverFix = (sink: string) => {
+  const known = DRIVER_FOR.find(([re]) => re.test(sink))
+  return `Pass a driver named ${sink} to run(): ` +
+    (known ? known[1](sink) : `run(App, { ${sink}: makeFetchDriver() }) for HTTP, or driverFromAsync(fn) / your own driver`) +
+    `. Check the spelling against the drivers you pass`
+}
 
 export const wiringCheck: DiagnosticCheck = {
   id: 'wiring',

package/src/extra/diagnostics/codes.ts

@@ -278,6 +278,9 @@ export const CODE_TITLES: Record<string, string> = {
   SYG425: 'isolatedState slice lacks initialState keys',
   // PLAN-9 (D471): checks/next.ts; dev entry and sygnal-check
   SYG426: 'Deprecated lowercase marker tag',
+  // checks/next.ts and sygnal-check: a component reference that is not a function (an import of
+  // a name the module doesn't export is undefined under Vitest)
+  SYG427: 'CHILD.select() of something that is not a component',
   // PLAN-9 (D470): checks/next.ts; dev entry
   SYG453: 'Two children with the same identity share one instance',
   SYG601: "Retired in 6.0: Missing or invalid sources",
@@ -486,6 +489,8 @@ export const DEV_CODE_SEVERITY: Record<string, DiagnosticSeverity> = {
   SYG425: 'warn',
   // PLAN-9 (checks/next.ts): D471 a lowercase <collection> / <switchable> tag (deprecated in 6.3.0)
   SYG426: 'warn',
+  // checks/next.ts: CHILD.select(undefined), usually a missing export
+  SYG427: 'error',
   // PLAN-9 (checks/next.ts): D470 key identity, two children with one identity
   SYG453: 'warn',
   SYG612: 'error',

package/src/extra/pwa.ts

@@ -18,6 +18,8 @@ export interface ServiceWorkerCommand {
 
 export interface ServiceWorkerOptions {
   scope?: string;
+  /** false: register nothing, ignore commands, emit nothing (a dev server: `enabled: import.meta.env.PROD`) */
+  enabled?: boolean;
 }
 
 export interface InstallPrompt {
@@ -47,7 +49,7 @@ export function makeServiceWorkerDriver(
   return function serviceWorkerDriver(sink$: Stream<ServiceWorkerCommand>): ServiceWorkerSource {
     const events = new EventTarget();
 
-    if (typeof navigator !== 'undefined' && 'serviceWorker' in navigator) {
+    if (options.enabled !== false && typeof navigator !== 'undefined' && 'serviceWorker' in navigator) {
       navigator.serviceWorker
         .register(scriptUrl, {scope: options.scope})
         .then((reg) => {

package/src/extra/reducers.ts

@@ -5,6 +5,8 @@
  * shorthand factories for the most frequent reducer shapes.
  */
 
+import {ABORT, isAbort} from '../shared'
+
 // ── set() ──────────────────────────────────────────────────────────
 /**
  * Create a reducer that merges a partial update into state.
@@ -40,13 +42,17 @@ export function toggle<S = any>(field: keyof S & string): (state: S) => S {
 }
 
 // event(type, payload?) → EVENTS sink fn for the object form:
-// `ACTION: { EVENTS: event('TYPE', (state, data) => payload) }` (static payloads allowed)
+// `ACTION: { EVENTS: event('TYPE', (state, data) => payload) }` (static payloads allowed).
+// A payload function that returns ABORT sends nothing, as ABORT does from any other sink.
 export function event(
   type: string,
   payload?: any | ((state: any, data: any, next: Function, props: any) => any)
-): (state: any, data: any, next: Function, props: any) => { type: string; data: any } {
+): (state: any, data: any, next: Function, props: any) => { type: string; data: any } | typeof ABORT {
   return typeof payload === 'function'
-    ? (state, data, next, props) => ({ type, data: payload(state, data, next, props) })
+    ? (state, data, next, props) => {
+      const d = payload(state, data, next, props)
+      return isAbort(d) ? ABORT : { type, data: d }
+    }
     : () => ({ type, data: payload })
 }
 
@@ -66,6 +72,6 @@ export function event(
 export function emit(
   type: string,
   data?: any | ((state: any, actionData: any, next: Function, props: any) => any)
-): { EVENTS: (state: any, actionData: any, next: Function, props: any) => { type: string; data: any } } {
+): { EVENTS: (state: any, actionData: any, next: Function, props: any) => { type: string; data: any } | typeof ABORT } {
   return { EVENTS: event(type, data) }
 }

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
@@ -3005,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(

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'