sygnal 5.4.0 → 6.0.0

package/src/cycle/state/objIsEqual.ts

@@ -0,0 +1,50 @@
+/** Structural equality (to depth 5): the core's state/props/context diffing and STATE.watch (GS-6) */
+export function objIsEqual(obj1: any, obj2?: any, maxDepth: number = 5, depth: number = 0): boolean {
+  // Past maxDepth the values count as different (false): the caller then treats them as changed
+  if (depth > maxDepth) {
+      return false;
+  }
+
+  // If both are the same object or are both exactly null or undefined
+  if (obj1 === obj2) {
+      return true;
+  }
+
+  // If either is not an object (null, undefined, or primitive), directly compare
+  if (typeof obj1 !== 'object' || obj1 === null || typeof obj2 !== 'object' || obj2 === null) {
+      return false;
+  }
+
+  // Special handling for arrays
+  if (Array.isArray(obj1) && Array.isArray(obj2)) {
+    if (obj1.length !== obj2.length) {
+        return false;
+    }
+    for (let i = 0; i < obj1.length; i++) {
+        if (!objIsEqual(obj1[i], obj2[i], maxDepth, depth + 1)) {
+            return false;
+        }
+    }
+    return true;
+  }
+
+  // Get keys of both objects
+  const keys1 = Object.keys(obj1);
+
+  // Check if the number of properties is different
+  if (keys1.length !== Object.keys(obj2).length) {
+      return false;
+  }
+
+  // Recursively check each property
+  for (const key of keys1) {
+      if (!(key in obj2)) {
+          return false;
+      }
+      if (!objIsEqual(obj1[key], obj2[key], maxDepth, depth + 1)) {
+          return false;
+      }
+  }
+
+  return true;
+}

package/src/cycle/state/types.ts

@@ -9,14 +9,4 @@ export type Lens<T, R> = {
   get: Getter<T, R>;
   set: Setter<T, R>;
 };
-export type ItemScopeFn = (key: string) => string | object;
-export type ItemKeyFn<S> = (state: S, index?: number) => string;
-export type ItemFactoryFn<S, So, Si> = (
-  state: S,
-  index?: number
-) => MainFn<So, Si>;
 export type Scope<T, R> = string | number | Lens<T, R>;
-export type InternalInstances<Si> = {
-  dict: Map<string, Si>;
-  arr: Array<Si & {_key: string}>;
-};

package/src/defineComponent.ts

@@ -0,0 +1,34 @@
+/**
+ * PLAN-4.6 (D162): `defineComponent(opts)` builds a component from an options object, for code
+ * that makes components from data (generators, wrappers). It returns an ordinary function
+ * component: a new function that calls `view` with the one view argument, with the other options
+ * assigned as its statics. There is no separate instantiation path: the core reads the statics
+ * like any function component's.
+ *
+ *   const Counter = defineComponent({ name: 'Counter', view, intent, model, initialState: { n: 0 } })
+ *
+ * `name` becomes `componentName` (diagnostics, devtools, uid()); without it, the view's
+ * componentName or function name (G-343: not the `view` an inline `view: () => …` is given;
+ * 'Component' then). Statics already on the view are copied, and the options override them. The
+ * view function itself is not changed, so one view can back several definitions; the dev checks
+ * read it from `__sygnalView` (its arity: positional views).
+ */
+export function defineComponent(opts: Record<string, any>): any {
+  if (!opts || typeof opts !== 'object') {
+    throw new TypeError('defineComponent(opts): pass an options object, e.g. defineComponent({ view, model, initialState })')
+  }
+  const {view, name, ...statics} = opts
+  if (typeof view !== 'function') {
+    throw new TypeError(`defineComponent(${name ? `{ name: '${name}' }` : 'opts'}): view must be a function (the view: ({ state, context, ...props }) => vnode)`)
+  }
+  const C: any = (args: any) => view(args)
+  for (const k of Object.keys(view)) C[k] = view[k]
+  const componentName = name || view.componentName || (view.name && view.name != 'view' ? view.name : 'Component')
+  C.componentName = componentName
+  try { Object.defineProperty(C, 'name', {value: componentName, configurable: true}) } catch (_) { /* name not configurable */ }
+  for (const k of Object.keys(statics)) if (statics[k] !== undefined) C[k] = statics[k]
+  Object.defineProperty(C, '__sygnalView', {value: view.__sygnalView || view, configurable: true})
+  return C
+}
+
+export default defineComponent

