@excom/neutron 0.1.0

package/support/package-meta.json

@@ -0,0 +1,129 @@
+{
+  "shortName": "neutron",
+  "package": {
+    "name": "@excom/neutron",
+    "version": "0.1.0",
+    "description": "Element factory of the Nucleus Stack — typed custom elements with effect-based lifecycles",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "element-base"
+    }
+  },
+  "demos": {},
+  "readme": "<h1 id=\"md-neutron\">neutron</h1>\n<p>Define typed custom elements with effect-based lifecycles — props, events, and compose without rewriting the Custom Elements boilerplate.</p>\n<p>Neutron is the element factory of the Nucleus Stack: <code>Neutron({ tag, props })</code> returns a builder you chain lifecycles onto, then <code>define()</code>. Every Nucleus Kit element is a Neutron element, and so is every element you write yourself.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Declarative factory</strong> <code>Neutron({ tag, props }).… .define()</code></li>\n<li><strong>Typed props</strong> Primitives and <code>TokenList</code> reflect to dashed attributes; objects / arrays / elements / promises stay on the instance</li>\n<li><strong>Effect returns</strong> Lifecycles / methods return a POJO (or an array of them) that sets props, emits, listens, calls methods, and styles</li>\n<li><strong>Fine-grained reactions</strong> <code>onPropSet</code> / <code>Unset</code> / <code>Changed</code> / <code>onEffect</code></li>\n<li><strong>Events &amp; broadcasts</strong> Tag-prefixed custom events, cancelable default actions, channel broadcasts</li>\n<li><strong>Commands</strong> <code>onCommand(&quot;--verb&quot;)</code> handles the HTML Command API — <code>&lt;button command commandfor&gt;</code> needs no custom element</li>\n<li><strong>Listener cleanup</strong> Listeners added through effects are removed on disconnect and restored on reconnect</li>\n<li><strong>Compose</strong> Combine builders (<code>Neutron.compose</code>) for mixin-style packages</li>\n<li><strong>Recompose</strong> Import a package&#39;s raw builder, add / remove lifecycles and methods, then <code>define()</code> it yourself</li>\n<li><strong>DevTools</strong> <code>Neutron.attachDevtools()</code> hooks the Nucleus DevTools extension</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>An element owns its own state (attributes) and announces changes (events). It never renders children or reaches into siblings — coordination belongs to Quark. The rules these examples follow are collected in <spa-a route-href=\"/nucleus/docs/best_practices\" role=\"link\">Best Practices</spa-a> and <spa-a route-href=\"/nucleus/docs/creating_elements\" role=\"link\">Creating Elements</spa-a>.</p>\n<include-content data-language=\"ts\"><template>import { Neutron } from \"@excom/neutron\";\n\nexport const PressTracker = Neutron({\n  tag: \"press-tracker\",\n  props: {\n    pressCount: { type: Number, defaultValue: () =&gt; 0 }, // reflects ↔ `press-count`\n  },\n})\n  .onEvent(\"click\", ({ pressCount }) =&gt; ({\n    // effects are declarative instructions, not imperative mutations\n    pressCount: pressCount + 1,\n    emit: [\"press-tracker-press\", { detail: { pressCount: pressCount + 1 } }],\n  }));\n\nPressTracker.define();</template></include-content>\n<include-content data-language=\"html\"><template>&lt;press-tracker press-count=\"0\"&gt;\n  &lt;button&gt;Press&lt;/button&gt;\n&lt;/press-tracker&gt;\n&lt;!-- `press-tracker[press-count=\"3\"]` is now a CSS / Quark selector --&gt;</template></include-content>\n<h3 id=\"md-documentation\">Documentation</h3>\n<p>Defining elements</p>\n<ul>\n<li><spa-a route-href=\"/nucleus/packages/neutron/props\" role=\"link\">Props</spa-a> — typed props, reflection, <code>TokenList</code>, naming rules</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/provision\" role=\"link\">Provision</spa-a> — the one property for published rich data</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/typescript\" role=\"link\">TypeScript</spa-a> — global element types, <code>ConstructorType</code></li>\n</ul>\n<p>Behavior</p>\n<ul>\n<li><spa-a route-href=\"/nucleus/packages/neutron/lifecycles\" role=\"link\">Lifecycles</spa-a> — <code>onConnected</code> &amp; co., destructuring, async pitfalls</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/effects\" role=\"link\">Effects</spa-a> — the object a handler returns</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/prop_reactions\" role=\"link\">Prop reactions</spa-a> — <code>onPropSet</code> / <code>Unset</code> / <code>Changed</code> / <code>onEffect</code></li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/methods\" role=\"link\">Methods</spa-a> — methods as effectors</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/events\" role=\"link\">Events</spa-a> — emits, default actions, broadcasts, listener cleanup</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/commands\" role=\"link\">Commands</spa-a> — <code>onCommand</code> for <code>--verb</code> commands, the <code>command</code> effect</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/promise_props\" role=\"link\">Promise props</spa-a> — <code>onPromiseResolved</code> / <code>Rejected</code></li>\n</ul>\n<p>Composition</p>\n<ul>\n<li><spa-a route-href=\"/nucleus/packages/neutron/compose\" role=\"link\">Compose</spa-a> — stack builders into mixin-style packages</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/recompose\" role=\"link\">Recompose</spa-a> — edit a packaged element before defining it</li>\n</ul>\n<p>Runtime</p>\n<ul>\n<li><spa-a route-href=\"/nucleus/packages/neutron/define\" role=\"link\">Define</spa-a> — <code>define()</code> and class introspection</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/debug\" role=\"link\">Debug</spa-a> — DevTools hook, loop guard</li>\n</ul>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-state-on-connect\">State on connect</h4>\n<include-content data-language=\"ts\"><template>Neutron({ tag: \"ready-flag\", props: { isReady: Boolean } })\n  .onConnected(() =&gt; ({ isReady: true, emit: [\"ready-flag-ready\"] }))\n  .define();</template></include-content>\n<h4 id=\"md-child-element-effect-across-handlers\">Child element effect across handlers</h4>\n<p>Assign an element prop, then react to it with a nested effect. Listener callbacks that return effects must be <code>defineMethods</code> methods:</p>\n<include-content data-language=\"ts\"><template>Neutron({\n  tag: \"focus-host\",\n  props: {\n    inputEl: { type: HTMLInputElement, store: \"weak\" },\n    isFocused: Boolean,\n  },\n})\n  .defineMethods({\n    handleFocus: () =&gt; ({ isFocused: true, emit: [\"focus-host-focus\"] }),\n    handleBlur: () =&gt; ({ isFocused: false }),\n  })\n  .onConnected((el) =&gt; ({\n    inputEl: el.querySelector(\"input\"),\n  }))\n  .onPropSet(\"inputEl\", ({ handleFocus, handleBlur }) =&gt; ({\n    inputEl: {\n      addListeners: [\n        [\"focus\", handleFocus],\n        [\"blur\", handleBlur],\n      ],\n    },\n  }));</template></include-content>\n",
+  "docs": {
+    "commands": "<h1 id=\"md-commands\">Commands</h1>\n<p>Accept imperatives as native <code>command</code> events (the HTML Command API) instead of bubbling custom events.</p>\n<h2 id=\"md-why-commands\">Why commands</h2>\n<p>A &quot;fetch again&quot;, &quot;submit&quot;, &quot;open&quot; or &quot;reload&quot; is an instruction aimed at one element, not a fact about the document and not an announcement. The platform models exactly that: a <code>&lt;button command=&quot;…&quot; commandfor=&quot;id&quot;&gt;</code> dispatches a <code>CommandEvent</code> at its target — non-bubbling, cancelable, with <code>command</code> (the verb) and <code>source</code> (the button). Custom verbs start with <code>--</code>, like CSS custom properties; the browser reserves every other name for its built-ins (<code>show-modal</code>, <code>toggle-popover</code>, …).</p>\n<p>Neutron elements handle those verbs with <code>onCommand</code>:</p>\n<include-content data-language=\"ts\"><template>Neutron({ tag: \"data-feed\", props: { apiUrl: String } })\n  .onCommand(\"--fetch\", ({ apiUrl }, { source }) =&gt; ({\n    emit: [\"data-feed-submit\", { detail: [apiUrl] }],\n  }))\n  .onCommand([\"--pause\", \"--resume\"], (_, { command }) =&gt; ({\n    isPaused: command === \"--pause\",\n  }))\n  .define();</template></include-content>\n<include-content data-language=\"html\"><template>&lt;button type=\"button\" command=\"--fetch\" commandfor=\"feed\"&gt;Refresh&lt;/button&gt;\n&lt;data-feed id=\"feed\" api-url=\"/api/items\"&gt;&lt;/data-feed&gt;</template></include-content>\n<p>The button is a real button — keyboard, focus and ARIA come with it — and needs no custom element. <code>&lt;event-handler command-name=&quot;--fetch&quot; target-ref=&quot;…&quot;&gt;</code> invokes the same command from any event (a relay, a keyboard shortcut) with a selector instead of an id.</p>\n<h2 id=\"md-semantics\">Semantics</h2>\n<ul>\n<li><strong>One verb list per handler.</strong> <code>onCommand(name | name[], fn)</code>; the handler receives the element and the <code>command</code> event (<code>event.command</code>, <code>event.source</code>). Names must be custom commands (<code>--verb</code>) — a built-in verb never reaches a custom element, so registering one throws.</li>\n<li><strong>At the target only.</strong> <code>command</code> never bubbles: a command aimed at a descendant is not yours. Tag-prefixing the verb is therefore pointless; use short verbs (<code>--submit</code>, <code>--reload</code>, <code>--open</code>).</li>\n<li><strong>Cancelable, after dispatch.</strong> Handlers run in a microtask after the dispatch completes and are skipped when any listener called <code>preventDefault()</code> — a Quark <code>@on command</code> 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.</li>\n<li><strong>No payload.</strong> A <code>CommandEvent</code> carries no <code>detail</code>. State the inputs on the target as attributes before invoking, or read the invoker&#39;s <code>data-*</code> through <code>event.source.dataset</code> — whitelisted against your own declared props (see <spa-a route-href=\"/nucleus/packages/neutron/define#md-introspection\" role=\"link\">Define</spa-a>) so a caller cannot set private state.</li>\n<li><strong><code>off*</code> twin.</strong> <code>offCommand(name, fn)</code> unregisters like every other lifecycle.</li>\n</ul>\n<h2 id=\"md-invoking-commands\">Invoking commands</h2>\n<p>Effects can invoke commands the way they emit events:</p>\n<include-content data-language=\"ts\"><template>.onEventDefault(\"dismiss-watcher-dismiss\", ({ targetEl }) =&gt; ({\n  command: [\"--close\", { target: targetEl }],\n  // several: commands: [[\"--a\", { target }], [\"--b\", { target }]]\n}))</template></include-content>\n<p><code>command: [name, { target?, source? }]</code> dispatches at <code>target</code> (default: the element itself) with the element as <code>source</code>. A custom verb dispatches a <code>command</code> event directly and works in every browser. A built-in verb (<code>show-modal</code>, <code>close</code>, <code>toggle-popover</code>) can only run through the platform: Neutron clicks an invisible proxy <code>&lt;button command commandfor&gt;</code> and removes it, and logs a warning where the Command API is missing. The same helpers are exported for app code: <code>invokeCommand(target, &quot;--fetch&quot;, source)</code> and <code>createCommandEvent(&quot;--fetch&quot;, { source })</code> (falls back to a plain <code>Event</code> with the same fields where <code>CommandEvent</code> does not exist yet).</p>\n<h2 id=\"md-typing\">Typing</h2>\n<p><code>TCommandEvent</code> is the handler&#39;s event type. Document each verb with a <code>@command</code> JSDoc tag on the element so it renders in the API reference:</p>\n<include-content data-language=\"ts\"><template>/**\n * @command --fetch - Re-runs the request with the current attributes.\n */</template></include-content>\n",
+    "compose": "<h1 id=\"md-compose\">Compose</h1>\n<p>Combine builders into one element — the pattern behind the Abortable / Fetchable / Renderable bases and packages like <code>&lt;include-content&gt;</code>.</p>\n<h2 id=\"md-stacking-builders\">Stacking builders</h2>\n<include-content data-language=\"ts\"><template>const DisabledBase = Neutron({\n  tag: \"disabled-base\",\n  props: { isDisabled: Boolean },\n}).onPropChanged(\"isDisabled\", ({ isDisabled }) =&gt; ({\n  ariaDisabled: isDisabled ? \"true\" : null, // native reflected property ↔ `aria-disabled`\n}));\n\nexport const FancyButton = Neutron.compose([\n  DisabledBase,\n  Neutron({\n    tag: \"fancy-button\",\n    props: { isPressed: Boolean },\n  }),\n]).onEvent(\"click\", ({ isDisabled, isPressed }) =&gt;\n  isDisabled ? undefined : { isPressed: !isPressed, emit: [\"fancy-button-press\"] }\n);\n\nFancyButton.define();</template></include-content>\n<h2 id=\"md-merge-rules\">Merge rules</h2>\n<p>Props, events, and broadcasts merge (later wins); methods and lifecycles concatenate in order; <code>tag</code> comes from the last builder. Bases are deep-cloned, so composing never mutates them.</p>\n<p>Composing is also how you add props to a packaged element you did not write — see <spa-a route-href=\"/nucleus/packages/neutron/recompose\" role=\"link\">Recompose</spa-a>.</p>\n",
+    "debug": "<h1 id=\"md-debug\">Debug</h1>\n<p>Application state is the DOM — watch attributes in the inspector; the DevTools hook shows the lifecycles behind them.</p>\n<h2 id=\"md-devtools\">DevTools</h2>\n<p>Attach the DevTools hook with <code>Neutron.attachDevtools()</code> (shared with Quark — one hook receives both lifecycle and orchestration publications; see <code>@excom/kit-devtools</code>). Neutron publishes <code>defined</code> (once per element definition: the tag and its <code>{ prop, attr }</code> pairs — the DevTools extension audits attribute names from it), <code>constructed</code>, <code>connected</code>, <code>disconnected</code>, <code>effect</code> (with the handler signature and the effect object), <code>commit</code> (changed props), and <code>error</code>.</p>\n<h2 id=\"md-loop-guard\">Loop guard</h2>\n<p>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 <code>LoopGuard.limit</code> (50) runs in one synchronous batch, and an attribute chain that arrives that deep — through Quark rules, other elements&#39; effects, or events — has its next write dropped. Both are logged once (<code>Loop guard: …</code>) and published as errors. <code>LoopGuard</code> (<code>@excom/kit-utils</code>, also <code>Neutron.DOM.LoopGuard</code>) exposes <code>limit</code>, <code>configure({ limit, log })</code> and <code>onTrip()</code>. Separately, Neutron rejects a handler that writes the prop it reacts to (see <spa-a route-href=\"/nucleus/packages/neutron/prop_reactions\" role=\"link\">Prop reactions</spa-a>).</p>\n",
+    "define": "<h1 id=\"md-define\">Define</h1>\n<p><code>define()</code> registers the element; the registered class then carries its own configuration for anyone who needs to inspect it.</p>\n<h2 id=\"md-define\">define()</h2>\n<p><code>define(tag?, options?)</code> registers the element. Both default to the config (<code>tag</code>, <code>definitionOpts</code>) and are passed straight to <code>customElements.define</code>. Defining an already-registered tag logs a warning instead of throwing.</p>\n<h2 id=\"md-introspection\">Introspection</h2>\n<p>The defined element class carries its runtime configuration as two static methods. Reach the class through the registry or an instance&#39;s constructor:</p>\n<include-content data-language=\"ts\"><template>const Drawer = customElements.get(\"content-drawer\") as typeof NeutronElement;\nDrawer.getConfig();                            // { tag, props, events, broadcasts, methods, lifecycles, … }\nDrawer.getPropConfig({ attr: \"open-stage\" });  // { prop: \"openStage\", attr: \"open-stage\", type: Number, … }\n(el.constructor as typeof NeutronElement).getPropConfig({ prop: \"isOpen\" });</template></include-content>\n<p><code>getConfig()</code> returns the <code>RuntimeConfig</code> built by <code>define()</code> (<code>undefined</code> before it); <code>getPropConfig({ attr })</code> / <code>getPropConfig({ prop })</code> return one prop&#39;s <code>PropConfig</code> or <code>undefined</code>. Treat both as read-only. A typical use is whitelisting event payloads: keep only <code>detail</code> keys that name a declared, non-private prop before applying them as an effect (see <code>content-drawer</code>).</p>\n",
+    "effects": "<h1 id=\"md-effects\">Effects</h1>\n<p>A handler describes what should change; Neutron applies it in a fixed order and batches the reactions.</p>\n<h2 id=\"md-effect-keys\">Effect keys</h2>\n<p>An effect is a plain object whose keys are instructions for the matched element:</p>\n<table>\n<thead>\n<tr>\n<th>Key</th>\n<th>Meaning</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>&lt;prop&gt;: value</code></td>\n<td>Set a declared prop or any existing element property. Unknown properties throw.</td>\n</tr>\n<tr>\n<td><code>&lt;elementProp&gt;: { … }</code></td>\n<td><strong>Child effect</strong> — an effect applied to the element held in an element-typed prop. The prop must already hold an element; <code>null</code> clears it.</td>\n</tr>\n<tr>\n<td><code>style: { … }</code></td>\n<td>Merged into <code>el.style</code>, not replaced. Prefer a state attribute and let CSS style it.</td>\n</tr>\n<tr>\n<td><code>emit</code> / <code>broadcast: [type, init?]</code></td>\n<td>Dispatch one event; <code>emits</code> / <code>broadcasts: [[type, init?], …]</code> dispatch several. Fires after everything else in the effect.</td>\n</tr>\n<tr>\n<td><code>command: [name, { target?, source? }]</code></td>\n<td>Invoke a command at <code>target</code> (default: the element) — see <spa-a route-href=\"/nucleus/packages/neutron/commands\" role=\"link\">Commands</spa-a>; <code>commands: [[…], …]</code> for several. Fires with the emits.</td>\n</tr>\n<tr>\n<td><code>addListener</code> / <code>removeListener</code> / <code>toggleListeners</code> / <code>removeAllListeners</code> / <code>…Broadcast…: [args]</code></td>\n<td>Listener management (see <spa-a route-href=\"/nucleus/packages/neutron/events\" role=\"link\">Events</spa-a>). Callbacks are plain functions — pass a <code>defineMethods</code> method when the callback should itself return an effect.</td>\n</tr>\n<tr>\n<td><code>&lt;method&gt;: [args]</code></td>\n<td>Call a defined or native method with these arguments (<code>focus: []</code>, <code>setCustomValidity: [&quot;Required&quot;]</code>). The value must be an array.</td>\n</tr>\n<tr>\n<td><code>returns: value</code></td>\n<td>Value returned to the caller of a method. Ignored in child effects.</td>\n</tr>\n</tbody></table>\n<h2 id=\"md-order\">Order</h2>\n<p>Within one effect: <code>returns</code> → remove listeners → add listeners → element props → child effects → other props → method calls → <code>provision</code> → emits / broadcasts / commands.</p>\n<h2 id=\"md-nothing-to-do\">Nothing to do</h2>\n<p>Return <code>undefined</code> / <code>null</code> / <code>false</code> / <code>&quot;&quot;</code> / <code>0</code> for &quot;nothing to do&quot;.</p>\n<h2 id=\"md-arrays-of-effects\">Arrays of effects</h2>\n<p>Return an <strong>array</strong> to run several effects in sequence — useful when a later effect depends on an earlier one:</p>\n<include-content data-language=\"ts\"><template>Neutron({\n  tag: \"focus-host\",\n  props: {\n    inputEl: { type: HTMLInputElement, store: \"weak\" },\n    isFocused: Boolean,\n  },\n})\n  .defineMethods({\n    handleFocus: () =&gt; ({ isFocused: true }),\n  })\n  .onConnected((el) =&gt; [\n    { inputEl: el.querySelector(\"input\") }, // 1. store the child\n    { inputEl: { addListener: [\"focus\", el.handleFocus] } }, // 2. wire it\n  ]);</template></include-content>\n<p>Any lifecycle or method may return an array. <code>returns</code> values are collected: none → <code>undefined</code>, one → the value, several → an array.</p>\n",
+    "events": "<h1 id=\"md-events\">Events</h1>\n<p>Tag-prefixed custom events, cancelable default actions, cross-instance broadcasts, and listeners that clean themselves up.</p>\n<h2 id=\"md-emit-default-actions-broadcasts\">Emit, default actions, broadcasts</h2>\n<include-content data-language=\"ts\"><template>Neutron({\n  tag: \"save-button\",\n  props: {},\n  events: {\n    // emitted and listened to as `save-button-save`\n    save: { prefixWithTag: true },\n  },\n  broadcasts: {\n    \"app-toast\": {},\n  },\n})\n  .onEvent(\"save\", (_el, e) =&gt; {\n    /* runs during dispatch, before the default action */\n  })\n  .onEventDefault(\"save\", () =&gt; ({\n    /* runs in the next task; skipped if e.preventDefault() was called synchronously */\n    broadcast: [\"app-toast\", { detail: { message: \"Saved\" } }],\n  }))\n  .onBroadcast(\"app-toast\", (_el, e) =&gt; {\n    /* cross-instance channel */\n  })\n  .onConnected(() =&gt; ({\n    emit: [\"save\", { detail: { id: 1 } }],\n  }));</template></include-content>\n<ul>\n<li><code>prefixWithTag</code> is off by default. When on, the configured short name is prefixed for <code>emit</code>, <code>onEvent</code>, <code>onEventDefault</code>, and <code>addListener</code> alike. Always prefix events with the tag name to avoid clashing with native events.</li>\n<li><code>emit</code> defaults <code>bubbles</code> / <code>cancelable</code> / <code>composed</code> to <code>true</code>, returns the event, and warns when the element is not connected. Pass <code>target</code> in the init to dispatch from another element.</li>\n<li><code>onEventDefault</code> runs only when the element itself is the event target, after the event has finished dispatching, and never when <code>preventDefault()</code> was called. Consumers cancel with <code>preventDefault()</code> instead of forking the element.</li>\n<li><code>broadcast</code> dispatches a non-bubbling event on a shared channel (not on the element), so any instance of any element can <code>onBroadcast</code> it.</li>\n<li>An instruction aimed at the element (&quot;submit&quot;, &quot;reload&quot;, &quot;open&quot;) is not an event of its own: handle it as a command — see <spa-a route-href=\"/nucleus/packages/neutron/commands\" role=\"link\">Commands</spa-a>.</li>\n</ul>\n<h2 id=\"md-listener-cleanup\">Listener cleanup</h2>\n<p>Listeners registered by <code>onEvent</code> / <code>onBroadcast</code> or added through <spa-a route-href=\"/nucleus/packages/neutron/effects\" role=\"link\">effects</spa-a> (<code>addListener</code>, <code>addListeners</code>, …) are tracked per element: removed on disconnect, re-added on reconnect (<code>once</code> listeners are not re-added). <code>addListener</code> accepts a <code>target</code> option to listen on another node with the same cleanup.</p>\n<h2 id=\"md-typing-events\">Typing events</h2>\n<p>Document Neutron-emitted events with <code>TEvent</code> plus <code>type</code> and <code>detail</code> — do not repeat the flags:</p>\n<include-content data-language=\"ts\"><template>import { TEvent } from \"@excom/neutron\";\n\nexport type SaveButtonSaveEvent = TEvent &amp; {\n  type: \"save-button-save\";\n  detail: { id: number };\n};</template></include-content>\n<p>Native listeners (form <code>submit</code>) are not Neutron emits — type those as the DOM event with its real flags (<code>composed: false</code> on <code>SubmitEvent</code>).</p>\n",
+    "lifecycles": "<h1 id=\"md-lifecycles\">Lifecycles</h1>\n<p>Chain <code>.on*</code> handlers that return effects; Neutron applies them, tracks listeners, and routes errors.</p>\n<h2 id=\"md-handlers\">Handlers</h2>\n<p>Each handler receives the element first, then any lifecycle-specific argument, and returns an <spa-a route-href=\"/nucleus/packages/neutron/effects\" role=\"link\">effect</spa-a>. Prefer effects over mutating the element directly. Every <code>on*</code> has an <code>off*</code> twin that unregisters the same function.</p>\n<include-content data-language=\"ts\"><template>Neutron({ tag: \"panel-host\", props: { isReady: Boolean } })\n  .onConstructed(() =&gt; ({ /* runs in the constructor, before connect */ }))\n  .onConnected(() =&gt; ({\n    // every connect, including reconnects\n    isReady: true,\n    emit: [\"panel-host-ready\"],\n  }))\n  .onDisconnected((el) =&gt; ({\n    // tear down; `el.isMoving` is true when a disconnect is followed by a connect in the same tick\n    isReady: false,\n  }))\n  .onAdopted(() =&gt; ({}))\n  .onError((_el, err) =&gt; {\n    console.error(err);\n  });</template></include-content>\n<p>Disconnect is settled one microtask after <code>disconnectedCallback</code>. If the element is re-inserted before then (a DOM move), <code>onDisconnected</code> and <code>onConnected</code> both still run, with <code>isMoving</code> set. An error thrown by any handler is routed to <code>onError(el, error)</code>; without an <code>onError</code>, it is rethrown.</p>\n<p>Reactions to prop changes, events, commands and promises are their own pages: <spa-a route-href=\"/nucleus/packages/neutron/prop_reactions\" role=\"link\">Prop reactions</spa-a>, <spa-a route-href=\"/nucleus/packages/neutron/events\" role=\"link\">Events</spa-a>, <spa-a route-href=\"/nucleus/packages/neutron/commands\" role=\"link\">Commands</spa-a>, <spa-a route-href=\"/nucleus/packages/neutron/promise_props\" role=\"link\">Promise props</spa-a>.</p>\n<h2 id=\"md-destructure-the-element-argument\">Destructure the element argument</h2>\n<p>Prefer <code>({ prop }) =&gt; …</code> over <code>(el) =&gt; …</code>. A handler that only ever sees the values it names cannot reach for <code>el.setAttribute</code>, <code>el.querySelector(…).value = …</code> or any other imperative mutation — reading the signature is enough to know the handler is pure, and the effect it returns is the whole story.</p>\n<include-content data-language=\"ts\"><template>Neutron({ tag: \"price-tag\", props: { amount: Number, currency: String } })\n  .onPropChanged([\"amount\", \"currency\"], ({ amount, currency }) =&gt; ({\n    ariaLabel: `${amount} ${currency}`,\n  }));</template></include-content>\n<h2 id=\"md-pitfall-stale-values-in-async-callbacks\">Pitfall: stale values in async callbacks</h2>\n<p>Destructuring copies the values at call time. If the handler starts asynchronous work and the callback reads those copies, it sees the element as it was when the work started, not when it finished:</p>\n<include-content data-language=\"ts\"><template>// ✗ `amount` here is whatever it was when the fetch began\n.onConnected(({ apiUrl, amount }) =&gt; ({\n  addListener: [\"price-tag-refresh\", () =&gt; fetch(apiUrl).then(() =&gt; console.log(amount))],\n}))</template></include-content>\n<p>Make the callback a <code>defineMethods</code> method instead. <spa-a route-href=\"/nucleus/packages/neutron/methods\" role=\"link\">Methods</spa-a> are effectors too — Neutron calls them with the live element first — so the callback destructures fresh values when it actually runs, and its return value is applied as an effect. The lifecycle keeps <code>el</code> only to reach the method (methods are bound to the element; call them as <code>el.method(…)</code>):</p>\n<include-content data-language=\"ts\"><template>Neutron({ tag: \"price-tag\", props: { apiUrl: String, amount: Number } })\n  .defineMethods({\n    // runs later, with the element as it is *then*\n    applyQuote: ({ amount }, quote: { rate: number }) =&gt; ({\n      amount: amount * quote.rate,\n    }),\n  })\n  .onConnected((el) =&gt; ({\n    addListener: [\n      \"price-tag-refresh\",\n      () =&gt; fetch(el.apiUrl).then((r) =&gt; r.json()).then((quote) =&gt; el.applyQuote(quote)),\n    ],\n  }));</template></include-content>\n",
+    "methods": "<h1 id=\"md-methods\">Methods</h1>\n<p>Methods are effectors like lifecycles: they receive the live element, return an effect, and can hand a value back to the caller.</p>\n<h2 id=\"md-defining-methods\">Defining methods</h2>\n<include-content data-language=\"ts\"><template>Neutron({ tag: \"tally-counter\", props: { tallyCount: Number } })\n  .defineMethods({\n    increment: ({ tallyCount }, step = 1) =&gt; ({\n      tallyCount: (tallyCount ?? 0) + step,\n      returns: (tallyCount ?? 0) + step, // value returned to the caller\n    }),\n  })\n  .define();\n\n// el.increment(2) → number</template></include-content>\n<p>Element first, then the call arguments. Other effects can call them by name: <code>increment: [2]</code>. Because Neutron calls a method with the element as it is <em>then</em>, methods are also the right shape for async callbacks — see <spa-a route-href=\"/nucleus/packages/neutron/lifecycles#md-pitfall-stale-values-in-async-callbacks\" role=\"link\">Lifecycles</spa-a>.</p>\n<h3 id=\"md-pre-declaring-signatures\">Pre-declaring signatures</h3>\n<p><code>defineMethods</code> types <code>element</code> as the element <em>before</em> that call, so a method cannot reach a sibling defined in the same object. <code>withTypes&lt;T&gt;()</code> is a type-only step (no runtime effect) that puts the signatures on the element type first — methods are bound and the element argument is stripped, so declare them as the element sees them. It also makes <code>typeof Builder.CustomElement</code> usable for module-level helpers.</p>\n<include-content data-language=\"ts\"><template>interface Methods {\n  flush: FrameRequestCallback;\n  schedule: () =&gt; void;\n}\n\nexport const Ticker = Neutron({ tag: \"tick-er\", props: { tickCount: Number } })\n  .withTypes&lt;Methods&gt;();\n\ntype El = typeof Ticker.CustomElement;\n\nconst label = (el: El) =&gt; `${el.tickCount}`;\n\nTicker.defineMethods({\n  flush: ({ tickCount }) =&gt; ({ tickCount: tickCount + 1 }),\n  schedule: ({ flush }) =&gt; {\n    requestAnimationFrame(flush); // sibling method, no cast\n  },\n}).define();</template></include-content>\n<h2 id=\"md-keep-the-imperative-surface-small\">Keep the imperative surface small</h2>\n<p>If a method is something the consuming app may want to invoke, accept it as a command (<code>onCommand(&quot;--verb&quot;)</code>, see <spa-a route-href=\"/nucleus/packages/neutron/commands\" role=\"link\">Commands</spa-a>); if it is something the app may want to cancel, fire an event with a default action (<code>onEventDefault</code>, see <spa-a route-href=\"/nucleus/packages/neutron/events\" role=\"link\">Events</spa-a>). Neither needs a public method.</p>\n",
+    "promise_props": "<h1 id=\"md-promise-props\">Promise props</h1>\n<p>Store a promise in a prop and react to its settlement; replacing it cancels the stale one.</p>\n<h2 id=\"md-resolve-reject-handlers\">Resolve / reject handlers</h2>\n<include-content data-language=\"ts\"><template>Neutron({\n  tag: \"lazy-item\",\n  props: {\n    srcPromise: Promise,\n    provision: Object,\n  },\n})\n  .onConnected(() =&gt; ({\n    srcPromise: fetch(\"/api/item\").then((r) =&gt; r.json()),\n  }))\n  .onPromiseResolved(\"srcPromise\", (_el, result) =&gt; ({\n    srcPromise: null,\n    provision: result.srcPromise,\n  }))\n  .onPromiseRejected(\"srcPromise\", () =&gt; ({ srcPromise: null }));</template></include-content>\n<p><code>result</code> maps the prop name to the resolved value (or the rejection reason).</p>\n<h2 id=\"md-cancellation\">Cancellation</h2>\n<p>Assigning a new promise or <code>null</code> while the previous one is pending cancels it — the stale settlement never reaches the handlers.</p>\n",
+    "props": "<h1 id=\"md-props\">Props</h1>\n<p>Declare an element&#39;s state once; primitives become dashed attributes that CSS and Quark select on, rich values stay on the instance.</p>\n<h2 id=\"md-declaring-props\">Declaring props</h2>\n<p>Shorthand constructors reflect primitives to dashed attributes. Rich config adds defaults, validation, storage, and custom serialize / deserialize.</p>\n<include-content data-language=\"ts\"><template>import { Neutron, TokenList } from \"@excom/neutron\";\n\nNeutron({\n  tag: \"usage-meter\",\n  props: {\n    unitLabel: String, // reflects ↔ `unit-label`\n    maxCount: Number, // reflects ↔ `max-count`\n    isOpen: Boolean, // presence attribute `is-open`\n    featureTags: TokenList, // space-separated tokens ↔ `feature-tags`, read as `string[]`\n    // non-reflecting by default:\n    payload: Object,\n    items: Array,\n    srcPromise: Promise,\n    // rich config:\n    maxValue: {\n      type: Number,\n      defaultValue: () =&gt; 100,\n      isValid: (n) =&gt; n &gt; 0,\n    },\n    // element references are always weak — never pin another node:\n    inputEl: { type: HTMLInputElement, store: \"weak\" },\n  },\n});</template></include-content>\n<h2 id=\"md-rich-config-keys\">Rich config keys</h2>\n<table>\n<thead>\n<tr>\n<th>Key</th>\n<th>Purpose</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>type</code></td>\n<td>Constructor. <code>String</code> / <code>Number</code> / <code>Boolean</code> / <code>TokenList</code> reflect to an attribute; everything else is instance-only.</td>\n</tr>\n<tr>\n<td><code>defaultValue</code></td>\n<td><code>() =&gt; value</code>, returned when the prop is nullish or invalid.</td>\n</tr>\n<tr>\n<td><code>isValid</code></td>\n<td><code>(value) =&gt; boolean</code>. Invalid values fall back to the default; for <code>TokenList</code> the invalid tokens are filtered out instead.</td>\n</tr>\n<tr>\n<td><code>attr</code></td>\n<td>Override the attribute name, or <code>false</code> to keep a primitive off the attribute.</td>\n</tr>\n<tr>\n<td><code>store</code></td>\n<td><code>&quot;weak&quot;</code> holds the value in a <code>WeakRef</code> and derefs on read. Required for every prop that references another element, so a removed node can be collected.</td>\n</tr>\n<tr>\n<td><code>serialize</code> / <code>deserialize</code></td>\n<td>Transform on write / read.</td>\n</tr>\n</tbody></table>\n<h2 id=\"md-tokenlist\">TokenList</h2>\n<p><code>TokenList</code> is exported by this package. It marks a space-separated attribute (<code>feature-tags=&quot;a b&quot;</code>) whose property value is a plain <code>string[]</code> — the element-side equivalent of <code>class</code>. Prefer it over <code>Array</code> whenever the list belongs in the document, so CSS and Quark can select on it (<code>usage-meter[feature-tags~=&quot;a&quot;]</code>).</p>\n<h2 id=\"md-built-in-instance-props\">Built-in instance props</h2>\n<p><code>isMounted</code>, <code>isMoving</code>, <code>isAdopted</code>, <code>wasMounted</code> exist on every element. They are instance-only; list them in <code>reflectDefaultProps: [&quot;isMounted&quot;]</code> to reflect them as attributes (<code>is-mounted</code>).</p>\n<h2 id=\"md-naming-rules\">Naming rules</h2>\n<p>Enforced at definition time or by convention:</p>\n<ul>\n<li>Custom attributes must contain a dash (<code>max-count</code>, <code>is-open</code>), so they can never collide with a native attribute — now or in the future. Dev mode warns on dash-less, <code>data-*</code>, and <code>aria-*</code> attributes.</li>\n<li>Booleans read as assertions: <code>is-loading</code>, <code>did-fail</code>, <code>has-rendered</code>, <code>should-fetch</code>.</li>\n<li>Events are tag-prefixed (<code>press-tracker-press</code>), never bare (<code>change</code>).</li>\n<li>Attribute names may not start with <code>q-</code>, <code>n-</code>, <code>on-</code>, or <code>off-</code> (reserved by Quark and Neutron).</li>\n<li>Prop names may not shadow Neutron internals or effect keywords (<code>returns</code>, <code>content</code>, lifecycle names, <code>_n_</code>, <code>_q_</code>).</li>\n<li>Private state and methods take a leading underscore.</li>\n<li>Loosely couple: element-typed props use <code>store: &quot;weak&quot;</code>, and anything else that holds a node is cleared in <code>onDisconnected</code>.</li>\n</ul>\n",
+    "prop_reactions": "<h1 id=\"md-prop-reactions\">Prop reactions</h1>\n<p>React to one prop, or a batch of them, with the previous values in hand.</p>\n<h2 id=\"md-handlers\">Handlers</h2>\n<include-content data-language=\"ts\"><template>Neutron({ tag: \"echo-field\", props: { fieldValue: String, isFilled: Boolean } })\n  .onPropSet(\"fieldValue\", () =&gt; ({\n    /* fieldValue became truthy for its type */\n    isFilled: true,\n  }))\n  .onPropUnset(\"fieldValue\", () =&gt; ({\n    /* fieldValue became falsy / removed */\n    isFilled: false,\n  }))\n  .onPropChanged(\"fieldValue\", ({ fieldValue }, previous) =&gt; ({\n    /* any change, including unset → set; `previous.fieldValue` is the old value */\n    emit: [\"echo-field-change\", { detail: { fieldValue, previous: previous.fieldValue } }],\n  }))\n  // one handler for a batch of props — runs when any of them changed\n  .onEffect([\"fieldValue\", \"isFilled\"], (el, previous) =&gt; ({\n    emit: [\"echo-field-effect\", { detail: { previous } }],\n  }));</template></include-content>\n<p><code>onPropChanged</code> and <code>onEffect</code> take one name or an array of names. The second argument maps every prop that changed in the batch to its <strong>previous</strong> value.</p>\n<h2 id=\"md-mount-gating\">Mount gating</h2>\n<p>Reactions run only on mounted elements. Changes made before the first connect (attributes parsed from HTML, props set on a detached element) are kept and flushed as one batch on first mount, so reaction handlers always see the settled initial state.</p>\n<h2 id=\"md-no-self-writes\">No self-writes</h2>\n<p>A handler must not set the same prop it is reacting to — Neutron throws a <code>NeutronError</code>. Child effects on element-typed props are the exception, so <code>.onPropSet(&quot;inputEl&quot;, () =&gt; ({ inputEl: { addListener: [...] } }))</code> is allowed.</p>\n",
+    "provision": "<h1 id=\"md-provision\">Provision</h1>\n<p>One property carries everything rich an element publishes to the document, so Quark and app JS have a single place to read it.</p>\n<h2 id=\"md-declaring-a-provision\">Declaring a provision</h2>\n<p>All public, rich data an element exposes to the document goes through one property: <code>provision</code>. Declare it as <code>provision: Object</code> (or a typed constructor), set it from an effect, and tag it <code>@provision</code> in JSDoc.</p>\n<include-content data-language=\"ts\"><template>Neutron({\n  tag: \"provider-ping\",\n  props: { provision: Object },\n})\n  .onConnected(() =&gt; ({ provision: { at: Date.now() } }))\n  .define();</template></include-content>\n<h2 id=\"md-reading-it\">Reading it</h2>\n<p>Every set emits <code>neutron-provision</code> for app JS. Quark reads it on the element itself with <code>prop(&quot;provision&quot;)</code> and re-runs when it is assigned — assign a new object rather than mutating the old one.</p>\n<include-content data-language=\"quark\"><template>provider-ping {\n  $ping: prop(\"provision\");\n  [bind-at] { content: $ping.at; }\n}</template></include-content>\n<h2 id=\"md-ordering\">Ordering</h2>\n<p>Within one <spa-a route-href=\"/nucleus/packages/neutron/effects\" role=\"link\">effect</spa-a>, <code>provision</code> is always applied last, so listeners of <code>neutron-provision</code> see every other prop already settled.</p>\n",
+    "readme": "<h1 id=\"md-neutron\">neutron</h1>\n<p>Define typed custom elements with effect-based lifecycles — props, events, and compose without rewriting the Custom Elements boilerplate.</p>\n<p>Neutron is the element factory of the Nucleus Stack: <code>Neutron({ tag, props })</code> returns a builder you chain lifecycles onto, then <code>define()</code>. Every Nucleus Kit element is a Neutron element, and so is every element you write yourself.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Declarative factory</strong> <code>Neutron({ tag, props }).… .define()</code></li>\n<li><strong>Typed props</strong> Primitives and <code>TokenList</code> reflect to dashed attributes; objects / arrays / elements / promises stay on the instance</li>\n<li><strong>Effect returns</strong> Lifecycles / methods return a POJO (or an array of them) that sets props, emits, listens, calls methods, and styles</li>\n<li><strong>Fine-grained reactions</strong> <code>onPropSet</code> / <code>Unset</code> / <code>Changed</code> / <code>onEffect</code></li>\n<li><strong>Events &amp; broadcasts</strong> Tag-prefixed custom events, cancelable default actions, channel broadcasts</li>\n<li><strong>Commands</strong> <code>onCommand(&quot;--verb&quot;)</code> handles the HTML Command API — <code>&lt;button command commandfor&gt;</code> needs no custom element</li>\n<li><strong>Listener cleanup</strong> Listeners added through effects are removed on disconnect and restored on reconnect</li>\n<li><strong>Compose</strong> Combine builders (<code>Neutron.compose</code>) for mixin-style packages</li>\n<li><strong>Recompose</strong> Import a package&#39;s raw builder, add / remove lifecycles and methods, then <code>define()</code> it yourself</li>\n<li><strong>DevTools</strong> <code>Neutron.attachDevtools()</code> hooks the Nucleus DevTools extension</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>An element owns its own state (attributes) and announces changes (events). It never renders children or reaches into siblings — coordination belongs to Quark. The rules these examples follow are collected in <spa-a route-href=\"/nucleus/docs/best_practices\" role=\"link\">Best Practices</spa-a> and <spa-a route-href=\"/nucleus/docs/creating_elements\" role=\"link\">Creating Elements</spa-a>.</p>\n<include-content data-language=\"ts\"><template>import { Neutron } from \"@excom/neutron\";\n\nexport const PressTracker = Neutron({\n  tag: \"press-tracker\",\n  props: {\n    pressCount: { type: Number, defaultValue: () =&gt; 0 }, // reflects ↔ `press-count`\n  },\n})\n  .onEvent(\"click\", ({ pressCount }) =&gt; ({\n    // effects are declarative instructions, not imperative mutations\n    pressCount: pressCount + 1,\n    emit: [\"press-tracker-press\", { detail: { pressCount: pressCount + 1 } }],\n  }));\n\nPressTracker.define();</template></include-content>\n<include-content data-language=\"html\"><template>&lt;press-tracker press-count=\"0\"&gt;\n  &lt;button&gt;Press&lt;/button&gt;\n&lt;/press-tracker&gt;\n&lt;!-- `press-tracker[press-count=\"3\"]` is now a CSS / Quark selector --&gt;</template></include-content>\n<h3 id=\"md-documentation\">Documentation</h3>\n<p>Defining elements</p>\n<ul>\n<li><spa-a route-href=\"/nucleus/packages/neutron/props\" role=\"link\">Props</spa-a> — typed props, reflection, <code>TokenList</code>, naming rules</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/provision\" role=\"link\">Provision</spa-a> — the one property for published rich data</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/typescript\" role=\"link\">TypeScript</spa-a> — global element types, <code>ConstructorType</code></li>\n</ul>\n<p>Behavior</p>\n<ul>\n<li><spa-a route-href=\"/nucleus/packages/neutron/lifecycles\" role=\"link\">Lifecycles</spa-a> — <code>onConnected</code> &amp; co., destructuring, async pitfalls</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/effects\" role=\"link\">Effects</spa-a> — the object a handler returns</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/prop_reactions\" role=\"link\">Prop reactions</spa-a> — <code>onPropSet</code> / <code>Unset</code> / <code>Changed</code> / <code>onEffect</code></li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/methods\" role=\"link\">Methods</spa-a> — methods as effectors</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/events\" role=\"link\">Events</spa-a> — emits, default actions, broadcasts, listener cleanup</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/commands\" role=\"link\">Commands</spa-a> — <code>onCommand</code> for <code>--verb</code> commands, the <code>command</code> effect</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/promise_props\" role=\"link\">Promise props</spa-a> — <code>onPromiseResolved</code> / <code>Rejected</code></li>\n</ul>\n<p>Composition</p>\n<ul>\n<li><spa-a route-href=\"/nucleus/packages/neutron/compose\" role=\"link\">Compose</spa-a> — stack builders into mixin-style packages</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/recompose\" role=\"link\">Recompose</spa-a> — edit a packaged element before defining it</li>\n</ul>\n<p>Runtime</p>\n<ul>\n<li><spa-a route-href=\"/nucleus/packages/neutron/define\" role=\"link\">Define</spa-a> — <code>define()</code> and class introspection</li>\n<li><spa-a route-href=\"/nucleus/packages/neutron/debug\" role=\"link\">Debug</spa-a> — DevTools hook, loop guard</li>\n</ul>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-state-on-connect\">State on connect</h4>\n<include-content data-language=\"ts\"><template>Neutron({ tag: \"ready-flag\", props: { isReady: Boolean } })\n  .onConnected(() =&gt; ({ isReady: true, emit: [\"ready-flag-ready\"] }))\n  .define();</template></include-content>\n<h4 id=\"md-child-element-effect-across-handlers\">Child element effect across handlers</h4>\n<p>Assign an element prop, then react to it with a nested effect. Listener callbacks that return effects must be <code>defineMethods</code> methods:</p>\n<include-content data-language=\"ts\"><template>Neutron({\n  tag: \"focus-host\",\n  props: {\n    inputEl: { type: HTMLInputElement, store: \"weak\" },\n    isFocused: Boolean,\n  },\n})\n  .defineMethods({\n    handleFocus: () =&gt; ({ isFocused: true, emit: [\"focus-host-focus\"] }),\n    handleBlur: () =&gt; ({ isFocused: false }),\n  })\n  .onConnected((el) =&gt; ({\n    inputEl: el.querySelector(\"input\"),\n  }))\n  .onPropSet(\"inputEl\", ({ handleFocus, handleBlur }) =&gt; ({\n    inputEl: {\n      addListeners: [\n        [\"focus\", handleFocus],\n        [\"blur\", handleBlur],\n      ],\n    },\n  }));</template></include-content>\n",
+    "recompose": "<h1 id=\"md-recompose\">Recompose</h1>\n<p>A builder is open until <code>define()</code> runs: import a package&#39;s raw builder, edit it, then register it yourself.</p>\n<h2 id=\"md-import-the-raw-builder\">Import the raw builder</h2>\n<p>Every element package ships two entries: <code>index.ts</code> (calls <code>.define()</code> and registers the global types) and the raw element source (<code>&lt;element&gt;.ts</code>), which only exports the builder. Import the raw entry, edit it, then register it yourself:</p>\n<include-content data-language=\"ts\"><template>// app.ts — never import \"@excom/detect-browser\" (or nucleus-kit) here: that entry defines the element immediately\nimport { DetectBrowser } from \"@excom/detect-browser/detect-browser\";\n\nDetectBrowser\n  // add lifecycles / methods the package did not ship\n  .onPropSet(\"isStandalone\", () =&gt; ({ emit: [\"detect-browser-standalone\"] }))\n  .defineMethods({ clearInfo: () =&gt; ({ provision: null }) })\n  .define();</template></include-content>\n<p>Most recomposition is exactly that: chaining new lifecycles onto a packaged element. Unregistering is rarer and goes through <code>builtConfig</code>.</p>\n<h2 id=\"md-builtconfig\">builtConfig</h2>\n<p>Every builder exposes its definition as <code>builtConfig</code>, a plain object you can read before <code>define()</code>:</p>\n<table>\n<thead>\n<tr>\n<th>Key</th>\n<th>Shape</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>tag</code></td>\n<td>The packaged tag name (also the event prefix).</td>\n</tr>\n<tr>\n<td><code>props</code></td>\n<td><code>{ [propName]: PropConfig }</code> — the normalized prop configs (<code>type</code>, <code>attr</code>, <code>defaultValue</code>, …).</td>\n</tr>\n<tr>\n<td><code>events</code> / <code>broadcasts</code></td>\n<td><code>{ [name]: { prefixWithTag? } }</code></td>\n</tr>\n<tr>\n<td><code>methods</code></td>\n<td><code>[name, fn][]</code> in definition order.</td>\n</tr>\n<tr>\n<td><code>lifecycles</code></td>\n<td><code>{ constructed, connected, adopted, disconnected, error, effect, propSet, propUnset, propChanged, promiseResolved, promiseRejected, broadcast, event, eventDefault }</code>, each an array of <code>[names, handler]</code> pairs in registration order. <code>names</code> is the prop / event list the handler was registered with (<code>[]</code> for lifecycles without one).</td>\n</tr>\n<tr>\n<td><code>reflectDefaultProps</code> / <code>definitionOpts</code></td>\n<td>As passed to <code>Neutron()</code>.</td>\n</tr>\n</tbody></table>\n<h2 id=\"md-removing-a-lifecycle\">Removing a lifecycle</h2>\n<p>Removal needs the original handler reference, because <code>off*</code> matches by function identity. Index into <code>builtConfig.lifecycles.&lt;lifecycle&gt;[entry][1]</code> and pass that handler to the matching <code>off*</code>:</p>\n<include-content data-language=\"ts\"><template>// stop detecting on connect; the app calls `el.setBrowserInfo()` when it wants to\nDetectBrowser.offConnected(DetectBrowser.builtConfig.lifecycles.connected[0][1]);\n\n// named lifecycles: pass the names too — only those names are detached, the handler keeps any others\nDetectBrowser.offPropSet(\"isStandalone\", DetectBrowser.builtConfig.lifecycles.propSet[0][1]);</template></include-content>\n<p>Indexing by position is intentional for now (a friendlier handle may come later); read <code>builtConfig.lifecycles.&lt;lifecycle&gt;</code> once to see which entry you are after.</p>\n<h2 id=\"md-adding-props\">Adding props</h2>\n<p>Adding props goes through <spa-a route-href=\"/nucleus/packages/neutron/compose\" role=\"link\"><code>Neutron.compose</code></spa-a>, which also leaves the imported builder untouched (it deep-clones):</p>\n<include-content data-language=\"ts\"><template>import { Neutron } from \"@excom/neutron\";\n\nexport const StampedDetectBrowser = Neutron.compose([\n  DetectBrowser,\n  Neutron({ tag: \"detect-browser\", props: { detectedAt: String } }),\n]).onPropSet(\"provision\", () =&gt; ({ detectedAt: new Date().toISOString() }));\n\nStampedDetectBrowser.define();</template></include-content>\n<h2 id=\"md-rules\">Rules</h2>\n<ul>\n<li>Everything must happen before <code>define()</code>. The runtime config is built at that moment; later <code>on*</code> / <code>off*</code> / <code>defineMethods</code> calls return the builder but change nothing.</li>\n<li>The raw builder is a module singleton — an in-place edit is visible to every importer. Use <code>Neutron.compose</code> when you want a modified copy instead.</li>\n<li>Added handlers run after the packaged ones for the same lifecycle (registration order) and batch into the same effect pass.</li>\n<li><code>define(&quot;other-tag&quot;)</code> registers the class under a different name. Events configured with <code>prefixWithTag</code> keep the packaged prefix, because the prefix comes from the builder&#39;s <code>tag</code>, not from the registered name.</li>\n<li>Skipping <code>index.ts</code> also skips its <code>declare global</code> block — add your own (see <spa-a route-href=\"/nucleus/packages/neutron/typescript\" role=\"link\">TypeScript</spa-a>) if you want the tag typed.</li>\n</ul>\n",
+    "typescript": "<h1 id=\"md-typescript\">TypeScript</h1>\n<p>Expose an element&#39;s inferred type the way the DOM exposes its own elements, so queries and <code>createElement</code> need no casts.</p>\n<h2 id=\"md-global-element-types\">Global element types</h2>\n<p><code>Neutron()</code> infers the element type from <code>props</code> and <code>defineMethods</code>. Publish it as a global <code>HTML*Element</code> interface plus an <code>HTMLElementTagNameMap</code> entry, so <code>document.querySelector(&quot;press-tracker&quot;)</code> and <code>document.createElement(&quot;press-tracker&quot;)</code> are typed without casts:</p>\n<include-content data-language=\"ts\"><template>// index.ts — the package entry defines and types the element\nimport { PressTracker } from \"./press-tracker\";\n\nPressTracker.define();\n\nexport { PressTracker };\n\ntype T_HTMLPressTrackerElement = typeof PressTracker.CustomElement;\ndeclare global {\n  interface HTMLPressTrackerElement extends T_HTMLPressTrackerElement {}\n  interface Window {\n    HTMLPressTrackerElement: HTMLPressTrackerElement;\n  }\n  interface HTMLElementTagNameMap {\n    \"press-tracker\": HTMLPressTrackerElement;\n  }\n}\nexport type { HTMLPressTrackerElement };</template></include-content>\n<p><code>CustomElement</code> is a type-only handle on the builder (there is no runtime value); <code>Props</code> is the inferred props object.</p>\n<h2 id=\"md-typed-rich-props\">Typed rich props</h2>\n<p>To type a rich prop more precisely than its constructor allows, cast the constructor with <code>ConstructorType&lt;T&gt;</code>:</p>\n<include-content data-language=\"ts\"><template>import { ConstructorType, Neutron } from \"@excom/neutron\";\n\ntype FeatureInfo = { fullSupport: string[]; noSupport: string[] };\n\nNeutron({\n  tag: \"detect-features\",\n  props: {\n    provision: Object as unknown as ConstructorType&lt;FeatureInfo&gt;, // el.provision: FeatureInfo\n  },\n});</template></include-content>\n<h2 id=\"md-event-types\">Event types</h2>\n<p>Document Neutron-emitted events with <code>TEvent</code> plus <code>type</code> and <code>detail</code> — see <spa-a route-href=\"/nucleus/packages/neutron/events#md-typing-events\" role=\"link\">Events</spa-a>.</p>\n"
+  },
+  "docSections": [
+    {
+      "id": "defining-elements",
+      "title": "Defining Elements",
+      "docs": [
+        {
+          "name": "props",
+          "title": "Props"
+        },
+        {
+          "name": "provision",
+          "title": "Provision"
+        },
+        {
+          "name": "typescript",
+          "title": "TypeScript"
+        }
+      ]
+    },
+    {
+      "id": "behavior",
+      "title": "Behavior",
+      "docs": [
+        {
+          "name": "lifecycles",
+          "title": "Lifecycles"
+        },
+        {
+          "name": "effects",
+          "title": "Effects"
+        },
+        {
+          "name": "prop_reactions",
+          "title": "Prop reactions"
+        },
+        {
+          "name": "methods",
+          "title": "Methods"
+        },
+        {
+          "name": "events",
+          "title": "Events"
+        },
+        {
+          "name": "commands",
+          "title": "Commands"
+        },
+        {
+          "name": "promise_props",
+          "title": "Promise props"
+        }
+      ]
+    },
+    {
+      "id": "composition",
+      "title": "Composition",
+      "docs": [
+        {
+          "name": "compose",
+          "title": "Compose"
+        },
+        {
+          "name": "recompose",
+          "title": "Recompose"
+        }
+      ]
+    },
+    {
+      "id": "runtime",
+      "title": "Runtime",
+      "docs": [
+        {
+          "name": "define",
+          "title": "Define"
+        },
+        {
+          "name": "debug",
+          "title": "Debug"
+        }
+      ]
+    }
+  ],
+  "installation": {
+    "name": "@excom/neutron",
+    "shortName": "neutron",
+    "version": "0.1.0",
+    "description": "Element factory of the Nucleus Stack — typed custom elements with effect-based lifecycles",
+    "packageType": "element-base",
+    "install": {
+      "npm": "npm install @excom/neutron"
+    },
+    "imports": {
+      "js": "import { /* … */ } from \"@excom/neutron\";"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [],
+  "exportedFiles": {}
+}

package/support/tests/commands.test.ts

@@ -0,0 +1,330 @@
+import {
+  createCommandEvent,
+  invokeCommand,
+  isCustomCommand,
+} from "../../src/command";
+import { Neutron } from "../../src/neutron";
+import { NeutronError } from "../../src/neutron-error";
+import {
+  afterEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  vi,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { KitLogger } from "@excom/kit-logger";
+
+const microtask = () => Promise.resolve();
+
+describe("command events", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+    delete (globalThis as { CommandEvent?: unknown }).CommandEvent;
+  });
+
+  it("accepts only dashed-ident custom command names", () => {
+    expect(isCustomCommand("--fetch")).toBe(true);
+    expect(isCustomCommand("--open-stage")).toBe(true);
+    expect(isCustomCommand("fetch")).toBe(false);
+    expect(isCustomCommand("show-modal")).toBe(false);
+    expect(isCustomCommand("--")).toBe(false);
+    expect(isCustomCommand("-- x")).toBe(false);
+    expect(isCustomCommand(undefined)).toBe(false);
+  });
+
+  it("builds a non-bubbling, cancelable, composed event without the platform class", () => {
+    const source = document.createElement("button");
+    const event = createCommandEvent("--fetch", { source });
+    expect(event.type).toBe("command");
+    expect(event.bubbles).toBe(false);
+    expect(event.cancelable).toBe(true);
+    expect(event.composed).toBe(true);
+    expect(event.command).toBe("--fetch");
+    expect(event.source).toBe(source);
+    expect(createCommandEvent("--x").source).toBe(null);
+  });
+
+  it("uses the platform CommandEvent when the browser has one", () => {
+    class FakeCommandEvent extends Event {
+      command: string;
+      source: Element | null;
+      constructor(type: string, init: any) {
+        super(type, init);
+        this.command = init.command;
+        this.source = init.source;
+      }
+    }
+    (globalThis as any).CommandEvent = FakeCommandEvent;
+    const source = document.createElement("button");
+    const event = createCommandEvent("--go", { source });
+    expect(event).toBeInstanceOf(FakeCommandEvent);
+    expect(event.command).toBe("--go");
+    expect(event.source).toBe(source);
+    expect(event.cancelable).toBe(true);
+  });
+
+  it("invokeCommand dispatches a custom command at the target and returns the event", () => {
+    const target = fixture<HTMLDivElement>(`<div></div>`);
+    const source = document.createElement("button");
+    const seen = vi.fn();
+    target.addEventListener("command", seen);
+    const event = invokeCommand(target, "--go", source);
+    expect(seen).toHaveBeenCalledTimes(1);
+    expect(seen.mock.calls[0][0]).toBe(event);
+    expect(event?.source).toBe(source);
+    expect(event?.target).toBe(target);
+  });
+
+  it("invokeCommand warns and does nothing for a built-in verb without the Command API", () => {
+    const warn = vi.spyOn(KitLogger, "warn").mockImplementation(() => {});
+    const target = fixture<HTMLDialogElement>(`<dialog></dialog>`);
+    // the rig's test shim emulates the API; hide it for this case
+    const shim = Object.getOwnPropertyDescriptor(
+      HTMLButtonElement.prototype,
+      "commandForElement"
+    );
+    delete (HTMLButtonElement.prototype as any).commandForElement;
+    try {
+      expect("commandForElement" in HTMLButtonElement.prototype).toBe(false);
+      expect(invokeCommand(target, "show-modal")).toBe(null);
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn.mock.calls[0][0]).toMatch(/needs the HTML Command API/);
+      expect(document.querySelector("button")).toBe(null);
+    } finally {
+      if (shim) {
+        Object.defineProperty(
+          HTMLButtonElement.prototype,
+          "commandForElement",
+          shim
+        );
+      }
+    }
+  });
+
+  it("a click on <button command commandfor> reaches the target in the test rig", () => {
+    const root = fixture<HTMLDivElement>(
+      `<div><button type="button" command="--go" commandfor="shim-target"></button><section id="shim-target"></section></div>`
+    );
+    const seen = vi.fn();
+    root.querySelector("section")!.addEventListener("command", seen);
+    root.querySelector("button")!.click();
+    expect(seen).toHaveBeenCalledTimes(1);
+    expect(seen.mock.calls[0][0].command).toBe("--go");
+    expect(seen.mock.calls[0][0].source).toBe(root.querySelector("button"));
+  });
+
+  it("invokeCommand runs a built-in verb through a proxy button when the API exists", () => {
+    const invoked: Array<{ command: string; target: Element; type: string }> =
+      [];
+    Object.defineProperty(HTMLButtonElement.prototype, "commandForElement", {
+      configurable: true,
+      writable: true,
+      value: null,
+    });
+    vi.spyOn(HTMLButtonElement.prototype, "click").mockImplementation(
+      function (this: any) {
+        invoked.push({
+          command: this.command,
+          target: this.commandForElement,
+          type: this.type,
+        });
+        expect(this.isConnected).toBe(true);
+      }
+    );
+    try {
+      const target = fixture<HTMLDialogElement>(`<dialog></dialog>`);
+      expect(invokeCommand(target, "show-modal")).toBe(null);
+      expect(invoked).toEqual([
+        { command: "show-modal", target, type: "submit" },
+      ]);
+      expect(document.querySelector("button")).toBe(null);
+    } finally {
+      delete (HTMLButtonElement.prototype as any).commandForElement;
+    }
+  });
+});
+
+describe("Lifecycles: onCommand", () => {
+  const openFn = vi.fn();
+  const anyFn = vi.fn();
+  Neutron({
+    tag: "command-host",
+    props: { isOpen: Boolean, lastVerb: String, sourceId: String },
+  })
+    .onCommand("--open", (_, e) => {
+      openFn(e);
+      return { isOpen: true, sourceId: e.source?.id ?? "none" };
+    })
+    .onCommand(["--open", "--close"], ({ isOpen }, e) => {
+      anyFn(e.command);
+      return { lastVerb: e.command, ...(e.command === "--close" && isOpen ? { isOpen: false } : {}) };
+    })
+    .define();
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    openFn.mockClear();
+    anyFn.mockClear();
+  });
+
+  it("runs the handlers whose verb matches, after the dispatch, with the event", async () => {
+    const el = fixture<any>(`<command-host></command-host>`);
+    const source = document.createElement("button");
+    source.id = "opener";
+    const event = invokeCommand(el, "--open", source)!;
+    // not synchronous: the whole dispatch may still preventDefault()
+    expect(openFn).not.toHaveBeenCalled();
+    expect(el.isOpen).toBeFalsy();
+    await microtask();
+    expect(openFn).toHaveBeenCalledTimes(1);
+    expect(openFn.mock.calls[0][0]).toBe(event);
+    expect(anyFn).toHaveBeenCalledWith("--open");
+    expect(el).dom.to.equalTag(
+      `<command-host is-open source-id="opener" last-verb="--open"></command-host>`
+    );
+
+    invokeCommand(el, "--close");
+    await microtask();
+    expect(openFn).toHaveBeenCalledTimes(1);
+    expect(el).dom.to.equalTag(
+      `<command-host source-id="opener" last-verb="--close"></command-host>`
+    );
+  });
+
+  it("ignores other verbs, prevented commands and bubbling look-alikes", async () => {
+    const el = fixture<any>(`<command-host><span></span></command-host>`);
+    invokeCommand(el, "--other");
+    await microtask();
+    expect(openFn).not.toHaveBeenCalled();
+    expect(anyFn).not.toHaveBeenCalled();
+
+    el.addEventListener("command", (e: Event) => e.preventDefault(), {
+      once: true,
+    });
+    invokeCommand(el, "--open");
+    await microtask();
+    expect(openFn).not.toHaveBeenCalled();
+    expect(el.isOpen).toBeFalsy();
+
+    // a hand-made bubbling "command" event from a descendant is not for this element
+    const fake = new Event("command", { bubbles: true }) as any;
+    fake.command = "--open";
+    el.querySelector("span").dispatchEvent(fake);
+    await microtask();
+    expect(openFn).not.toHaveBeenCalled();
+  });
+
+  it("registers one listener per handler, dropped on disconnect and restored on reconnect", async () => {
+    const el = fixture<any>(`<command-host></command-host>`);
+    expect(
+      el._n_.eventListeners.filter(([type]) => type === "command").length
+    ).toBe(2);
+    el.remove();
+    await wait(0);
+    invokeCommand(el, "--open");
+    await microtask();
+    expect(openFn).not.toHaveBeenCalled();
+    document.body.append(el);
+    invokeCommand(el, "--open");
+    await microtask();
+    expect(openFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects built-in verbs at registration and unregisters by handler", () => {
+    const B = Neutron({ tag: "command-names", props: {} });
+    expect(() => B.onCommand("show-modal", () => ({}))).toThrow(NeutronError);
+    expect(() => B.onCommand("show-modal", () => ({}))).toThrow(
+      /must start with "--"/
+    );
+    expect(() => B.onCommand(["--ok", "close"], () => ({}))).toThrow(
+      /got "close"/
+    );
+    const f = () => ({});
+    B.onCommand("--ok", f);
+    expect(B.builtConfig.lifecycles.command).toEqual([[["--ok"], f]]);
+    expect((f as any)._logSignature).toBe('onCommand("--ok")');
+    B.offCommand("--ok", f);
+    expect(B.builtConfig.lifecycles.command).toEqual([]);
+  });
+
+  it("merges command handlers through compose", async () => {
+    const seen: string[] = [];
+    const Base = Neutron({ tag: "command-base", props: {} }).onCommand(
+      "--a",
+      () => {
+        seen.push("base");
+      }
+    );
+    Neutron.compose([
+      Base,
+      Neutron({ tag: "command-composed", props: {} }),
+    ])
+      .onCommand("--a", () => {
+        seen.push("composed");
+      })
+      .define();
+    const el = fixture<any>(`<command-composed></command-composed>`);
+    expect(el._n_.ctr.builtConfig.lifecycles.command.length).toBe(2);
+    invokeCommand(el, "--a");
+    await microtask();
+    expect(seen).toEqual(["base", "composed"]);
+  });
+});
+
+describe("Effects: command / commands", () => {
+  Neutron({ tag: "command-invoker", props: { targetEl: HTMLElement } })
+    .defineMethods({
+      fire: ({ targetEl }) => ({
+        command: ["--fetch", { target: targetEl }],
+      }),
+      fireMany: ({ targetEl }) => ({
+        commands: [
+          ["--one", { target: targetEl }],
+          ["--two", { target: targetEl, source: null }],
+        ],
+      }),
+      fireSelf: () => ({ command: ["--self"] }),
+    })
+    .define();
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("dispatches at the target with the element as source, last in the effect", () => {
+    const root = fixture<HTMLDivElement>(
+      `<div><command-invoker></command-invoker><section></section></div>`
+    );
+    const invoker = root.querySelector("command-invoker") as any;
+    const section = root.querySelector("section")!;
+    const seen: Array<[string, Element | null, Element | null]> = [];
+    const record = (e: any) =>
+      seen.push([e.command, e.source, e.currentTarget]);
+    section.addEventListener("command", record);
+    invoker.addEventListener("command", record);
+
+    invoker.targetEl = section;
+    invoker.fire();
+    expect(seen).toEqual([["--fetch", invoker, section]]);
+
+    invoker.fireMany();
+    expect(seen.slice(1)).toEqual([
+      ["--one", invoker, section],
+      ["--two", null, section],
+    ]);
+
+    invoker.fireSelf();
+    expect(seen.at(-1)).toEqual(["--self", invoker, invoker]);
+  });
+
+  it("rejects a non-array command effect", () => {
+    Neutron({ tag: "command-bad", props: {} })
+      .defineMethods({ bad: () => ({ command: "--x" as any }) })
+      .define();
+    const el = fixture<any>(`<command-bad></command-bad>`);
+    expect(() => el.bad()).toThrow(/arguments must be an array/);
+  });
+});