@excom/neutron 0.1.0

package/src/utils/element.ts

@@ -0,0 +1,382 @@
+import {
+  DEFAULT_CONFIG,
+  PROTECTED_ATTR_NAMES,
+  PROTECTED_PROP_NAMES,
+} from "../constants";
+import { LifecycleConfigMap } from "../lifecycle-configs";
+import { Neutron } from "../neutron";
+import type { NeutronElement as TNeutronElement } from "../neutron-element";
+import { NeutronError } from "../neutron-error";
+import type {
+  BuiltConfig,
+  DefaultPropName,
+  EffectorOptions,
+  OptsConfig,
+  OptsPropConfig,
+  PropConfig,
+  RuntimeConfig,
+} from "../types";
+import { effector } from "./effect";
+import {
+  camelToDash,
+  Converter,
+  isNullish,
+  isPojo,
+  isPrimitiveConstructor,
+  PropSerializer,
+} from "@excom/kit-utils";
+import { getAttr, setAttr, TokenList } from "@excom/kit-utils";
+import { deepClone, unique } from "@excom/kit-utils";
+
+export const isBuiltInElement = (el: HTMLElement): boolean =>
+  !!el?.nodeName && !el?.nodeName.includes("-");
+
+const defaultGetProp = (
+  element: TNeutronElement,
+  propStore: Record<string, unknown>,
+  propConfig: PropConfig
+) => {
+  const validatePropValue = (
+    value: unknown,
+    { canSetDefault = false }: { canSetDefault: boolean }
+  ) => {
+    const isTokens = propConfig.type === TokenList;
+    // invalid / nullish → default
+    const isValid = (v) => !propConfig.isValid || propConfig.isValid(v);
+    if (isNullish(value) || (!isTokens && !isValid(value))) {
+      const defaultValue = propConfig.defaultValue();
+      if (canSetDefault) {
+        /* `setAttr()` serializes; defaults are props, so store raw
+         * (or serialized only when there is no attr). */
+        propStore[propConfig.prop] = propConfig.attr
+          ? defaultValue
+          : propConfig.serialize(defaultValue);
+      }
+      return defaultValue;
+    }
+    if (isTokens) {
+      return !propConfig.isValid ? value : (value as string[]).filter(isValid);
+    }
+    return value;
+  };
+  if (propStore.hasOwnProperty(propConfig.prop) && propConfig.attr) {
+    /*
+     * Observed attrs: `attributeChangedCallback` already wrote
+     * `propStore` (`canSetDefault: true`), so later reads skip
+     * `getAttribute()`. Unobserved attrs parse from the attribute
+     * below.
+     * TODO: would notifying every attr and always reading
+     * `propStore` be faster?
+     */
+    return validatePropValue(propStore[propConfig.prop], {
+      canSetDefault: true,
+    });
+  } else if (!propConfig.attr) {
+    // rich prop: deserialize from `propStore`
+    return validatePropValue(
+      propConfig.deserialize(propStore[propConfig.prop]),
+      { canSetDefault: true }
+    );
+  } else {
+    // attribute-backed: parse the live attr
+    const val = Converter.type(propConfig.type).attr.convert(
+      propConfig.deserialize(getAttr(element, propConfig.attr as string))
+    );
+    return validatePropValue(val, { canSetDefault: false });
+  }
+};
+
+const defaultSetProp = (
+  element: TNeutronElement,
+  propStore: Record<string, unknown>,
+  propConfig: PropConfig,
+  value: unknown
+) => {
+  const name = propConfig.prop;
+  const attrName = propConfig.attr;
+  if (attrName) {
+    setAttr(
+      element,
+      attrName,
+      // prop → attribute
+      propConfig.serialize(Converter.type(propConfig.type).prop.convert(value))
+    );
+  } else {
+    // prop → `propStore`
+    propStore[name] = propConfig.serialize(value);
+    if (
+      propConfig.type === Promise ||
+      propConfig.type?.prototype instanceof Promise
+    ) {
+      const queue = element._n_.queueManager.getQueue(name);
+      if (queue.state.status !== "pending" || !value) {
+        // replace / clear: cancel the previous Promise queue
+        queue.reset();
+      }
+      if (value) {
+        queue.settle(value);
+      }
+    }
+  }
+};
+
+export const createPropConfig = (
+  name: string,
+  conf: OptsConfig["props"][string],
+  isDefault: boolean = false
+): PropConfig => {
+  const configuredObject = (
+    isPojo(conf) ? conf : { type: conf }
+  ) as OptsPropConfig;
+  if (!configuredObject.type) {
+    throw new NeutronError(
+      "Incorrect property config: " + JSON.stringify(name)
+    );
+  }
+  const serializer =
+    typeof configuredObject.store === "string"
+      ? PropSerializer[configuredObject.store] || PropSerializer.dfault
+      : typeof configuredObject.store === "object"
+        ? configuredObject.store
+        : PropSerializer.dfault;
+  const result = {
+    prop: name,
+    attr: isPrimitiveConstructor(configuredObject.type)
+      ? Converter.getAttrName(name)
+      : false,
+    defaultValue: () =>
+      Converter.type(configuredObject.type)?.prop.defaultValue ?? null,
+    isValid: configuredObject.isValid ?? null,
+    notify: false as const,
+    get: defaultGetProp,
+    set: defaultSetProp,
+    serialize: serializer.serialize,
+    deserialize: serializer.deserialize,
+    store: configuredObject.store || "default",
+    ...configuredObject,
+    type: configuredObject.type,
+  };
+  if (!isDefault && PROTECTED_PROP_NAMES.includes(name)) {
+    throw new NeutronError(`Cannot use protected prop name: "${name}"`);
+  }
+  if (!isDefault && PROTECTED_ATTR_NAMES.some((n) => n.test(result.attr))) {
+    throw new NeutronError(`Cannot use protected attr: "${result.attr}"`);
+  }
+  return result;
+};
+
+export const initRenderRootConfig = (
+  renderRootConfig?: OptsConfig["renderRoot"]
+): RuntimeConfig["renderRoot"] | undefined => {
+  if (renderRootConfig) {
+    const isShadow = ["open", "closed"].includes(
+      renderRootConfig.shadow as string
+    );
+    return {
+      tag: renderRootConfig.tag || "div",
+      shadow: isShadow ? renderRootConfig.shadow : undefined,
+      defaultSlots: renderRootConfig.defaultSlots ?? isShadow,
+    };
+  }
+};
+
+export const createBuiltConfig = (optsConfig: OptsConfig): BuiltConfig => ({
+  ...optsConfig,
+  reflectDefaultProps: optsConfig.reflectDefaultProps || [],
+  renderRoot: initRenderRootConfig(optsConfig.renderRoot),
+  events: optsConfig.events || {},
+  broadcasts: optsConfig.broadcasts || {},
+  methods: optsConfig.methods || [],
+  lifecycles: {
+    constructed: optsConfig.lifecycles?.constructed || [],
+    connected: optsConfig.lifecycles?.connected || [],
+    adopted: optsConfig.lifecycles?.adopted || [],
+    disconnected: optsConfig.lifecycles?.disconnected || [],
+    error: optsConfig.lifecycles?.error || [],
+    promiseResolved: optsConfig.lifecycles?.promiseResolved || [],
+    promiseRejected: optsConfig.lifecycles?.promiseRejected || [],
+    broadcast: optsConfig.lifecycles?.broadcast || [],
+    event: optsConfig.lifecycles?.event || [],
+    eventDefault: optsConfig.lifecycles?.eventDefault || [],
+    command: optsConfig.lifecycles?.command || [],
+    effect: optsConfig.lifecycles?.effect || [],
+    propUnset: optsConfig.lifecycles?.propUnset || [],
+    propSet: optsConfig.lifecycles?.propSet || [],
+    propChanged: optsConfig.lifecycles?.propChanged || [],
+  },
+  props: Object.keys(optsConfig.props || {}).reduce((acc, propName) => {
+    acc[propName] = createPropConfig(
+      propName,
+      optsConfig.props[propName],
+      false
+    );
+    return acc;
+  }, {}),
+});
+
+export const createRuntimeConfig = (
+  builtConfig: BuiltConfig
+): RuntimeConfig => {
+  const lifecycles = Object.fromEntries(
+    Object.entries({
+      ...builtConfig.lifecycles,
+      propSet: [
+        ...builtConfig.lifecycles!.propSet,
+        /* `provision` is the public rich-data surface: every set
+         * announces to app JS (Quark reads the property directly). */
+        ...("provision" in builtConfig.props
+          ? [[["provision"], () => ({ emit: ["neutron-provision"] })]]
+          : [null]),
+      ].filter(Boolean),
+    }).map(([key, value]) => [
+      key,
+      value.map(([nameArray, fn]) => {
+        const conf = LifecycleConfigMap[key];
+        const batchNames = unique(conf.batchNames?.(nameArray) || nameArray);
+        const opts: EffectorOptions = conf?.effectorOptions?.(nameArray) || {};
+        return [batchNames, effector(fn, opts)];
+      }),
+    ])
+  ) as unknown as RuntimeConfig["lifecycles"];
+  const allPropNames = [
+    ...(lifecycles?.connected || []),
+    ...(lifecycles?.adopted || []),
+    ...(lifecycles?.disconnected || []),
+    ...(lifecycles?.error || []),
+    ...(lifecycles?.effect || []),
+    ...(lifecycles?.propUnset || []),
+    ...(lifecycles?.propSet || []),
+    ...(lifecycles?.propChanged || []),
+  ].flatMap(([names]) => names);
+  return {
+    ...builtConfig,
+    props: Object.fromEntries(
+      Object.entries({
+        ...builtConfig.props,
+        ...Object.keys(DEFAULT_CONFIG.props).reduce((acc, propName) => {
+          acc[propName] = createPropConfig(
+            propName,
+            DEFAULT_CONFIG.props[propName],
+            true
+          );
+          if (
+            builtConfig.reflectDefaultProps?.includes(
+              propName as DefaultPropName
+            )
+          ) {
+            acc[propName].attr = camelToDash(propName);
+          }
+          return acc;
+        }, {}),
+      }).map(([key, value]: [string, PropConfig]) => [
+        key,
+        {
+          ...value,
+          notify:
+            value.notify ||
+            (allPropNames.includes(key) ? buildPropNotify(value) : false),
+        },
+      ])
+    ),
+    methods: builtConfig.methods.map(([name, fn]) => [name, effector(fn)]),
+    lifecycles,
+  };
+};
+
+function buildPropNotify(propConfig: PropConfig): "attr" | "prop" {
+  return propConfig.attr && isPrimitiveConstructor(propConfig.type)
+    ? "attr"
+    : "prop";
+}
+
+export type MergeCustomTypes<T extends { CustomTypes: any }[]> = T extends [
+  infer F extends { CustomTypes: any },
+  ...infer R extends { CustomTypes: any }[],
+]
+  ? F["CustomTypes"] & MergeCustomTypes<R>
+  : {};
+
+// Merge each mixin's `Config`
+export type MergeConfig<T extends { Config: any }[]> = T extends [
+  infer F extends { Config: any },
+  ...infer R extends { Config: any }[],
+]
+  ? F["Config"] & MergeConfig<R>
+  : {};
+
+export const compose = <T extends any[]>(inheriting: [...T]) => {
+  return Neutron<MergeCustomTypes<T>, MergeConfig<T>>(
+    inheriting
+      .map(({ builtConfig }) => deepClone(builtConfig))
+      .reduce(
+        (acc: BuiltConfig, conf: BuiltConfig) => {
+          if (!acc) return conf;
+          return {
+            ...acc,
+            ...conf,
+            events: {
+              ...acc.events,
+              ...conf.events,
+            },
+            broadcasts: {
+              ...acc.broadcasts,
+              ...conf.broadcasts,
+            },
+            props: {
+              ...acc.props,
+              ...conf.props,
+            },
+            methods: [...acc.methods, ...conf.methods],
+            lifecycles: {
+              constructed: [
+                ...acc.lifecycles.constructed,
+                ...conf.lifecycles.constructed,
+              ],
+              connected: [
+                ...acc.lifecycles.connected,
+                ...conf.lifecycles.connected,
+              ],
+              adopted: [...acc.lifecycles.adopted, ...conf.lifecycles.adopted],
+              disconnected: [
+                ...acc.lifecycles.disconnected,
+                ...conf.lifecycles.disconnected,
+              ],
+              error: [...acc.lifecycles.error, ...conf.lifecycles.error],
+              promiseResolved: [
+                ...acc.lifecycles.promiseResolved,
+                ...conf.lifecycles.promiseResolved,
+              ],
+              promiseRejected: [
+                ...acc.lifecycles.promiseRejected,
+                ...conf.lifecycles.promiseRejected,
+              ],
+              broadcast: [
+                ...acc.lifecycles.broadcast,
+                ...conf.lifecycles.broadcast,
+              ],
+              event: [...acc.lifecycles.event, ...conf.lifecycles.event],
+              eventDefault: [
+                ...acc.lifecycles.eventDefault,
+                ...conf.lifecycles.eventDefault,
+              ],
+              command: [
+                ...(acc.lifecycles.command ?? []),
+                ...(conf.lifecycles.command ?? []),
+              ],
+              effect: [...acc.lifecycles.effect, ...conf.lifecycles.effect],
+              propUnset: [
+                ...acc.lifecycles.propUnset,
+                ...conf.lifecycles.propUnset,
+              ],
+              propSet: [...acc.lifecycles.propSet, ...conf.lifecycles.propSet],
+              propChanged: [
+                ...acc.lifecycles.propChanged,
+                ...conf.lifecycles.propChanged,
+              ],
+            },
+          };
+        },
+        null as unknown as BuiltConfig
+      )
+  );
+};

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from "./effect";
+export * from "./element";

