sygnal 5.4.0 → 6.0.0

package/src/extra/diagnostics/index.ts

@@ -52,10 +52,11 @@
  *   The mode is resolved at module load, on every run() call and on every
  *   configureDiagnostics() call. `configureDiagnostics({ mode: undefined })`
  *   clears the explicit mode and falls back to steps 2-3.
- *   Every run() call is authoritative: it sets both the explicit mode and the
- *   ignore list from its `diagnostics` option, and run() WITHOUT the option
- *   resets them to the defaults (no explicit mode, empty ignore list), so a
- *   setting from an earlier run()/configureDiagnostics() does not leak in.
+ *   A run() call with the `diagnostics` option sets both the explicit mode and
+ *   the ignore list from it. run() WITHOUT the option resets them to the
+ *   defaults (no explicit mode, empty ignore list), so a setting from an earlier
+ *   run()/configureDiagnostics() does not leak in, unless another app is still
+ *   running (G-212: a second app or a custom element keeps the host's mode).
  *
  * --- Checks ---------------------------------------------------------------
  *
@@ -73,7 +74,7 @@
  *   A check that throws (other than a DiagnosticError from 'error' mode) is
  *   isolated: the exception is reported as SYG900 and other checks still run.
  *
- * --- Hooks (called from src/component.ts, marked `// [diagnostics hook]`) ----
+ * --- Hooks (dispatched by checks/next.ts from the core's hook layer) ----
  *
  *   onIntent(component, actionNames, selectorsUsed?)
  *     after intent is built. actionNames = keys of the intent object ([] for a
@@ -118,8 +119,9 @@
  *   `component` is the internal Component instance (stable identity per
  *   instance; `.name` is the component name).
  *
- *   Every hook starts with a single boolean check and returns immediately
- *   when the mode is 'off'.
+ *   In mode 'off' a hook only runs the checks registered with `always: true`
+ *   (internal: renderComponent's own bookkeeping, R2-3); none are registered
+ *   in an app, so the hooks do nothing.
  *
  *   Hooks NEVER throw synchronously into Sygnal's stream pipeline (a throw
  *   there would kill the state/view stream for good). Every exception from a
@@ -167,6 +169,8 @@ export interface DiagnosticsOptions {
 
 export interface DiagnosticCheck {
   id: string
+  /** internal: also runs when diagnostics are 'off' (renderComponent's harness hooks) */
+  always?: boolean
   onIntent?: (component: any, actionNames: string[], selectorsUsed: string[] | undefined) => void
   onModel?: (component: any, modelMap: Record<string, string[]>) => void
   onRender?: (component: any, rootVnode: any) => void
@@ -175,6 +179,12 @@ export interface DiagnosticCheck {
   onSelector?: (domSource: any, selector: string) => void
   onBusEmit?: (type: string, emitterName?: string) => void
   onBusSelect?: (type: string | string[] | undefined) => void
+  /**
+   * (additive, PLAN-2 E2) Called before a component's intent runs. May return a replacement
+   * for `sources` (e.g. a Proxy that reports or fakes a source with no driver); the intent
+   * gets the last one returned. See sourcesFor().
+   */
+  sources?: (component: any, sources: any) => any
 }
 
 export class DiagnosticError extends Error {
@@ -282,8 +292,8 @@ export function _setAsyncThrow(fn?: (err: any) => void): void {
 }
 
 const hook = (name: HookName) => (component: any, ...args: any[]): void => {
-  if (!enabled) return
   for (const check of checks) {
+    if (!enabled && !check.always) continue
     try {
       (check[name] as any)?.(component, ...args)
     } catch (err: any) {
@@ -312,8 +322,23 @@ export const onSelector: (domSource: any, selector: string) => void = hook('onSe
 export const onBusEmit: (type: string, emitterName?: string) => void = hook('onBusEmit')
 export const onBusSelect: (type: string | string[] | undefined) => void = hook('onBusSelect')
 
+/**
+ * (PLAN-2 E2) The sources object a component's intent is called with: `component.sources`,
+ * wrapped by every active check with a `sources` hook (the dev entry's SYG609 check,
+ * renderComponent's fake sources). Without such a check it is `component.sources` itself.
+ */
+export function sourcesFor(component: any): any {
+  let s = component.sources
+  for (const check of checks) {
+    if (!check.sources || (!enabled && !check.always)) continue
+    try { s = check.sources(component, s) || s } catch (_) {}
+  }
+  return s
+}
+
 // Bridge for the separately bundled 'sygnal/diagnostics' checks entry.
-;(globalThis as any).__SYGNAL_DIAGNOSTICS__ = { registerCheck, report }
+// PLAN-4.6 R4: the hook dispatchers too, for the dev entry's core adapter (checks/next.ts)
+;(globalThis as any).__SYGNAL_DIAGNOSTICS__ = { registerCheck, report, hooks: { onIntent, onModel, onRender, onReducer, onDispose, sourcesFor, on: isDiagnosticsEnabled } }
 
 export function _resetDiagnostics(): void {
   explicitMode = undefined

package/src/extra/diagnostics/legacy.ts

@@ -26,6 +26,14 @@
  * `.code` is the diagnostic code. It does not go through report(): the throw
  * itself is the signal, in every mode.
  *
+ * A call site that catches an exception and keeps running reports it with the
+ * core's caught() (src/core/runtime.ts: an error thrown by fail() under ITS code,
+ * G-027 / G-044), then the app's onError hook (callHook, PLAN-4 GS-11).
+ *
+ * `error` is also published on the core bridge
+ * (globalThis.__SYGNAL_DIAGNOSTICS__.error) for the separately bundled JSX
+ * runtime (SYG420).
+ *
  * (This comment is attached to the type-only import below so the TypeScript
  * emit drops it.)
  */
@@ -55,5 +63,14 @@ export const error = emit('error')
 export function fail(code: string, component: any, message: string, fix?: string): never {
   const err: any = new Error(formatDiagnostic(code, { component, message, fix }))
   err.code = code
+  err.sygnal = [component, message, fix]
   throw err
 }
+
+// PLAN-4 GS-11: the app's error hook (run(App, drivers, { onError })), reporting only (each app
+// has its own). A throwing hook is logged once and swallowed
+export const callHook = (hook: any, err: any, info: any): void => {
+  try { hook && hook(err, info) } catch (e) { console.error(e) }
+}
+
+;(globalThis as any).__SYGNAL_DIAGNOSTICS__.error = error

package/src/extra/driverFactories.ts

@@ -1,4 +1,5 @@
 import xs, {Stream} from 'xstream';
+import {senderOf, allowed, makeReplies} from './replies';
 
 interface DriverFromAsyncOptions {
   selector?: string;
@@ -15,7 +16,9 @@ interface DriverFromAsyncOptions {
  * by `args`, after `pre`). The resolved value, after `post`, is delivered as
  * `{ [return]: value, [selector]: request[selector] }` (defaults:
  * `{ value, category }`) and read with `source.select(category)`. A promise
- * that resolves to `null`/`undefined` is delivered the same way.
+ * that resolves to `null`/`undefined` is delivered the same way. Replies that
+ * resolve before any `select()` listener exists (a BOOTSTRAP request, say) are
+ * held and delivered once the first one subscribes.
  *
  * Errors: if the function's promise (or a promise returned by `post`)
  * rejects, or `post` throws, the error is delivered on `source.errors()`,
@@ -31,13 +34,21 @@ interface DriverFromAsyncOptions {
  *
  * `errors(selector?)` filters like `select()`: no argument = all errors, a
  * string matches the request's selector property, a function is a predicate on
- * the error payload. While nothing listens to `errors()`, failures are only
- * logged with console.error (the pre-existing behavior).
+ * the error payload. An error no errors() listener matches is logged with
+ * console.error. Errors that occur before the first errors() listener
+ * subscribes (a BOOTSTRAP request) are held like early replies.
+ *
+ * Reply actions (PLAN-3): a request object a component sends with `ok` /
+ * `error` action names gets its outcome as that action, on exactly the sending
+ * instance (never on select()/errors()): `ok` data is the resolved value (after
+ * `post`), `error` data `{ error, request }`. A request naming only one of them
+ * sends the other outcome down select()/errors(). A reply for a disposed
+ * instance is dropped. Requests with a `then` / `catch` key are refused (SYG610).
  */
 function driverFromAsync(
   promiseReturningFunction: (...args: any[]) => Promise<any>,
   opts: DriverFromAsyncOptions = {}
-): (fromApp$: Stream<any>) => {select: (selector?: any) => Stream<any>; errors: (selector?: any) => Stream<any>} {
+): (fromApp$: Stream<any>) => {select: (selector?: any) => Stream<any>; errors: (selector?: any) => Stream<any>; [k: string]: any} {
   const {
     selector: selectorProperty = 'category',
     args: functionArgs = 'value',
@@ -65,13 +76,41 @@ function driverFromAsync(
   }
 
   return (fromApp$: Stream<any>) => {
+    // G-069: a reply can resolve before anything has subscribed to select() (e.g. a
+    // BOOTSTRAP request to an instantly-resolving promise under run()). Such replies are
+    // buffered (at most EARLY_REPLY_LIMIT, oldest dropped) until the first select()
+    // listener subscribes, then delivered in order on a microtask, so every select()
+    // wired in the same pass sees them. After that, a reply that arrives while no one
+    // listens is dropped, as with any xstream source.
+    const EARLY_REPLY_LIMIT = 100;
     let sendFn: ((val: any) => void) | null = null;
+    let started = false;
+    let pending: any[] = [];
+    const flush = () => {
+      const queued = pending;
+      pending = [];
+      queued.forEach(reply => sendFn?.(reply));
+    };
+    const deliver = (reply: any) => {
+      if (!started || pending.length > 0) {
+        pending.push(reply);
+        if (pending.length > EARLY_REPLY_LIMIT) pending.shift();
+        return;
+      }
+      sendFn?.(reply);
+    };
 
     const toApp$ = xs.create<any>({
       start: (listener) => {
         sendFn = listener.next.bind(listener);
+        if (!started) {
+          started = true;
+          if (pending.length > 0) queueMicrotask(flush);
+        }
+      },
+      stop: () => {
+        sendFn = null;
       },
-      stop: () => {},
     });
 
     // Active errors(selector) streams (1H-6): an error goes to the ones it matches, and is
@@ -82,13 +121,43 @@ function driverFromAsync(
       (typeof selector === 'function' ? selector(val) : val?.[selectorProperty] === selector);
     const filterBy = (stream: Stream<any>, selector?: any) =>
       selector === undefined ? stream : stream.filter((val: any) => matches(selector, val));
+    const errMsg = `Error in driver created using driverFromAsync(${functionName})`;
+    const dispatchError = (val: any) => {
+      let handled = false;
+      errorSubs.forEach(sub => {
+        let hit = false;
+        try { hit = matches(sub.selector, val); } catch (_) {}
+        if (hit) {
+          handled = true;
+          sub.listener.next(val);
+        }
+      });
+      if (!handled) console.error(`${errMsg}: ${val.error}`);
+    };
+    // G-092: like early replies, errors that occur before the first errors() listener
+    // subscribes are held (same limit) and dispatched on a microtask once it does. If
+    // nothing has subscribed by the next macrotask, they are dispatched (i.e. logged) then.
+    let errStarted = false;
+    let pendingErrors: any[] = [];
+    const flushErrors = () => {
+      errStarted = true;
+      const queued = pendingErrors;
+      pendingErrors = [];
+      queued.forEach(dispatchError);
+    };
 
     // 3E/R11: set by the source's dispose(), which Cycle's engine calls on teardown just
     // before it completes the sink proxies; that completion is expected, not worth a warning.
     let disposing = false;
+    const {replies, reply} = makeReplies();
 
     fromApp$.addListener({
       next: (incoming: any) => {
+        const isObject = typeof incoming === 'object' && incoming !== null;
+        if (isObject && !allowed(incoming, `driverFromAsync(${functionName})`)) return;
+        const sender = isObject ? senderOf(incoming) : undefined;
+        const ok = sender !== undefined && incoming.ok;
+        const error = sender !== undefined && incoming.error;
         const preProcessed = preFunction(incoming);
         let argArr: any[] = [];
         if (typeof preProcessed === 'object' && preProcessed !== null) {
@@ -103,7 +172,6 @@ function driverFromAsync(
             argArr = functionArgs.map((arg: string) => preProcessed[arg]);
           }
         }
-        const errMsg = `Error in driver created using driverFromAsync(${functionName})`;
         const constructReply = (rawVal: any) => {
           let outgoing: any;
           if (returnProperty === undefined) {
@@ -130,17 +198,11 @@ function driverFromAsync(
         // Rejections (of the function, a thenable it resolves to, or post()) go to errors();
         // an error no active errors() selector matches is logged, as before.
         const reportError = (err: any) => {
+          if (error) return reply(sender, error, {error: err, request: incoming});
           const val = {error: err, [selectorProperty]: incoming?.[selectorProperty], request: incoming};
-          let handled = false;
-          errorSubs.forEach(sub => {
-            let hit = false;
-            try { hit = matches(sub.selector, val); } catch (_) {}
-            if (hit) {
-              handled = true;
-              sub.listener.next(val);
-            }
-          });
-          if (!handled) console.error(`${errMsg}: ${err}`);
+          if (errStarted) return dispatchError(val);
+          if (pendingErrors.push(val) === 1) setTimeout(flushErrors);
+          if (pendingErrors.length > EARLY_REPLY_LIMIT) pendingErrors.shift();
         };
         const isThenable = (val: any) => val != null && typeof val.then === 'function';
         promiseReturningFunction(...argArr)
@@ -149,10 +211,10 @@ function driverFromAsync(
               ? innerVal.then((innerOutgoing: any) => postFunction(innerOutgoing, incoming))
               : postFunction(innerVal, incoming)
           )
-          .then(constructReply)
-          .then((reply: any) => {
+          .then((val: any) => (ok ? val : constructReply(val)))
+          .then((outgoing: any) => {
             try {
-              sendFn!(reply);
+              ok ? reply(sender, ok, outgoing) : deliver(outgoing);
             } catch (err) {
               console.error(`${errMsg}: ${err}`);
             }
@@ -177,11 +239,13 @@ function driverFromAsync(
         disposing = true;
       },
       select: (selector?: any) => filterBy(toApp$, selector),
+      ...replies,
       errors: (selector?: any) => {
         let sub: any;
         return xs.create<any>({
           start: (listener) => {
             errorSubs.add((sub = {listener, selector}));
+            if (!errStarted) queueMicrotask(flushErrors);
           },
           stop: () => {
             errorSubs.delete(sub);

package/src/extra/elementCommands.ts

@@ -0,0 +1,53 @@
+/*
+ * PLAN-4 GS-2: element commands, the built-in ELEMENT sink.
+ *
+ *   SUBMIT:    { STATE: validate, ELEMENT: (s) => (s.errors.email ? { focus: Email } : ABORT) },
+ *   OPEN_HELP: { ELEMENT: { showModal: HelpDialog } },
+ *
+ * A command is `{ <method>: target, ...options }`: the FIRST key is the method, the other keys
+ * are its options (D118); an array sends several, in order. The target (a control or a
+ * selector) is resolved in the SENDING instance's own DOM source, so isolation applies (a
+ * Collection item reaches only its own elements; a parent doesn't reach its children's).
+ *
+ * The method: D102 first, a control whose spec object declares `commands` runs
+ * `commands[method](element, options)` (it overrides a native method of the same name; only the
+ * control itself carries a spec, a template-string selector doesn't). A widget host
+ * (src/extra/widget.ts) carries its widget's commands, which win the same way for a selector
+ * target (PLAN-5 D196: `{ focus: '.editor' }` runs the widget's `focus`). Then the element's own
+ * method: `close` gets `returnValue` as its argument (D118), `togglePopover` its `force` (a
+ * boolean, or no argument: a browser that only takes a boolean treats an object as true), every
+ * other method the options object (focus { preventScroll }, scrollIntoView { block, inline,
+ * behavior }, blur, select, click, showModal, show, showPopover, hidePopover; also play, pause, showPicker,
+ * requestSubmit, reset...). The core runs any method the element has (no list: it
+ * would cost ~60 B); the dev entry reports the ones that change the DOM Sygnal renders (SYG641).
+ *
+ * Timing: a command runs once the render it may depend on is on the page. The instance's DOM
+ * source emits after every DOM mutation of the app (a patch), so the command runs in a microtask
+ * after the next patch at which its target exists. When no patch comes (the action changed
+ * nothing that renders), it runs at the first 16 ms check instead; the checks repeat every 16 ms
+ * while the target is missing, about 1 s, then it is given up (SYG640 in dev). A disposed
+ * instance's pending commands are dropped. Without a DOM source nothing runs (SSR renders views
+ * without instances); a null command is skipped (ABORT is the way to send nothing).
+ *
+ * Failures (no match: SYG640; neither a spec command nor an element method: SYG641) go to the
+ * 'sygnal/diagnostics' dev entry through the core bridge (`elementCommand`), which words them;
+ * the core carries no message text. In production a failed command does nothing.
+ */
+export function runElementCommands(c: any, cmds: any): void {
+  const dom = c.sources[c.DOMSourceName];
+  if (dom) for (const cmd of ([] as any[]).concat(cmds)) if (cmd) {
+    const m = Object.keys(cmd)[0], {[m]: t, ...o} = cmd, s = dom.select('' + t).elements();
+    let els: any, n = 0, k = 0, l: any;
+    const run = (last?: any) => {
+      const e = !c._disposed && els?.[0], f = t?.spec?.commands?.[m] || e?.__sw?.w.commands[m];
+      if (!l || !e && !last) return;
+      s.removeListener(l);
+      clearInterval(i);
+      l = 0;
+      e && (f || e[m]) ? f ? f(e, o) : e[m](m == 'close' ? o.returnValue : m == 'togglePopover' ? o.force : o)
+        : (globalThis as any).__SYGNAL_DIAGNOSTICS__?.elementCommand?.(c, cmd, e);
+    }, i = setInterval(() => run(++k > 62), 16);
+    // the first value (the DOM as it is now) is skipped; the next ones follow a patch
+    s.addListener(l = {next: (x: any) => { els = x; n++ && queueMicrotask(run); }});
+  }
+}