@symbiote-native/engine 1.3.0 → 1.3.1

package/build/post-commit.js

@@ -1,11 +1,6 @@
-// Post-commit hooks: run once after every native commit that changed the tree (after
-// completeRoot, when fresh Fabric tags have just been assigned). The seam exists so a
-// consumer that needs a node's committed tag — today only the Animated native driver,
-// which binds a props node to a view tag — can retry work that ran too early under an
-// async-batched commit (Vue/Svelte schedule completeRoot on a microtask, so lifecycle
-// code can reach a node before its tag exists; React commits synchronously and never
-// queues). A neutral module so commit.ts and animated/props.ts share it without a
-// dependency cycle.
+// Run once after every commit that changed the tree, once fresh Fabric tags exist — lets a
+// consumer needing a node's committed tag (the Animated native driver) retry work that ran too
+// early under an async-batched commit. Shared by commit.ts and animated/props.ts, cycle-free.
 const hooks = new Set();
 export function registerPostCommit(hook) {
     hooks.add(hook);

package/build/process-aspect-ratio.js

@@ -1,10 +1,6 @@
-// JS-side port of RN's processAspectRatio (Libraries/StyleSheet/processAspectRatio.js).
-// Same root cause family as boxShadow/filter: RN registers `aspectRatio` with a JS
-// `process` because enableNativeCSSParsing() defaults to false, so the CSS ratio string
-// ('16 / 9') is resolved to a number IN JS before native. A plain number (the common,
-// already-working form) passes through untouched; this is a no-op for it.
-//
-// RN throws via invariant() in __DEV__ on a malformed value; we dlog and return undefined.
+// JS-side port of RN's processAspectRatio: resolves a CSS ratio string ('16 / 9') to a number
+// before native, same root cause as boxShadow/filter. A plain number passes through untouched.
+// RN throws via invariant() on a malformed value; here we dlog and return undefined instead.
 import { dlog } from './debug.js';
 // RN processAspectRatio.js:15-63. number → number; ratio string → number; invalid → undefined.
 export function processAspectRatio(aspectRatio) {

package/build/process-background-longhands.js

@@ -1,20 +1,12 @@
 // RN's own processBackgroundSize / processBackgroundPosition / processBackgroundRepeat, imported
 // rather than ported.
-//
-// Why they are needed at all: ReactNativeStyleAttributes registers all three with
-// `nativeCSSParsing ? true : {process: processX}` (:50, :54, :58), and enableNativeCSSParsing()
-// defaults to false - so RN's stock path parses the CSS string into the per-axis structure
-// Fabric's C++ expects. We registered `experimental_backgroundImage` and not its three siblings,
-// so a string for any of them reached native unparsed: dropped on iOS, cast to the wrong
-// ReadableMap type on Android. Same shape as the process-transform incident.
-//
-// Why importing is free here even by this repo's strictest reading: all three upstream files
-// contain ONLY `import type` lines. Their value-import closure is empty - no processColor, no
-// Platform, no TurboModule floor, no renderer. There is nothing to weigh.
-//
-// Why no try/catch, unlike the other upstream wrappers: these three do not validate through
-// `invariant`. They answer `[]` for anything they cannot parse, which upstream's own comment calls
-// "do not apply any background" - so refusal is a RETURN here, not a throw.
+// Needed because enableNativeCSSParsing() defaults to false, so RN's stock JS path parses the CSS
+// string into the per-axis structure Fabric's C++ expects. Without it a string for any of these
+// three reached native unparsed: dropped on iOS, cast to the wrong ReadableMap type on Android.
+// Importing is free here: all three upstream files contain only `import type` lines, so their
+// value-import closure is empty — no processColor, no Platform, no TurboModule floor, no renderer.
+// No try/catch, unlike the other upstream wrappers: these three don't validate through invariant,
+// they answer `[]` for anything unparseable — so refusal is a return here, not a throw.
 import { dlog } from './debug.js';
 // @ts-expect-error - untyped Flow source. Metro compiles it; vitest.config.ts strips the types.
 import processBackgroundSizeUpstream from 'react-native/Libraries/StyleSheet/processBackgroundSize';
@@ -22,10 +14,9 @@ import processBackgroundSizeUpstream from 'react-native/Libraries/StyleSheet/pro
 import processBackgroundPositionUpstream from 'react-native/Libraries/StyleSheet/processBackgroundPosition';
 // @ts-expect-error - untyped Flow source. Metro compiles it; vitest.config.ts strips the types.
 import processBackgroundRepeatUpstream from 'react-native/Libraries/StyleSheet/processBackgroundRepeat';
-// An empty result is upstream's way of saying it parsed nothing usable. The payload builder's
-// rule is that a refused processor leaves the key ABSENT, so it must not become `[]` - an empty
-// array is a real value, and committing one asks native to apply "no background size" rather than
-// leaving the declaration unset.
+// An empty result means upstream parsed nothing usable. The payload builder's rule is that a
+// refused processor leaves the key absent — `[]` is a real value, committing it would ask native
+// to apply "no background size" rather than leave the declaration unset.
 function orAbsent(parsed, key, value) {
     if (!Array.isArray(parsed) || parsed.length === 0) {
         dlog(`${key}: RN parsed nothing usable from ${JSON.stringify(value)}`);

package/build/process-filter.js

@@ -1,22 +1,14 @@
-// RN's own processFilter, imported rather than ported.
-//
-// Why it is needed at all: RN registers `filter` with `nativeCSSParsing ? true : {process:
-// processFilter}`, and enableNativeCSSParsing() defaults to false - so the stock path parses the
-// CSS string / structured array in JS and native never sees the raw string.
-//
-// Why the try/catch, unlike processBoxShadow's wrapper: upstream throws exactly once
-// (processFilter.js:120, a TypeError for an input that is neither string nor array), and a commit
-// path must never throw. fabric-props narrows before calling, but `processFilter` is on the public
-// barrel, so the guard is reachable rather than ceremonial.
-//
-// What changed by importing: a drop-shadow's colour now goes through RN's own `processColor`
-// (upstream imports it directly at processFilter.js:16) instead of our injected
-// `setColorProcessor` seam. On a real host those are the same function - bootstrapHost injects
-// exactly `processColor` - so the seam simply no longer governs the colour inside a filter.
-//
-// Platform caveat worth keeping in view when demoing this: on iOS RN paints only `brightness` and
-// `opacity` unless enableSwiftUIBasedFilters is on, so grayscale/blur/saturate/contrast/hueRotate
-// parse correctly here and still do nothing on screen.
+// RN's own processFilter, imported rather than ported: enableNativeCSSParsing() defaults to
+// false, so the stock path parses the CSS string / structured array in JS and native never sees
+// the raw string.
+// try/catch because upstream throws once (a TypeError for a non-string/array input) and a commit
+// path must never throw; fabric-props narrows first, but processFilter is on the public barrel
+// too, so the guard here stays reachable, not ceremonial.
+// A drop-shadow's color goes through RN's own processColor here, not our injected
+// setColorProcessor seam — the same function on a real host, since bootstrapHost injects exactly
+// processColor, so the seam simply doesn't govern a filter's color.
+// iOS caveat: RN paints only brightness/opacity unless enableSwiftUIBasedFilters is on, so
+// grayscale/blur/saturate/contrast/hueRotate parse fine here and still paint nothing on screen.
 import { dlog } from './debug.js';
 // @ts-expect-error - untyped Flow source. Metro compiles it; vitest.config.ts strips the types.
 import processFilterUpstream from 'react-native/Libraries/StyleSheet/processFilter';

package/build/process-font-variant.js

@@ -1,10 +1,6 @@
-// JS-side port of RN's processFontVariant (Libraries/StyleSheet/processFontVariant.js).
-// Same root cause family as boxShadow/filter: RN registers `fontVariant` with a JS
-// `process` because enableNativeCSSParsing() defaults to false, so a space-separated CSS
-// string ('small-caps tabular-nums') is split into the array native expects IN JS. An
-// array (the common, already-working form) passes through untouched; this is a no-op
-// for it.
-// RN processFontVariant.js:15-28. Array → array; space-separated string → array of variants.
+// JS-side port of RN's processFontVariant: splits a space-separated CSS string
+// ('small-caps tabular-nums') into the array native expects, same root cause as
+// boxShadow/filter. An array (the common, already-working form) passes through as a no-op.
 export function processFontVariant(fontVariant) {
     if (Array.isArray(fontVariant)) {
         return fontVariant;

package/build/registry.d.ts

@@ -29,39 +29,6 @@ export declare function registerComponent(name: string, registration?: IComponen
 export declare function isRegisteredEvent(component: string, listener: string): boolean;
 export declare function registeredNativeEvent(component: string, raw: string): INativeEventBinding | undefined;
 export declare function registeredProcessor(component: string, key: string): IPropProcessor | undefined;
-/**
- * A component's ViewConfig processors, as a payload fold — or undefined when it has none.
- *
- * WHY A FOLD AND NOT A LOOKUP AT PAYLOAD-BUILD TIME. The payload is built in C++ on a device
- * (`core/engine/cpp/SymbioteFabricProps.cpp`) and only in JS headless, and this registry cannot
- * cross that boundary: it is populated lazily from an INJECTED `ReactNativeViewConfigRegistry`
- * lookup, holding JS closures. `payloadFold` is the one seam that already runs in JS on both paths
- * — the C++ probes it once per node and calls back — so putting the processors there is what makes
- * a third-party view behave the same on a device as it does in a test.
- *
- * The alternative was a list of prop NAMES in C++, and that is what this replaces. It cost a day:
- * `@symbiote-native/slider` declares `minimumTrackTintColor` / `maximumTrackTintColor` in its own
- * ViewConfig, neither name was in the C++ list, both reached Fabric as CSS strings, and iOS answers
- * a string colour with `clearColor()`. The slider dragged and reported values correctly with no
- * track drawn at all. Any list of names is a list somebody has to extend for a component we have
- * never seen — which would have meant editing C++ to add a native view, and that is exactly the
- * coupling `<native_core_is_untouched>` exists to prevent.
- *
- * Resolved ONCE per component and cached, because `createElement` asks per node. A built-in
- * short-circuits inside `resolve` before any of this.
- */
-/**
- * The prop names a component's OWN ViewConfig claims a processor for — i.e. exactly the keys
- * `configPayloadFold` has already converted by the time the payload builder's own passes run.
- *
- * It exists so "a colour is converted exactly once" can be a stated rule rather than a lucky one.
- * The overlap is real: `thumbTintColor` is claimed by @symbiote-native/slider's config AND by the
- * engine's built-in COLOR_PROPS, and for a while nothing broke only because a processed colour came
- * back as a NUMBER and the engine skipped numbers. That guard died when a numeric colour became
- * processable in its own right — an author writing `color: 0xff0000ff` means rrggbbaa and owes the
- * same rotation a string owes — and the second conversion then turned an already-correct int into
- * a different colour.
- */
 export declare function configProcessedKeys(component: string): ReadonlySet<string> | undefined;
 export declare function configPayloadFold(component: string): IPayloadFold | undefined;
 export {};

package/build/registry.js

@@ -1,33 +1,19 @@
-// Runtime metadata for native Fabric views, DERIVED BY DEFAULT. Any RN library
-// already ships its own ViewConfig: codegen registers it into RN's
-// ReactNativeViewConfigRegistry the moment the library's native-component module is
-// imported. That config carries everything the shared engine can't infer: which
-// events the view emits (bubblingEventTypes / directEventTypes) and how to process
-// its props (validAttributes[*].process, e.g. processColor). So we DON'T transcribe
-// any of it, and we don't mark anything "third-party": there is no
-// per-package registration to maintain. The engine reads the config for ANY
-// component on first use. Install a community view library, render it, done.
-//
-// shared must stay react-native-free (the headless harness runs in plain Node), so
-// the ViewConfig lookup is INJECTED, exactly like the color processor: the adapter
-// wires `setNativeViewConfigSource(ReactNativeViewConfigRegistry.get)` on a real
-// host, where that one source covers BOTH RN core and every library.
-//
-// The ONLY explicit list is OUR OWN built-in primitives (BUILTIN_COMPONENTS): a
-// finite set we own, which keep their hand-tuned tables (view-config events, commit
-// COLOR_PROPS) and are never read from the source, so they can't drift. Everything
-// NOT in that set derives. The list never grows with the community; it grows only
-// when we add a core primitive of our own.
+// Runtime metadata for native Fabric views, derived by default. Any RN library ships its own
+// ViewConfig via codegen, carrying everything the shared engine can't infer — which events a view
+// emits, how to process its props. Nothing is transcribed; read from the config on first use.
+// shared must stay react-native-free (the headless harness runs in plain Node), so the ViewConfig
+// lookup is injected, exactly like the color processor: the adapter wires
+// setNativeViewConfigSource(ReactNativeViewConfigRegistry.get) on a real host.
+// The only explicit list is our own built-in primitives (BUILTIN_COMPONENTS): a finite set we own,
+// which keep their hand-tuned tables and are never read from the source, so they can't drift. It
+// grows only when we add a core primitive of our own, never for a community package.
 import { isRecord } from './type-guards.js';
 const EMPTY = {
     listeners: new Set(),
     byRaw: new Map(),
     processors: new Map(),
 };
-// OUR own primitives: the finite set shared hand-tunes (view-config events,
-// commit COLOR_PROPS). The source is never consulted for these, so they can't
-// drift. Everything else derives. This list grows only when WE add a core
-// primitive, never for a community package.
+// Our own primitives — see the module header for why the source is never consulted for these.
 const BUILTIN_COMPONENTS = new Set([
     'RCTView',
     'RCTText',
@@ -156,39 +142,18 @@ export function registeredNativeEvent(component, raw) {
 export function registeredProcessor(component, key) {
     return resolve(component).processors.get(key);
 }
-/**
- * A component's ViewConfig processors, as a payload fold — or undefined when it has none.
- *
- * WHY A FOLD AND NOT A LOOKUP AT PAYLOAD-BUILD TIME. The payload is built in C++ on a device
- * (`core/engine/cpp/SymbioteFabricProps.cpp`) and only in JS headless, and this registry cannot
- * cross that boundary: it is populated lazily from an INJECTED `ReactNativeViewConfigRegistry`
- * lookup, holding JS closures. `payloadFold` is the one seam that already runs in JS on both paths
- * — the C++ probes it once per node and calls back — so putting the processors there is what makes
- * a third-party view behave the same on a device as it does in a test.
- *
- * The alternative was a list of prop NAMES in C++, and that is what this replaces. It cost a day:
- * `@symbiote-native/slider` declares `minimumTrackTintColor` / `maximumTrackTintColor` in its own
- * ViewConfig, neither name was in the C++ list, both reached Fabric as CSS strings, and iOS answers
- * a string colour with `clearColor()`. The slider dragged and reported values correctly with no
- * track drawn at all. Any list of names is a list somebody has to extend for a component we have
- * never seen — which would have meant editing C++ to add a native view, and that is exactly the
- * coupling `<native_core_is_untouched>` exists to prevent.
- *
- * Resolved ONCE per component and cached, because `createElement` asks per node. A built-in
- * short-circuits inside `resolve` before any of this.
- */
-/**
- * The prop names a component's OWN ViewConfig claims a processor for — i.e. exactly the keys
- * `configPayloadFold` has already converted by the time the payload builder's own passes run.
- *
- * It exists so "a colour is converted exactly once" can be a stated rule rather than a lucky one.
- * The overlap is real: `thumbTintColor` is claimed by @symbiote-native/slider's config AND by the
- * engine's built-in COLOR_PROPS, and for a while nothing broke only because a processed colour came
- * back as a NUMBER and the engine skipped numbers. That guard died when a numeric colour became
- * processable in its own right — an author writing `color: 0xff0000ff` means rrggbbaa and owes the
- * same rotation a string owes — and the second conversion then turned an already-correct int into
- * a different colour.
- */
+// A component's ViewConfig processors, as a payload fold — or undefined when it has none. Not a
+// lookup at payload-build time: the payload is built in C++ on a device and this registry can't
+// cross that boundary (it's populated lazily from an injected JS-closure-holding lookup).
+// payloadFold is the one seam that already runs in JS on both paths, so putting the processors
+// there is what makes a third-party view behave the same on device as in a test. The alternative,
+// a list of prop names hardcoded in C++, needs editing native code for every new component we see.
+// Resolved once per component and cached, since createElement asks per node. A built-in
+// short-circuits inside resolve before any of this.
+// The prop names a component's own ViewConfig claims a processor for — exactly the keys
+// configPayloadFold has already converted by the time the payload builder's own passes run.
+// Exists so "a colour is converted exactly once" is a stated rule, not a lucky one: an overlap
+// between a third-party config and the engine's own COLOR_PROPS would otherwise double-convert.
 export function configProcessedKeys(component) {
     const cached = keysCache.get(component);
     if (cached !== undefined)

package/build/report-error.js

@@ -1,21 +1,8 @@
 // Hand an error to the host the way React Native itself does, for the seams where an adapter
 // catches something its framework would otherwise have surfaced on its own.
-//
-// RN routes an uncaught render error through ReactFiberErrorDialog -> ExceptionsManager
-// (Libraries/Core/ReactFiberErrorDialog.js), which is reachable only by a deep path into RN's
-// Libraries. `global.ErrorUtils` is the same surface through the documented global that
-// @react-native/js-polyfills installs before any module evaluates - RN's own
-// Libraries/vendor/core/ErrorUtils.js is nothing but `export default global.ErrorUtils`. Off a
-// native host (vitest, node smokes) the global is absent and console.error is the whole channel.
-//
-// This is NOT the dlog channel. dlog is DEBUG-gated and therefore the developer's; an error that
-// blanked the screen has to reach the app whether or not anyone turned diagnostics on.
-// Read off globalThis through Reflect rather than named as an identifier, and deliberately NOT
-// declared in an ambient block: react-native ships its own `const ErrorUtils: ErrorUtils` in
-// src/types/globals.d.ts, so a `declare global { var ErrorUtils }` here redeclares it (TS2451) for
-// every package whose tsconfig pulls in RN's types - the engine's own does not, so it typechecks
-// clean here and breaks ngc downstream. RN's declared shape also lists only the two
-// get/setGlobalHandler members, not reportError, which the polyfill does install.
+// Read off globalThis via Reflect, not a named identifier or an ambient declare: react-native
+// ships its own `ErrorUtils` global type, so redeclaring it here breaks any package whose tsconfig
+// pulls in RN's types. RN's declared shape also omits reportError, which the polyfill installs.
 function nativeReporter() {
     const utils = Reflect.get(globalThis, 'ErrorUtils');
     if (typeof utils !== 'object' || utils === null)
@@ -54,8 +41,7 @@ export function reportUncaughtError(value, info) {
     const report = nativeReporter();
     if (report !== null) {
         // Exactly one channel, never both: RN routes console.error into LogBox as well, so logging
-        // here too would double-report every error. Upstream returns false from showErrorDialog for
-        // this same reason (Libraries/Core/ReactFiberErrorDialog.js:57).
+        // here too would double-report every error.
         report(error);
         return;
     }

package/build/structured-style.d.ts

@@ -1,10 +1 @@
-/**
- * A style value with its structured keys resolved — the same value by identity when there was
- * nothing to resolve, which is nearly always.
- *
- * Accepts what a style slot can hold: one object, or a (nested) array of them. An array is not
- * memoized — `pushClassStyle` mints a fresh one on every publish, so a cache keyed on it could
- * never hit; its ENTRIES carry the memo instead, and the original array comes back untouched when
- * none of them moved.
- */
 export declare function resolveStructuredStyle(style: unknown): unknown;

package/build/structured-style.js

@@ -1,22 +1,12 @@
 // The ten style keys RN parses in JS before native, and the one place they are resolved.
-//
-// WHY THEY RUN AT WRITE TIME AND NOT AT PAYLOAD-BUILD TIME. On a device the payload is built by
-// `core/engine/cpp/SymbioteFabricProps.cpp`, which does not carry these — they are pure JS. So a
-// `boxShadow: '0 2px 4px #000'` resolved only inside `fabric-props.ts` is resolved only headless,
-// and the device gets the raw CSS string. Fabric's C++ parses a style string ONLY under
-// `enableNativeCSSParsing()`, which defaults to FALSE, so the declaration is dropped in silence:
-// no warning, no wrong value, just a gradient or a shadow that is not there. Resolving on the way
-// IN puts the structured value in `node.props` itself, which is the one thing both payload builders
-// read.
-//
-// This is the same move `configPayloadFold` makes for a third-party view's own processors, one
-// layer down: anything the C++ half cannot do has to happen before the C++ half sees the value.
-//
-// IDENTITY IS PART OF THE CONTRACT. A style object that needs nothing comes back BY IDENTITY, and
-// so does an array whose every entry did. The host's `OP_SET_PROP` skips a same-identity write, and
-// `pushClassStyle` compares what it is about to publish against what it published last — hand
-// either of them a fresh object per write and an unchanged style becomes a write and a dirty node
-// on every render.
+// They run at write time, not payload-build time: SymbioteFabricProps.cpp doesn't carry these
+// processors, so resolving only in fabric-props.ts leaves the device its raw CSS string, silently
+// dropped (C++ parses a style string only under enableNativeCSSParsing, default false).
+// Same move `configPayloadFold` makes for a third-party view's own processors: anything the C++
+// half can't do has to happen before the C++ half sees the value.
+// Identity is part of the contract: an object/array needing no resolution comes back by identity,
+// since OP_SET_PROP skips a same-identity write and pushClassStyle diffs by reference — a fresh
+// object per call would turn an unchanged style into a write and a dirty node every render.
 import { processAspectRatio } from './process-aspect-ratio.js';
 import { processBackgroundImage } from './process-background-image/index.js';
 import { processBackgroundPosition, processBackgroundRepeat, processBackgroundSize, } from './process-background-longhands.js';
@@ -80,10 +70,9 @@ function asFontVariantInput(value) {
         return value.filter(isString);
     return '';
 }
-// transform accepts a CSS string (processTransform parses it) or an array of single-key
-// transform records (the hot animated / sticky-header path). A non-string non-array value is NOT
-// dropped: it may already be processed, so it passes through verbatim rather than being coerced to
-// [] (which would erase a valid transform).
+// transform accepts a CSS string or an array of single-key records (the hot animated /
+// sticky-header path). A non-string non-array value passes through verbatim — it may already be
+// processed, so coercing it to [] would erase a valid transform.
 function processTransformValue(value) {
     if (typeof value === 'string')
         return processTransform(value);
@@ -154,15 +143,11 @@ function resolveRecord(style) {
     resolvedStyles.set(style, answer);
     return answer;
 }
-/**
- * A style value with its structured keys resolved — the same value by identity when there was
- * nothing to resolve, which is nearly always.
- *
- * Accepts what a style slot can hold: one object, or a (nested) array of them. An array is not
- * memoized — `pushClassStyle` mints a fresh one on every publish, so a cache keyed on it could
- * never hit; its ENTRIES carry the memo instead, and the original array comes back untouched when
- * none of them moved.
- */
+// A style value with its structured keys resolved — same value by identity when nothing needed
+// resolving, which is nearly always.
+// Accepts one object or a (nested) array of them. An array itself isn't memoized (pushClassStyle
+// mints a fresh one per publish, so a cache keyed on it would never hit); its entries carry the
+// memo instead.
 export function resolveStructuredStyle(style) {
     if (Array.isArray(style)) {
         let out;

package/build/styles.js

@@ -1,7 +1,4 @@
-// The typed style surface (ViewStyle / TextStyle and friends). Maps onto Yoga layout
-// props and RN's view/text props, which Fabric's C++ reads off the props payload.
-// A correctly-typed subset of RN's StyleSheet surface (see
-// react-native/Libraries/StyleSheet/StyleSheetTypes): the load-bearing layout / box /
-// shadow / transform / text props, not the full surface. Agnostic types, so they
-// live in the engine next to the style processors; every adapter re-exports them.
+// The typed style surface (ViewStyle/TextStyle and friends). Maps onto Yoga layout props and RN's
+// view/text props, which Fabric's C++ reads off the props payload. A correctly-typed subset of
+// RN's StyleSheet surface — agnostic types, so every adapter re-exports them from the engine.
 export {};

package/build/surface.d.ts

@@ -6,38 +6,12 @@ export declare class SymbioteSurface {
     private readonly node;
     private commitScheduled;
     constructor(rootTag: IRootTag);
-    /**
-     * Every OTHER live surface, so one commit names every root — see `commitSurfaceOps`.
-     *
-     * Static because it reads a sibling instance's private handle, which only a member of this class
-     * may do. One surface — the universal case — allocates nothing.
-     *
-     * `self` may already be OUT of the registry: a teardown unregisters and then commits, and that
-     * commit is the one carrying the removals. So the fast path cannot be a size check — with one
-     * live surface left, `size === 1` means either "only me" or "only the other one", and taking the
-     * shortcut on the second reading is how a surface loses the very batch that empties it.
-     */
     private static others;
-    /**
-     * The top-level nodes, asked of the host.
-     *
-     * A getter rather than an array this class maintains: a second copy of a child list is the thing
-     * this design removes, and `nextSiblingOf` (host-access.ts) needs the same answer the host gives
-     * for a parented node.
-     */
     get children(): readonly ISymbioteNode[];
     appendChild(child: ISymbioteNode): void;
     insertBefore(child: ISymbioteNode, beforeChild: ISymbioteNode): void;
     removeChild(child: ISymbioteNode): void;
     clear(): void;
-    /**
-     * Release every host behavior still standing under this surface, at unmount.
-     *
-     * The sweep above cannot answer this: it only sees nodes a `removeChild` NOMINATED, and an
-     * unmount removes nothing — the adapter drops the whole surface. Without it every node keeps its
-     * `afterCommit` registration and its timers, and a restarted surface's commits drain the dead
-     * one's hooks forever.
-     */
     teardown(): void;
     commit(): void;
     requestCommit(): void;