package/support/docs/COMMANDS.md

@@ -0,0 +1,58 @@
+# Commands
+
+Accept imperatives as native `command` events (the HTML Command API) instead of bubbling custom events.
+
+## Why commands
+
+A "fetch again", "submit", "open" or "reload" is an instruction aimed at one element, not a fact about the document and not an announcement. The platform models exactly that: a `<button command="…" commandfor="id">` dispatches a `CommandEvent` at its target — non-bubbling, cancelable, with `command` (the verb) and `source` (the button). Custom verbs start with `--`, like CSS custom properties; the browser reserves every other name for its built-ins (`show-modal`, `toggle-popover`, …).
+
+Neutron elements handle those verbs with `onCommand`:
+
+```ts
+Neutron({ tag: "data-feed", props: { apiUrl: String } })
+  .onCommand("--fetch", ({ apiUrl }, { source }) => ({
+    emit: ["data-feed-submit", { detail: [apiUrl] }],
+  }))
+  .onCommand(["--pause", "--resume"], (_, { command }) => ({
+    isPaused: command === "--pause",
+  }))
+  .define();
+```
+
+```html
+<button type="button" command="--fetch" commandfor="feed">Refresh</button>
+<data-feed id="feed" api-url="/api/items"></data-feed>
+```
+
+The button is a real button — keyboard, focus and ARIA come with it — and needs no custom element. `<event-handler command-name="--fetch" target-ref="…">` invokes the same command from any event (a relay, a keyboard shortcut) with a selector instead of an id.
+
+## Semantics
+
+- **One verb list per handler.** `onCommand(name | name[], fn)`; the handler receives the element and the `command` event (`event.command`, `event.source`). Names must be custom commands (`--verb`) — a built-in verb never reaches a custom element, so registering one throws.
+- **At the target only.** `command` never bubbles: a command aimed at a descendant is not yours. Tag-prefixing the verb is therefore pointless; use short verbs (`--submit`, `--reload`, `--open`).
+- **Cancelable, after dispatch.** Handlers run in a microtask after the dispatch completes and are skipped when any listener called `preventDefault()` — a Quark `@on command` handler or app JS can veto. The delay is a microtask, not a task, so the user activation of the click that invoked the command survives for permission prompts and popups.
+- **No payload.** A `CommandEvent` carries no `detail`. State the inputs on the target as attributes before invoking, or read the invoker's `data-*` through `event.source.dataset` — whitelisted against your own declared props (see [Define](./DEFINE.md#md-introspection)) so a caller cannot set private state.
+- **`off*` twin.** `offCommand(name, fn)` unregisters like every other lifecycle.
+
+## Invoking commands
+
+Effects can invoke commands the way they emit events:
+
+```ts
+.onEventDefault("dismiss-watcher-dismiss", ({ targetEl }) => ({
+  command: ["--close", { target: targetEl }],
+  // several: commands: [["--a", { target }], ["--b", { target }]]
+}))
+```
+
+`command: [name, { target?, source? }]` dispatches at `target` (default: the element itself) with the element as `source`. A custom verb dispatches a `command` event directly and works in every browser. A built-in verb (`show-modal`, `close`, `toggle-popover`) can only run through the platform: Neutron clicks an invisible proxy `<button command commandfor>` and removes it, and logs a warning where the Command API is missing. The same helpers are exported for app code: `invokeCommand(target, "--fetch", source)` and `createCommandEvent("--fetch", { source })` (falls back to a plain `Event` with the same fields where `CommandEvent` does not exist yet).
+
+## Typing
+
+`TCommandEvent` is the handler's event type. Document each verb with a `@command` JSDoc tag on the element so it renders in the API reference:
+
+```ts
+/**
+ * @command --fetch - Re-runs the request with the current attributes.
+ */
+```