package/src/devtools.d.ts

@@ -0,0 +1,151 @@
+// 'sygnal/devtools' (D77): importing it installs the DevTools bridge
+// (window.__SYGNAL_DEVTOOLS__) in a browser, for the Sygnal DevTools extension.
+// Dev only: sygnal/vite injects it in dev; without Vite, import it before run().
+// Self-contained (like the other dev entries' types); the same shape as
+// SygnalDevTools in 'sygnal'.
+// PLAN-4 3-E (GS-10): it also records the action log and writes "Copy as test" tests.
+
+export interface SygnalDevTools {
+  /** true while the browser extension is connected */
+  readonly connected: boolean
+  /** Diagnostics collected so far (same as getDiagnostics() from 'sygnal') */
+  getDiagnostics(): Array<{ code: string; severity: string; message: string; [key: string]: any }>
+  /** The app graph; present only when the 'sygnal/diagnostics' dev entry is loaded */
+  inspect?(): any
+  /** PLAN-4 3-E: defaults for "Copy as test" from the extension panel (componentImport, drivers, ...) */
+  configureCopyAsTest(options: CopyAsTestOptions): void
+  /** PLAN-4 3-E: one instance's recorded session (as getSession()) */
+  getSession(target?: Exclude<SessionTarget, SessionRecording>): SessionRecording
+}
+
+/** The bridge singleton of this entry (also window.__SYGNAL_DEVTOOLS__ once installed). */
+export declare function getDevTools(): SygnalDevTools
+/** Install the bridge (done on import; idempotent). Undefined outside a browser. */
+export declare function installDevTools(): SygnalDevTools | undefined
+
+// ── PLAN-4 3-E (GS-10): the action log, "Copy as test", the Redux DevTools bridge ──
+
+export type DevtoolsActionCause = 'intent' | 'next' | 'reply' | 'built-in' | 'simulateAction' | 'behavior'
+
+/** One recorded action (the entry records every component instance's actions) */
+export interface DevtoolsAction {
+  /** Sequence number (session-wide) */
+  seq: number
+  /** The action name (a behavior's actions are namespaced, `pager.NEXT`) */
+  type: string
+  /** Its data, as the model got it (a DOM event for a DOM intent stream) */
+  data: any
+  /** The component's name */
+  component: string
+  /** The instance's id */
+  instance: string
+  /** The parent instance's id (null: a root) */
+  parent: string | null
+  /** Sinks that produced a value for it (live: STATE fills in when its reducer runs) */
+  sinks: string[]
+  cause: DevtoolsActionCause
+  /** ms since the session started */
+  at: number
+  /** The instance's state before / after the action's STATE reducer, when it changed the state */
+  before?: any
+  after?: any
+  /** A reply action (or RESOURCE): the source that delivered it; 'fetch' when it is makeFetchDriver's */
+  replySink?: string
+  replyKind?: 'fetch' | 'other'
+  /** An intent action whose data is the instance's own state (an intent over STATE.stream) */
+  echo?: true
+}
+
+export interface ActionFilter {
+  component?: string
+  instance?: string | number
+  type?: string | RegExp
+  cause?: DevtoolsActionCause | DevtoolsActionCause[]
+}
+
+/** One instance's recorded session, as plain data (what copyAsTest() writes the test from) */
+export interface SessionRecording {
+  version: 1
+  component: string
+  instance: string
+  /** The state when the session started for this instance */
+  initialState?: any
+  /** The component's own initialState (renderComponent's default) */
+  definitionInitialState?: any
+  finalState: any
+  /** The action names the component can be sent (model keys, behavior actions) */
+  actionNames?: string[]
+  /** Source names beyond DOM / EVENTS / STATE / LOG / CHILD / PARENT / READY */
+  drivers: string[]
+  /** Those of `drivers` renderComponent fakes (makeFetchDriver sources) */
+  fakeable: string[]
+  /** The instance's own actions, in order */
+  actions: Array<Pick<DevtoolsAction, 'type' | 'data' | 'cause' | 'sinks' | 'at' | 'replySink' | 'replyKind' | 'echo'>>
+  /** State changes in descendant instances a replay at this instance can't reproduce */
+  foreign: Array<{ type: string; component: string; instance: string; cause: DevtoolsActionCause }>
+  truncated?: boolean
+}
+
+export interface CopyAsTestOptions {
+  /** The import line(s) for the component (default: `import <Name> from './<Name>.js'`) */
+  componentImport?: string
+  /** The component's identifier in the test (default: its recorded name) */
+  componentName?: string
+  /** More import lines (drivers, helpers) */
+  imports?: string[]
+  /** Drivers for renderComponent, as source code by sink name: { DND: 'mockDragDriver().driver' } */
+  drivers?: Record<string, string>
+  /** More renderComponent options, as source code: 'strict: true' */
+  renderOptions?: string
+  /** The test's name */
+  testName?: string
+  /** Adds a `// @vitest-environment <env>` first line */
+  environment?: string
+}
+
+export interface CopyAsTestResult {
+  /** The test file */
+  code: string
+  /** true when the test asserts the final state */
+  complete: boolean
+  /** What was left out and why (also comments in the code) */
+  warnings: string[]
+  /** Actions written as simulateAction / t.respond / t.fail */
+  replayed: number
+}
+
+/**
+ * What a session is taken from: undefined (the newest root), an instance id, a component, run()'s
+ * result, or a SessionRecording from getSession()
+ */
+export type SessionTarget = undefined | string | number | ((...args: any[]) => any) | { sources: any } | SessionRecording
+
+/** Start recording (done on import in a browser; idempotent). Returns a function that stops it. */
+export declare function recordActions(): () => void
+/** true while the action log records */
+export declare function isRecording(): boolean
+/** Start a new session: forget the recorded actions */
+export declare function clearActions(): void
+/** The session's actions, oldest first, optionally filtered */
+export declare function getActions(filter?: ActionFilter): DevtoolsAction[]
+/** Subscribe to the log; returns unsubscribe */
+export declare function onAction(fn: (action: DevtoolsAction | null, kind: 'add' | 'update' | 'reset') => void): () => void
+/** One instance's session as plain data */
+export declare function getSession(target?: Exclude<SessionTarget, SessionRecording>): SessionRecording
+/** "Copy as test": a Vitest + renderComponent test that replays the session */
+export declare function copyAsTest(target?: SessionTarget, options?: CopyAsTestOptions): string
+/** "Copy as test", with what it left out */
+export declare function copyAsTestResult(target?: SessionTarget, options?: CopyAsTestOptions): CopyAsTestResult
+
+export interface ReduxDevtoolsOptions {
+  /** The instance name in the extension (default 'Sygnal') */
+  name?: string
+  /** Which actions to send (default: all but 'built-in' ones) */
+  filter?: (action: DevtoolsAction) => boolean
+}
+/**
+ * Send the recorded actions and the root's state to the Redux DevTools extension
+ * (window.__REDUX_DEVTOOLS_EXTENSION__); jump to state / action replaces the root's state.
+ * Returns a disconnect function (a no-op without the extension).
+ */
+export declare function connectReduxDevtools(target?: Exclude<SessionTarget, SessionRecording>, options?: ReduxDevtoolsOptions): () => void