package/support/docs/COMPOSE.md

@@ -0,0 +1,32 @@
+# Compose
+
+Combine builders into one element — the pattern behind the Abortable / Fetchable / Renderable bases and packages like `<include-content>`.
+
+## Stacking builders
+
+```ts
+const DisabledBase = Neutron({
+  tag: "disabled-base",
+  props: { isDisabled: Boolean },
+}).onPropChanged("isDisabled", ({ isDisabled }) => ({
+  ariaDisabled: isDisabled ? "true" : null, // native reflected property ↔ `aria-disabled`
+}));
+
+export const FancyButton = Neutron.compose([
+  DisabledBase,
+  Neutron({
+    tag: "fancy-button",
+    props: { isPressed: Boolean },
+  }),
+]).onEvent("click", ({ isDisabled, isPressed }) =>
+  isDisabled ? undefined : { isPressed: !isPressed, emit: ["fancy-button-press"] }
+);
+
+FancyButton.define();
+```
+
+## Merge rules
+
+Props, events, and broadcasts merge (later wins); methods and lifecycles concatenate in order; `tag` comes from the last builder. Bases are deep-cloned, so composing never mutates them.
+
+Composing is also how you add props to a packaged element you did not write — see [Recompose](./RECOMPOSE.md).

package/support/docs/DEBUG.md

@@ -0,0 +1,11 @@
+# Debug
+
+Application state is the DOM — watch attributes in the inspector; the DevTools hook shows the lifecycles behind them.
+
+## DevTools
+
+Attach the DevTools hook with `Neutron.attachDevtools()` (shared with Quark — one hook receives both lifecycle and orchestration publications; see `@excom/kit-devtools`). Neutron publishes `defined` (once per element definition: the tag and its `{ prop, attr }` pairs — the DevTools extension audits attribute names from it), `constructed`, `connected`, `disconnected`, `effect` (with the handler signature and the effect object), `commit` (changed props), and `error`.
+
+## Loop guard
+
+Runaway reactions are cut by the shared loop guard: a handler that keeps re-queuing itself (or two handlers feeding each other) is stopped after `LoopGuard.limit` (50) runs in one synchronous batch, and an attribute chain that arrives that deep — through Quark rules, other elements' effects, or events — has its next write dropped. Both are logged once (`Loop guard: …`) and published as errors. `LoopGuard` (`@excom/kit-utils`, also `Neutron.DOM.LoopGuard`) exposes `limit`, `configure({ limit, log })` and `onTrip()`. Separately, Neutron rejects a handler that writes the prop it reacts to (see [Prop reactions](./PROP_REACTIONS.md)).