package/src/devtools.ts

@@ -0,0 +1,34 @@
+// 'sygnal/devtools' (D77): the DevTools bridge for the browser extension, a dev-only
+// entry. Importing it installs window.__SYGNAL_DEVTOOLS__ (run() did this before 6.0),
+// so import it before run(): components created earlier are not in the tree.
+// sygnal/vite injects it in dev (`vite`, not `vite build`); opt out with
+// sygnal({ devtools: false }). Production builds never contain it.
+// PLAN-4 3-E (GS-10): it also records the action log (in a browser on import; elsewhere
+// after recordActions()), and turns a session into a renderComponent test (copyAsTest).
+import {installDevTools} from './extra/devtools'
+import {getSession, isRecording} from './extra/devtoolsActions'
+import type {SessionRecording} from './extra/devtoolsActions'
+import {sessionToTest} from './extra/copyAsTest'
+import type {CopyAsTestOptions, CopyAsTestResult} from './extra/copyAsTest'
+
+installDevTools()
+
+export {getDevTools, installDevTools} from './extra/devtools'
+export {recordActions, clearActions, getActions, onAction, getSession, isRecording} from './extra/devtoolsActions'
+export {connectReduxDevtools} from './extra/reduxDevtools'
+
+const isSession = (x: any): x is SessionRecording => !!x && typeof x == 'object' && x.version === 1 && Array.isArray(x.actions)
+
+/**
+ * "Copy as test", with what was left out: the session of `target` (undefined: the newest root;
+ * an instance id; a component; run()'s result; or a SessionRecording from getSession()).
+ */
+export function copyAsTestResult(target?: any, options?: CopyAsTestOptions): CopyAsTestResult {
+  if (!isSession(target) && !isRecording()) throw new Error('[Sygnal DevTools] copyAsTest: nothing was recorded: import sygnal/devtools before run() (in a browser), or call recordActions() first')
+  return sessionToTest(isSession(target) ? target : getSession(target), options)
+}
+
+/** "Copy as test": a Vitest + renderComponent test replaying the recorded session (see copyAsTestResult). */
+export function copyAsTest(target?: any, options?: CopyAsTestOptions): string {
+  return copyAsTestResult(target, options).code
+}