package/support/docs/DEFINE.md

@@ -0,0 +1,20 @@
+# Define
+
+`define()` registers the element; the registered class then carries its own configuration for anyone who needs to inspect it.
+
+## define()
+
+`define(tag?, options?)` registers the element. Both default to the config (`tag`, `definitionOpts`) and are passed straight to `customElements.define`. Defining an already-registered tag logs a warning instead of throwing.
+
+## Introspection
+
+The defined element class carries its runtime configuration as two static methods. Reach the class through the registry or an instance's constructor:
+
+```ts
+const Drawer = customElements.get("content-drawer") as typeof NeutronElement;
+Drawer.getConfig();                            // { tag, props, events, broadcasts, methods, lifecycles, … }
+Drawer.getPropConfig({ attr: "open-stage" });  // { prop: "openStage", attr: "open-stage", type: Number, … }
+(el.constructor as typeof NeutronElement).getPropConfig({ prop: "isOpen" });
+```
+
+`getConfig()` returns the `RuntimeConfig` built by `define()` (`undefined` before it); `getPropConfig({ attr })` / `getPropConfig({ prop })` return one prop's `PropConfig` or `undefined`. Treat both as read-only. A typical use is whitelisting event payloads: keep only `detail` keys that name a declared, non-private prop before applying them as an effect (see `content-drawer`).

package/support/docs/EFFECTS.md