package/src/element.d.ts

@@ -0,0 +1,59 @@
+// 'sygnal/element' (PLAN-4 GS-13, D127): publish a Sygnal component as a custom element.
+// Self-contained (like the other entries' types).
+
+export type ElementPropType =
+  | StringConstructor
+  | NumberConstructor
+  | BooleanConstructor
+  | ObjectConstructor
+  | ArrayConstructor
+
+/** The property type a prop declaration gives (attributes are parsed to it). */
+export type ElementPropValue<T> =
+  T extends BooleanConstructor ? boolean :
+  T extends NumberConstructor ? number | undefined :
+  T extends StringConstructor ? string | undefined :
+  T extends ArrayConstructor ? any[] | undefined :
+  T extends ObjectConstructor ? Record<string, any> | undefined :
+  never
+
+/** The element's prop properties for a `props` option (an array means all String). */
+export type ElementProps<P> =
+  P extends readonly (infer K extends string)[] ? { [N in K]: string | undefined } :
+  P extends Record<string, ElementPropType> ? { -readonly [N in keyof P]: ElementPropValue<P[N]> } :
+  {}
+
+export interface ElementOptions<P extends readonly string[] | Record<string, ElementPropType> = readonly string[] | Record<string, ElementPropType>> {
+  /**
+   * Properties fed into state: camelCase names; each also has a kebab-case attribute
+   * (`dueDate` ↔ `due-date`). String/Number attributes are parsed, Boolean is presence,
+   * Object/Array are JSON. An array of names means all String.
+   */
+  props?: P
+  /**
+   * Sink name → CustomEvent name, e.g. `{ PARENT: 'task-picked' }`. The event bubbles and is
+   * composed; `detail` is the sink's value. Use lowercase names (React 19 listens with
+   * `on<exact-name>`, e.g. `ontask-picked`). DOM, STATE and EVENTS can't be used.
+   */
+  events?: Record<string, string>
+  /** Render into a shadow root (true = 'open') */
+  shadow?: boolean | 'open' | 'closed'
+  /** Adopted into the shadow root, shared by every instance (ignored without shadow) */
+  styles?: string | CSSStyleSheet | Array<string | CSSStyleSheet>
+}
+
+export interface SygnalElementConstructor<P = {}> {
+  new (): HTMLElement & ElementProps<P>
+  prototype: HTMLElement & ElementProps<P>
+  readonly observedAttributes: string[]
+}
+
+/**
+ * Define `tag` as a custom element that runs `Component` (a plain function component) as
+ * its own app. Define it before a host framework renders the tag, so props arrive as
+ * properties. Calling it again for the same tag hot-swaps the component in every live
+ * element, keeping each one's state (HMR), and returns the same constructor.
+ */
+export declare function defineElement<
+  const P extends readonly string[] | Record<string, ElementPropType> = {}
+>(tag: string, Component: (...args: any[]) => any, options?: ElementOptions<P>): SygnalElementConstructor<P>