@@ -0,0 +1,49 @@
+# Effects
+
+A handler describes what should change; Neutron applies it in a fixed order and batches the reactions.
+
+## Effect keys
+
+An effect is a plain object whose keys are instructions for the matched element:
+
+| Key | Meaning |
+| --- | --- |
+| `<prop>: value` | Set a declared prop or any existing element property. Unknown properties throw. |
+| `<elementProp>: { … }` | **Child effect** — an effect applied to the element held in an element-typed prop. The prop must already hold an element; `null` clears it. |
+| `style: { … }` | Merged into `el.style`, not replaced. Prefer a state attribute and let CSS style it. |
+| `emit` / `broadcast: [type, init?]` | Dispatch one event; `emits` / `broadcasts: [[type, init?], …]` dispatch several. Fires after everything else in the effect. |
+| `command: [name, { target?, source? }]` | Invoke a command at `target` (default: the element) — see [Commands](./COMMANDS.md); `commands: [[…], …]` for several. Fires with the emits. |
+| `addListener` / `removeListener` / `toggleListeners` / `removeAllListeners` / `…Broadcast…: [args]` | Listener management (see [Events](./EVENTS.md)). Callbacks are plain functions — pass a `defineMethods` method when the callback should itself return an effect. |
+| `<method>: [args]` | Call a defined or native method with these arguments (`focus: []`, `setCustomValidity: ["Required"]`). The value must be an array. |
+| `returns: value` | Value returned to the caller of a method. Ignored in child effects. |
+
+## Order
+
+Within one effect: `returns` → remove listeners → add listeners → element props → child effects → other props → method calls → `provision` → emits / broadcasts / commands.
+
+## Nothing to do
+
+Return `undefined` / `null` / `false` / `""` / `0` for "nothing to do".
+
+## Arrays of effects
+
+Return an **array** to run several effects in sequence — useful when a later effect depends on an earlier one:
+
+```ts
+Neutron({
+  tag: "focus-host",
+  props: {
+    inputEl: { type: HTMLInputElement, store: "weak" },
+    isFocused: Boolean,
+  },
+})
+  .defineMethods({
+    handleFocus: () => ({ isFocused: true }),
+  })
+  .onConnected((el) => [
+    { inputEl: el.querySelector("input") }, // 1. store the child
+    { inputEl: { addListener: ["focus", el.handleFocus] } }, // 2. wire it
+  ]);
+```
+
+Any lifecycle or method may return an array. `returns` values are collected: none → `undefined`, one → the value, several → an array.

package/support/docs/EVENTS.md

@@ -0,0 +1,57 @@
+# Events
+
+Tag-prefixed custom events, cancelable default actions, cross-instance broadcasts, and listeners that clean themselves up.
+
+## Emit, default actions, broadcasts
+
+```ts
+Neutron({
+  tag: "save-button",
+  props: {},
+  events: {
+    // emitted and listened to as `save-button-save`
+    save: { prefixWithTag: true },
+  },
+  broadcasts: {
+    "app-toast": {},
+  },
+})
+  .onEvent("save", (_el, e) => {
+    /* runs during dispatch, before the default action */
+  })
+  .onEventDefault("save", () => ({
+    /* runs in the next task; skipped if e.preventDefault() was called synchronously */
+    broadcast: ["app-toast", { detail: { message: "Saved" } }],
+  }))
+  .onBroadcast("app-toast", (_el, e) => {
+    /* cross-instance channel */
+  })
+  .onConnected(() => ({
+    emit: ["save", { detail: { id: 1 } }],
+  }));
+```
+
+- `prefixWithTag` is off by default. When on, the configured short name is prefixed for `emit`, `onEvent`, `onEventDefault`, and `addListener` alike. Always prefix events with the tag name to avoid clashing with native events.
+- `emit` defaults `bubbles` / `cancelable` / `composed` to `true`, returns the event, and warns when the element is not connected. Pass `target` in the init to dispatch from another element.
+- `onEventDefault` runs only when the element itself is the event target, after the event has finished dispatching, and never when `preventDefault()` was called. Consumers cancel with `preventDefault()` instead of forking the element.
+- `broadcast` dispatches a non-bubbling event on a shared channel (not on the element), so any instance of any element can `onBroadcast` it.
+- An instruction aimed at the element ("submit", "reload", "open") is not an event of its own: handle it as a command — see [Commands](./COMMANDS.md).
+
+## Listener cleanup
+
+Listeners registered by `onEvent` / `onBroadcast` or added through [effects](./EFFECTS.md) (`addListener`, `addListeners`, …) are tracked per element: removed on disconnect, re-added on reconnect (`once` listeners are not re-added). `addListener` accepts a `target` option to listen on another node with the same cleanup.
+
+## Typing events
+
+Document Neutron-emitted events with `TEvent` plus `type` and `detail` — do not repeat the flags:
+
+```ts
+import { TEvent } from "@excom/neutron";
+
+export type SaveButtonSaveEvent = TEvent & {
+  type: "save-button-save";
+  detail: { id: number };
+};
+```
+
+Native listeners (form `submit`) are not Neutron emits — type those as the DOM event with its real flags (`composed: false` on `SubmitEvent`).