package/src/element.ts

@@ -0,0 +1,235 @@
+// 'sygnal/element' (PLAN-4 GS-13, D127): publish a Sygnal component as a custom element.
+//
+//   defineElement('task-board', TaskBoard, {
+//     props: { title: String, tasks: Array, readonly: Boolean },  // or ['a', 'b'] (all String)
+//     events: { PARENT: 'task-picked' },                          // sink name → CustomEvent name
+//     shadow: true,                                               // true | 'open' | 'closed'
+//     styles: '.title { color: green }',                          // string | CSSStyleSheet | array
+//   })
+//
+// Each connected element is its own app: run(Component) mounted on a div inside the element
+// (or its shadow root). Props are in state from the first render (the component's
+// initialState, overlaid with the props); later property/attribute changes are merged into
+// state. Sinks listed in `events` are dispatched as CustomEvents (bubbles + composed; the
+// PARENT wrapper is unwrapped to its value). Removing the element disposes the app; a move
+// (disconnect + connect in the same task) keeps it running. Calling defineElement again for
+// the same tag (HMR) swaps the component in every live element, keeping each one's state.
+//
+// Separate entry: rollup rewrites './index' to the external 'sygnal' (0 B in the core bundle).
+import {run} from './index';
+import {owned} from './extra/owned';
+
+export type ElementPropType =
+  | StringConstructor
+  | NumberConstructor
+  | BooleanConstructor
+  | ObjectConstructor
+  | ArrayConstructor;
+
+export interface ElementOptions {
+  /** Properties fed into state (camelCase; the attribute is kebab-case). An array means all String. */
+  props?: readonly string[] | Record<string, ElementPropType>;
+  /** Sink name → CustomEvent name, e.g. { PARENT: 'task-picked' } */
+  events?: Record<string, string>;
+  /** Render into a shadow root (true = 'open') */
+  shadow?: boolean | 'open' | 'closed';
+  /** Adopted into the shadow root, shared by every instance (ignored without shadow) */
+  styles?: string | CSSStyleSheet | Array<string | CSSStyleSheet>;
+}
+
+// Sinks that are the app's own drivers, never events
+const RESERVED_SINKS = ['DOM', 'STATE', 'EVENTS'];
+
+// Hot-swap functions of the tags this module defined
+const swaps = new WeakMap<CustomElementConstructor, (Component: any) => void>();
+
+const kebab = (name: string) => name.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+
+function parseAttribute(type: ElementPropType, value: string | null): any {
+  if (type === Boolean) return value !== null;
+  if (value === null) return undefined;
+  if (type === Number) return Number(value);
+  if (type === String) return value;
+  return JSON.parse(value); // Object, Array (throws on bad JSON)
+}
+
+function toSheet(style: string | CSSStyleSheet): CSSStyleSheet {
+  if (typeof style !== 'string') return style;
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(style);
+  return sheet;
+}
+
+const devMode = () => (globalThis as any).__SYGNAL_DEV__ === true;
+
+export function defineElement(tag: string, Component: any, options: ElementOptions = {}): CustomElementConstructor {
+  const prior = customElements.get(tag);
+  const swap = prior && swaps.get(prior);
+  if (swap) {
+    swap(Component); // HMR: the defining module ran again
+    return prior!;
+  }
+  if (typeof Component !== 'function') {
+    throw new TypeError(`defineElement('${tag}'): pass a function component`);
+  }
+
+  const types: Record<string, ElementPropType> = Array.isArray(options.props)
+    ? Object.fromEntries(options.props.map((name: string) => [name, String]))
+    : {...(options.props as Record<string, ElementPropType> | undefined)};
+  const propOfAttribute: Record<string, string> = Object.fromEntries(Object.keys(types).map((name) => [kebab(name), name]));
+  const events = {...options.events};
+  for (const sink of RESERVED_SINKS) {
+    if (sink in events) throw new TypeError(`defineElement('${tag}'): '${sink}' is a driver of the element's app, not an event sink`);
+  }
+  const shadowMode = options.shadow ? (options.shadow === 'closed' ? 'closed' : 'open') : undefined;
+  const sheets = shadowMode ? ([] as Array<string | CSSStyleSheet>).concat(options.styles || []).map(toSheet) : [];
+  // Props that hide a member of HTMLElement (e.g. title, hidden): SYG644 once per tag (D131)
+  const shadowedMembers = Object.keys(types).filter((name) => name in HTMLElement.prototype);
+  let warned = false;
+
+  const live = new Set<SygnalElement>();
+  let instances = 0;
+
+  class SygnalElement extends HTMLElement {
+    static observedAttributes = Object.keys(propOfAttribute);
+
+    #props: Record<string, any> = {};
+    #app: any = undefined;
+    #root: HTMLElement | ShadowRoot = this;
+    #uid = `${tag}-${++instances}`;
+
+    static {
+      for (const name of Object.keys(types)) {
+        Object.defineProperty(this.prototype, name, {
+          configurable: true,
+          enumerable: true,
+          get(this: SygnalElement) {
+            return this.#props[name];
+          },
+          set(this: SygnalElement, value: any) {
+            this.#setProp(name, value);
+          },
+        });
+      }
+      swaps.set(this, (Next: any) => {
+        Component = Next;
+        live.forEach((element) => element.#swap());
+      });
+    }
+
+    constructor() {
+      super();
+      if (shadowMode) {
+        const root = this.attachShadow({mode: shadowMode});
+        root.adoptedStyleSheets = sheets;
+        this.#root = root;
+      }
+      // Properties set before the tag was defined are own properties that hide the
+      // accessors: move them onto the accessors
+      for (const name of Object.keys(types)) {
+        if (Object.prototype.hasOwnProperty.call(this, name)) {
+          const value = (this as any)[name];
+          delete (this as any)[name];
+          this.#setProp(name, value);
+        }
+      }
+    }
+
+    attributeChangedCallback(attribute: string, _old: string | null, value: string | null) {
+      const name = propOfAttribute[attribute];
+      try {
+        this.#setProp(name, parseAttribute(types[name], value));
+      } catch (_) {
+        // bad JSON in an Object/Array attribute: keep the previous value
+      }
+    }
+
+    connectedCallback() {
+      if (this.#app) return; // moved, not removed: keep running
+      // (G-216: a hot swap elsewhere on the page is that app's own, so no need to wait it out)
+      if (shadowedMembers.length && !warned) {
+        // D131: SYG644 through the diagnostics core when diagnostics are on; else a console
+        // warning in dev
+        const message = `props hide the HTMLElement members of the same name (${shadowedMembers.join(', ')})`;
+        const fix = 'Rename them to keep the native behaviour';
+        let reported: any;
+        try {
+          reported = (globalThis as any).__SYGNAL_DIAGNOSTICS__?.report('SYG644', {
+            severity: 'warn', component: `<${tag}>`, message, fix, data: {tag, members: shadowedMembers},
+          });
+        } catch (e) {
+          reported = true; // mode 'error': thrown after the element starts
+          queueMicrotask(() => { throw e; });
+        }
+        if (reported || devMode()) warned = true;
+        if (!reported && devMode()) console.warn(`[sygnal/element] <${tag}>: ${message}. ${fix}.`);
+      }
+      const mount = document.createElement('div');
+      this.#root.appendChild(mount);
+      this.#app = run(this.#component(), this.#eventDrivers(), {mountPoint: mount as any, uid: this.#uid});
+      this.#releaseDevtools();
+      live.add(this);
+    }
+
+    disconnectedCallback() {
+      // Deferred: a move is a disconnect + connect in the same task
+      queueMicrotask(() => {
+        if (this.isConnected || !this.#app) return;
+        this.#app.dispose();
+        this.#app = undefined;
+        live.delete(this);
+        this.#root.replaceChildren();
+      });
+    }
+
+    // Hot swap (defineElement again for this tag): the new component, this element's state
+    #swap() {
+      if (!this.#app) return;
+      // (the state through the runtime API, 04 §3.9)
+      this.#app.hmr(this.#component(), (this.#app as any).__runtime.getState());
+      this.#releaseDevtools();
+    }
+
+    #setProp(name: string, value: any) {
+      this.#props[name] = value;
+      const set = (state: any) => ({...state, [name]: value});
+      (this.#app as any)?.__runtime?.setState('root', set);
+    }
+
+    // A per-instance copy of the component whose initialState includes the current props
+    // (owned: the dev statics freeze leaves the host's values alone, G-275)
+    #component() {
+      const wrapped = Object.assign((...args: any[]) => Component(...args), Component, {
+        initialState: owned({...Component.initialState, ...this.#props}),
+      });
+      return Object.defineProperty(wrapped, 'name', {value: Component.name || tag});
+    }
+
+    #eventDrivers() {
+      return Object.fromEntries(
+        Object.entries(events).map(([sink, eventName]) => [
+          sink,
+          (sink$: any) => {
+            sink$.addListener({
+              next: (value: any) => {
+                // PARENT values arrive wrapped as { name, component, value }
+                const detail = sink === 'PARENT' ? value?.value : value;
+                this.dispatchEvent(new CustomEvent(eventName, {detail, bubbles: true, composed: true}));
+              },
+            });
+          },
+        ])
+      );
+    }
+
+    // run() registers the first live app for DevTools time travel (G-212). An element gives
+    // the slot back, so a host app that starts later gets it
+    #releaseDevtools() {
+      const w = window as any;
+      if (w.__SYGNAL_DEVTOOLS_APP__ === this.#app || w.__SYGNAL_DEVTOOLS_APP__?.sinks === this.#app.sinks) w.__SYGNAL_DEVTOOLS_APP__ = undefined;
+    }
+  }
+
+  customElements.define(tag, SygnalElement);
+  return SygnalElement;
+}

package/src/extra/backoff.ts

@@ -0,0 +1,9 @@
+/*
+ * PLAN-3: the retry delay shared by makeSocketDriver's `reconnect` and makeFetchDriver's `retry`.
+ * Delay of retry n (from 0): `min(maxDelayMs, delayMs * 2^n)`, varied by ±`jitter` (a fraction;
+ * `false` = none). Defaults `{ delayMs: 500, maxDelayMs: 10000, jitter: 0.2 }`.
+ */
+export const backoff = (p: {delayMs?: number; maxDelayMs?: number; jitter?: number | boolean}, n: number) => {
+  const j = p.jitter === false ? 0 : p.jitter == null || p.jitter === true ? 0.2 : +p.jitter;
+  return Math.min(p.maxDelayMs ?? 10000, (p.delayMs ?? 500) * 2 ** n) * (1 + j * (2 * Math.random() - 1));
+};