@fusion.dev/helix-core 0.2.0 → 0.3.0

package/dist/controllers/indicator-controller/indicator-controller.js

@@ -1,41 +1,3 @@
-/**
- * Measures the marked child and writes the geometry onto a traveling mark.
- *
- * Serves `Navigation`, `Tabs`, `Toggle.Group` and `Outline`. The two things
- * hand-written copies of this get wrong:
- *
- * **The inline axis is signed.** In a right-to-left document the distance is
- * measured from the surface's right edge and applied as a negative translation,
- * because the mark travels from the inline start and the inline start is on the
- * right. Measuring from the physical left and applying an unsigned offset from
- * the inline-start edge sends the mark the wrong way in RTL.
- *
- * **The border has to come off both axes.** `getBoundingClientRect` gives the
- * border box and the containing block is the padding box, so a surface with a
- * border of its own puts the mark one border-width out. `clientLeft` and
- * `clientTop` are the border widths, already resolved, which is why they are
- * used here rather than parsing `borderLeftWidth`.
- *
- * **Nothing is written until there is something to measure.** A zero-width box
- * is a component whose children have not upgraded yet, and writing zeroes would
- * park the mark at the origin and leave it there. The `data-placed` attribute is
- * what a stylesheet waits for, so a mark fades in where it belongs rather than
- * sliding from the corner on first paint.
- *
- * The four custom properties are the contract. What a component does with them
- * is its own business, which is how one controller serves a bar under a tab, a
- * pill filling it, and a rule down the side of a contents page.
- *
- * **Declared here because this is what writes them.** `core` ships no CSS, so
- * every reader is outside this package and none of these is private.
- * the `hooks` rule pairs a documented hook with a rule that reads one, in both
- * directions.
- *
- * @cssproperty --indicator-block-size - How tall the active item is, in pixels.
- * @cssproperty --indicator-inline-size - How wide the active item is, in pixels.
- * @cssproperty --indicator-x - Where the active item starts, along the inline axis.
- * @cssproperty --indicator-y - Where the active item starts, along the block axis.
- */
 export class IndicatorController {
     constructor(host, options) {
         this.host = host;
@@ -43,32 +5,17 @@ export class IndicatorController {
         host.addController(this);
     }
     hostConnected() {
-        /* The host's own size is not enough: a strip that keeps its width while its
-           children rewrap moves every one of them, and a mark measured against the
-           old layout is left behind. Observing the host catches both, because a
-           rewrap changes its height. */
         this.resize = new ResizeObserver(() => this.place());
         this.resize.observe(this.host);
     }
     hostDisconnected() {
         this.resize?.disconnect();
         this.resize = undefined;
-        /* The host going away is the third way a move can end, and the one nothing
-           was watching. A timer holding a closure over a detached element keeps it
-           alive for the second it has left to run. */
         this.stopWaiting();
     }
-    /** Called after every update, which is when the marked child may have moved. */
     hostUpdated() {
         this.place();
     }
-    /*
-     * Measures and writes, or gives up without writing anything.
-     *
-     * Public because `slotchange` is not an update: children arriving is exactly
-     * when the first measurement becomes possible, and a component that only
-     * placed on its own updates left the mark unplaced for the life of the page.
-     */
     place() {
         const indicator = this.options.indicator();
         const surface = this.options.surface();
@@ -77,8 +24,6 @@ export class IndicatorController {
             return;
         }
         if (!active) {
-            // Nothing is marked, so there is nothing to point at. The attribute goes
-            // and the stylesheet takes the mark away with it.
             indicator.removeAttribute('data-placed');
             return;
         }
@@ -87,32 +32,12 @@ export class IndicatorController {
         if (box.width === 0 && box.height === 0) {
             return;
         }
-        /* `clientLeft` and `clientTop` are the resolved border widths, which is the
-           difference between the border box the measurement gives and the padding
-           box the mark is placed against. */
         const rtl = getComputedStyle(surface).direction === 'rtl';
         const inline = rtl
             ? own.right - box.right - surface.clientLeft
             : box.left - own.left - surface.clientLeft;
         const x = `${rtl ? -inline : inline}px`;
         const y = `${box.top - own.top - surface.clientTop}px`;
-        /* `data-moving` while it is on its way, so a stylesheet can say something
-         * about the travel itself.
-         *
-         * There is no CSS state for "a transition is running", and the effect this
-         * exists for wants one: a mark that swells as it leaves and settles back
-         * when it lands reads as a thing being carried rather than a rectangle
-         * being repositioned. The controller is the only thing that knows a move
-         * has been asked for, so it says so.
-         *
-         * Only on a *change*, and never on the first placement: the mark arrives by
-         * fading in, and swelling on arrival would be an animation about nothing.
-         *
-         * Cleared on `transitionend` with a timeout behind it. The event is the
-         * honest signal and it does not always come: a move under reduced motion
-         * has no transition to end, and neither does one whose computed position
-         * turns out identical after a resize. A marker that can stick is worse than
-         * one that clears a little early. */
         const moved = this.last !== undefined && (this.last.x !== x || this.last.y !== y);
         this.last = { x, y };
         indicator.style.setProperty('--indicator-x', x);
@@ -125,12 +50,6 @@ export class IndicatorController {
         }
         indicator.toggleAttribute('data-moving', true);
         this.stopWaiting();
-        /* `translate` only. `transitionend` fires once per property, and a
-           stylesheet reacting to `data-moving` is very likely to transition
-           something shorter than the travel: the outline's mark widens over
-           `duration-fast` while it travels over `duration-normal`, so an unfiltered
-           listener had the width's own transition end the move that caused it, a
-           third of the way through. */
         const settle = (event) => {
             if (event && event.propertyName !== 'translate') {
                 return;
@@ -142,7 +61,6 @@ export class IndicatorController {
         this.waiting = { on: indicator, settle };
         this.settling = setTimeout(settle, 1000);
     }
-    /** Takes the pending listener and its guard off, wherever they came from. */
     stopWaiting() {
         clearTimeout(this.settling);
         this.settling = undefined;

package/dist/controllers/keyboard-navigation-controller/keyboard-navigation-controller.js

@@ -1,27 +1,4 @@
-/** Every key that moves within a set, which is the whole of what this handles. */
 const KEYS = new Set(['ArrowDown', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'End', 'Home']);
-/**
- * Moves through a set of items with the arrow keys, and chooses as it goes.
- *
- * **Moving and choosing are one act here, not two.** That is the radio group
- * pattern and it is the difference from a listbox: moving focus without
- * choosing leaves a keyboard reader sitting on an item they have not selected,
- * with nothing on screen saying which of the two is true. A pointer user
- * chooses by arriving, so a keyboard user does too.
- *
- * **Both axes, always.** A vertical set still answers left and right, and a
- * horizontal one still answers up and down. Binding only the axis the items
- * happen to be laid out on means a reader who guesses wrong gets nothing, and
- * `orientation` is presentation: the same set of choices reads the same way
- * whichever direction it runs.
- *
- * Disabled items are skipped rather than stopped at, so a set with a gap in it
- * still moves in one press.
- *
- * A set that starts from focus rather than from the selection, or that moves
- * without choosing, says so through `origin` and `selects`. Neither is a reason
- * to keep a hand-written copy, and neither exempts a set from both axes.
- */
 export class KeyboardNavigationController {
     constructor(host, { items, origin = 'selection', reserved = () => [], selects = () => true, wrap = true, }) {
         this.handleKeydown = (event) => {
@@ -32,18 +9,6 @@ export class KeyboardNavigationController {
             if (items.length === 0) {
                 return;
             }
-            /* `-1` means two different things and only one of them is a starting point.
-             *
-               Starting from the selection, `-1` is "nothing is chosen", and the
-               arithmetic below relies on it: a forward step lands on the first item and
-               a backward step on the last, both of which are where a reader entering an
-               unanswered set expects to arrive.
-        
-               Starting from focus, `-1` is "the press did not come from the set", and
-               there is nothing to move. The listener is on the host, not on the items,
-               and a host can hold more than the set: a tab panel is `tabindex="0"`, so
-               an arrow pressed while reading a panel used to move the tabs out from
-               under the reader. */
             const current = this.origin === 'focus'
                 ? items.findIndex((item) => item.contains(event.target))
                 : items.findIndex((item) => item.selected);
@@ -56,17 +21,6 @@ export class KeyboardNavigationController {
                 next = this.wrap ? (current + 1) % items.length : Math.min(current + 1, last);
             }
             else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') {
-                /* From nothing, backwards is the last, which the arithmetic did not give.
-                 *
-                 * `(-1 - 1 + length) % length` is `length - 2`: the *second* to last, so
-                 * a reader arrowing backwards into an unanswered group lands one short of
-                 * the end. The wrapping form is right for every real index and wrong for
-                 * the one that is not an index.
-                 *
-                 * And the clamp is `Math.max` against the forward branch's `Math.min`.
-                 * Unclamped this is `-1` on the first item, and `items[-1]` is undefined,
-                 * so nothing is focused and nothing chosen on a press that
-                 * `preventDefault` has already swallowed. */
                 next =
                     current < 0
                         ? last

package/dist/controllers/popover-controller/popover-controller.js

@@ -1,37 +1,7 @@
 import { DismissController } from '../dismiss-controller/dismiss-controller.js';
 import { FloatingController } from '../floating-controller/floating-controller.js';
-/**
- * A surface that floats against something, in the top layer, until dismissed.
- *
- * Bundles the three things that always travel together: the popover API, a
- * `FloatingController` and a `DismissController`.
- *
- * **The top layer is the whole point.** A floating panel has to escape every
- * clipping ancestor between it and the page, and `position: fixed` does not do
- * that: it is clipped by `overflow` on any ancestor and re-anchored entirely by
- * an ancestor carrying `transform`, `filter` or `contain`. The popover API
- * lifts the element out of the tree's paint order for real, and it is the only
- * thing that does.
- *
- * `manual` rather than `auto`, because the host owns dismissal. `auto`
- * popovers light-dismiss themselves and close each other, which is close to
- * what is wanted and not the same: a select that closed itself before its own
- * change event landed, or a submenu that closed its parent, are both things the
- * platform would do here and neither is right.
- *
- * **The order matters on the way up.** `showPopover` first, then position:
- * measuring an element that is still `display: none` gives zeroes, so a surface
- * positioned before it is shown lands at the origin and slides into place on
- * the next frame. On the way down it is the reverse, and stopping the observer
- * before hiding avoids a final measurement of an element on its way out.
- *
- * What this does not own is *when*. Opening is the host's, because a menu opens
- * on click, a tooltip on hover and a select on either, and none of that is
- * about surfaces.
- */
 export class PopoverController {
     constructor(host, options) {
-        /** Whether the surface is currently shown, so the calls can be idempotent. */
         this.shown = false;
         this.options = options;
         this.floating = new FloatingController(host, {
@@ -48,11 +18,9 @@ export class PopoverController {
         });
         host.addController(this);
     }
-    /** Whether the surface is showing. */
     get open() {
         return this.shown;
     }
-    /** Whether this one is placed by measurement, read fresh so it may change. */
     get places() {
         const asked = this.options.place;
         if (asked === undefined) {
@@ -60,29 +28,13 @@ export class PopoverController {
         }
         return typeof asked === 'function' ? asked() : asked;
     }
-    /**
-     * Shows the surface, positions it, and starts listening for a way out.
-     *
-     * Safe to call when already open, so a host may call it from whatever
-     * combination of a property, an event and a command it likes without keeping
-     * track of which one got there first.
-     */
     show() {
         const surface = this.options.surface();
         if (this.shown || !surface) {
             return;
         }
         this.shown = true;
-        /* Feature-detected rather than assumed. The popover API is recent enough
-           that a browser without it should still get a positioned panel, which is
-           what every one of these was before the API existed: worse, because it can
-           be clipped, and not broken. */
         if (typeof surface.showPopover === 'function') {
-            /* And said plainly where the surface is not one. `showPopover` on an
-               element with no `popover` attribute throws `NotSupportedError`, from
-               inside the promise the host called this in, so it surfaces as an
-               unhandled rejection naming a method rather than as the thing that is
-               actually wrong. */
             if (!surface.hasAttribute('popover')) {
                 throw new Error('PopoverController: the surface needs a `popover` attribute to reach the top layer');
             }
@@ -93,7 +45,6 @@ export class PopoverController {
         }
         this.dismisser.activate();
     }
-    /** Hides the surface and stops everything watching it. */
     hide() {
         const surface = this.options.surface();
         if (!this.shown) {
@@ -104,7 +55,6 @@ export class PopoverController {
         this.floating.stop();
         surface?.hidePopover?.();
     }
-    /** Whichever of the two the surface is not already doing. */
     toggle() {
         if (this.shown) {
             this.hide();
@@ -113,31 +63,9 @@ export class PopoverController {
             this.show();
         }
     }
-    /**
-     * Places the surface again, for an anchor that moved without the page moving.
-     *
-     * `autoUpdate` watches scrolling, resizing and layout shift, which covers
-     * everything that moves an anchor *with* its surroundings. It does not cover
-     * an absolutely positioned anchor being moved by an inline style, and that is
-     * exactly what a chart does: the mark walks from reading to reading while the
-     * page holds still, so the bubble was placed once and stayed there.
-     */
     reposition() {
         this.floating.update();
     }
-    /*
-     * Forgets that it was showing, and nothing more, which is the whole job.
-     *
-     * An element removed while its popover is showing is taken out of the top
-     * layer by the platform. The two controllers watching it stop themselves:
-     * both were constructed against this same host and registered with it, so Lit
-     * calls each one's own `hostDisconnected`, and `autoUpdate` in particular
-     * releases the listeners it holds on every scrolling ancestor there.
-     *
-     * Stopping them from here as well would be the same call twice. What is left
-     * is the flag, which nothing else owns, and which has to be cleared or a host
-     * reconnected to the page believes it is still open and refuses to show.
-     */
     hostDisconnected() {
         this.shown = false;
     }

package/dist/controllers/source-controller/source-controller.js

@@ -1,24 +1,4 @@
 import { readSeries } from '../../utils/read-series/read-series.js';
-/**
- * Resolves the element a chart reads from, and follows it.
- *
- * Every chart that takes a `for` wants exactly this, and wants it to behave
- * identically, so it is a controller rather than a paragraph in each of them.
- *
- * A controller and not a pure function, by the test the rules set: it reacts to
- * the host's lifecycle. It has to start watching when the host connects, stop
- * when it leaves, and re-resolve when `for` changes.
- *
- * **What it refuses is as much the point as what it accepts.** A `<table>` or
- * anything built from grid roles, including this library's own `helix-table`,
- * whose roles live in `ElementInternals` and therefore write no attribute at
- * all. Anything else resolves to null, so a `for` pointed at a paragraph draws
- * nothing rather than something arbitrary.
- *
- * The element is watched for `childList` and `characterData` alike, because
- * renaming a series edits a text node in place rather than replacing a cell,
- * and nothing in a page has reason to know a chart is reading it.
- */
 export class SourceController {
     #host;
     #observer;
@@ -26,13 +6,6 @@ export class SourceController {
         this.#host = host;
         host.addController(this);
     }
-    /**
-     * The element `for` names, or null where there is nothing to name it in.
-     *
-     * Null on the server as well, since resolving an id wants a document. Every
-     * chart inherits that: the table is served whole and the drawing arrives on
-     * hydration.
-     */
     get element() {
         const host = this.#host;
         if (host.for === '') {
@@ -43,10 +16,6 @@ export class SourceController {
         if (!found) {
             return null;
         }
-        /* `tagName` rather than `instanceof HTMLTableElement`, which is not a guard
-           on the server: the constructor is not defined there, so naming it throws
-           before the comparison can answer false. It is also the check that
-           survives an element from another document. */
         const role = found.getAttribute('role');
         return found.tagName === 'TABLE' ||
             role === 'table' ||
@@ -55,7 +24,6 @@ export class SourceController {
             ? found
             : null;
     }
-    /** The series it holds, or none. */
     get series() {
         const element = this.element;
         return element ? readSeries(element) : [];
@@ -67,12 +35,6 @@ export class SourceController {
         this.#observer?.disconnect();
         this.#observer = undefined;
     }
-    /**
-     * Points the watcher at whatever `for` names now.
-     *
-     * Called on connect and by the host when `for` changes. Safe to call when
-     * there is no `MutationObserver`, which is the server.
-     */
     watch() {
         this.#observer?.disconnect();
         const element = this.element;

package/dist/controllers/token-color-controller/token-color-controller.js

@@ -1,44 +1,7 @@
-/**
- * Reads a design token as the sRGB triple a shader or a 2D canvas can take, and
- * tells the host when the palette underneath it moves.
- *
- * **Two hops, and both are load-bearing.** A custom property's own value is the
- * unevaluated function text, so `getComputedStyle` on a probe is the only way
- * to see what it resolves to. And what it resolves to is not `rgb()`: the
- * palette derives from an `oklch()` seed, and Chrome answers `lab(100 0 0)` for
- * white. Parsing that with a regular expression for numbers reads the three
- * channels as 100, 0 and 0, which divided by 255 is a dark red.
- *
- * A screenshot cannot catch that: a warm cast on a saturated gradient is also
- * what chroma subsampling produces, so the picture agrees with the bug.
- *
- * The conversion is therefore the browser's own: fill a pixel and read it back.
- * That holds for `lab()`, `oklch()`, `color-mix()` and whatever a token is
- * written in next, which is the property worth having in a design system whose
- * palette is derived rather than listed.
- *
- * **A controller and not a mixin**, by this repository's own line: it adds no
- * property or method a consumer sets. It reacts to lifecycle, holding a probe
- * that has to be created after the host connects and removed when it leaves,
- * and it watches for the color mode changing so the host can repaint.
- *
- * **Client only, and that is the contract rather than a limitation.** There is
- * no computed style on a server and no canvas to convert with, so `read`
- * answers the fallback there. Every caller is drawing into a canvas, which does
- * not exist on a server either.
- */
 export class TokenColorController {
-    /**
-     * @param host The element to update when the palette changes.
-     * @param onChange Called when the mode moves, after the host has updated. A
-     *   host that paints outside Lit's cycle needs to know, because a canvas
-     *   holds its last frame and no re-render repaints it.
-     */
     constructor(host, onChange) {
         this.host = host;
         this.onChange = onChange;
-        /** Where a resolved color is converted, one pixel at a time. */
-        // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read in three places below, and this rule's own automatic fix removed it, which failed `typecheck` immediately. The suppression has to sit under the doc comment rather than over it, being directional.
         this.context = null;
         this.announce = () => {
             this.host.requestUpdate();
@@ -47,8 +10,6 @@ export class TokenColorController {
         host.addController(this);
     }
     hostConnected() {
-        /* Guarded on `document` rather than on `window`, which the server shim does
-           provide. There is nothing to append a probe to without one. */
         if (typeof document === 'undefined') {
             return;
         }
@@ -59,10 +20,6 @@ export class TokenColorController {
         swatch.width = 1;
         swatch.height = 1;
         this.context = swatch.getContext('2d', { willReadFrequently: true });
-        /* The color mode is an attribute, and the system's answer is a media query.
-           Watching only the first leaves a reader on system light with the dark
-           palette, which is the half that is easy to miss because a developer
-           toggling the site's own control never sees it. */
         this.modes = new MutationObserver(() => this.announce());
         this.modes.observe(document.documentElement, {
             attributeFilter: ['data-color-mode'],
@@ -80,20 +37,12 @@ export class TokenColorController {
         this.probe = undefined;
         this.context = null;
     }
-    /**
-     * The token's current value, or the fallback where it cannot be resolved.
-     *
-     * @param token The custom property's name, including its leading dashes.
-     * @param fallback What to answer on a server, or where the token is unset.
-     */
     read(token, fallback) {
         const { context, probe } = this;
         if (!context || !probe) {
             return [...fallback];
         }
         probe.style.color = `var(${token})`;
-        /* Reset first. An unparseable value leaves `fillStyle` where it was, which
-           would silently hand back the previous token's color. */
         context.fillStyle = '#000000';
         context.fillStyle = getComputedStyle(probe).color;
         context.fillRect(0, 0, 1, 1);

package/dist/controllers/virtualize-controller/virtualize-controller.js

@@ -1,97 +1,11 @@
-/**
- * How many times an update this asked for may change the answer again.
- *
- * **A measurement that its own render moves has no fixed point, so something
- * has to stop looking for one.** `clientHeight` is meant to be a fact about the
- * box, true of any real scroller, and false of a box with no height: there it
- * is a function of the rows just drawn, so `measure` renders, the render
- * changes the height, and the next measurement disagrees.
- *
- * It does not even diverge, which is what made it hard to see. Measured on the
- * headless tier with 500 rows and no height on the viewport, it converged
- * toward a non-integer and then oscillated between 378 and 379 rows forever,
- * 2505 passes in eight seconds. The loop runs on microtasks, so timers never
- * fire, and every deadline written to catch this, the harness's 2000ms race and
- * the spec's own bounded `settle`, is a `setTimeout` that cannot run. The page
- * simply stops.
- *
- * Ten, because a legitimate settling is two or three: nothing, then the real
- * height, then agreement.
- */
 const UNSTABLE = 10;
-/**
- * Works out which slice of a long set is worth rendering.
- *
- * **A controller and not an element, which is the whole reason it is here.**
- * Table, Listbox, Combobox and Tree each need windowing *inside* themselves,
- * and an element would make each of them nest one in its own shadow root: a
- * listbox whose options are inside a `<helix-virtual-list>` is a listbox whose
- * options are no longer its children, so its own keyboard, its own selection
- * and its own ARIA all have a stranger in the middle of them.
- *
- * **A windowed set still reports its true length, and each row its true
- * position.** This is the part virtualization usually gets wrong and the reason
- * the arithmetic lives somewhere shared. A reader on row 4,000 of 10,000 must
- * hear "4,000 of 10,000", so `aria-setsize` is the count and `aria-posinset` is
- * the real index, never the position within the rendered slice. The window is a
- * rendering decision and the set is a fact, and a component that lets the first
- * overwrite the second has told a screen reader the list is twelve long.
- *
- * **The spacers are what make the scrollbar honest.** Rendering twelve rows in
- * a box that should scroll for ten thousand gives a thumb the size of the
- * track, so the room the absent rows would have taken is left as padding before
- * and after. A reader dragging that thumb is dragging against the real length.
- *
- * **What it does not do, and the reason is narrower than it first looks.** True
- * virtualization means never creating the rows that are not on screen, and that
- * needs the set as *data*. Two channels are shut: a consumer's items arrive as
- * light-DOM children, which exist by the time this could decide not to create
- * them, and an `items` property cannot survive React hydration, which skips
- * every property it would have to apply imperatively (see `bindReactHandler`,
- * and the note in the rules that objects and functions have that bug and are
- * not fixed).
- *
- * **A third channel is open.** Data as *text*
- * in the markup, a `<script type="application/json">` child or an attribute, is
- * neither a property nor a node per row: React's hydration bug cannot touch text
- * it renders as a child, a server emits it, and the node count is one. The
- * charts already read data out of the document this way, `for="<id>"` at a real
- * `<table>`, so the pattern is in the library rather than being invented for
- * this.
- *
- * So the thing actually blocked is the *row template*. Turning an item into
- * markup wants either a render function, which is a function property and dies
- * on the same bug, or a `<template>` with named holes, which survives because it
- * is markup and which no component here asks anyone to write. That is a decision
- * about what this library is willing to look like, not a platform limit, and it
- * is open at #71.
- *
- * So what this buys is the expensive half rather than all of it: the rows
- * outside the window are not laid out and not painted, which is where the time
- * goes in a long list, and the node count stays. That is worth having and it is
- * not worth calling something it is not. An element that windows children it
- * was handed is not a virtual list, whatever it is named.
- *
- * **One estimate, not per-row measurement.** Measuring every row to place it is
- * how a virtual list ends up reading the layout it is trying to avoid, and it
- * is what makes them jump: a row taller than its estimate shifts everything
- * after it at the moment it renders. A fixed estimate is a straight line
- * between scroll offset and index, which never disagrees with itself. Rows of
- * genuinely different heights are a different component and a harder one.
- */
 export class VirtualizeController {
     constructor(host, options) {
         this.watching = false;
-        /** Consecutive measurements that moved the window with nothing outside asking. */
         this.settling = 0;
-        /** Whether the consumer has been told their box cannot be measured. */
         this.warned = false;
-        /** The slice to render, recomputed on scroll and on resize. */
         this.window = { after: 0, before: 0, first: 0, last: 0 };
-        /* `passive`, because this never calls `preventDefault` and saying so lets the
-           browser scroll without waiting to find out. */
         this.handleScroll = () => {
-            // A reader moved, which is the one input this exists to answer.
             this.settling = 0;
             this.measure();
         };
@@ -100,22 +14,6 @@ export class VirtualizeController {
         host.addController(this);
     }
     hostConnected() {
-        /* Nothing is observed here, and that is deliberate. `hostConnected` runs
-           before the first render, so the container query returns null and an
-           observer attached to nothing observes nothing for the life of the
-           element. It is an invisible failure: the first measurement is right, so
-           the only symptom is a window that never moves again. */
-        /* **The count is deliberately not cleared here**, which is the obvious
-           thing to do and does not work. A resize looks like an outside cause and
-           is not one when the box has no height of its own: the render this
-           controller asked for is what changed the size, so the observer fires on
-           every pass and resets the very counter meant to notice that. Measured:
-           the guard made no difference at all, 7776 passes in twenty-five seconds,
-           identical to having none.
-    
-           Nothing is lost by leaving it. A genuine resize changes the window once
-           and the next measurement agrees, which clears the count through `same`. A
-           runaway never agrees, which is the whole distinction. */
         this.observer = new ResizeObserver(() => {
             this.measure();
         });
@@ -126,7 +24,6 @@ export class VirtualizeController {
         this.watching = false;
         this.options.container()?.removeEventListener('scroll', this.handleScroll);
     }
-    /** Attaches to the box the first time there is one to attach to. */
     watch() {
         if (this.watching) {
             return;
@@ -139,13 +36,6 @@ export class VirtualizeController {
         box.addEventListener('scroll', this.handleScroll, { passive: true });
         this.watching = true;
     }
-    /**
-     * Reads the scroll offset and settles the window.
-     *
-     * Asks for an update only when the slice actually moved. A scroll fires many
-     * events per frame and most of them land inside the row already at the top,
-     * so requesting one per event would re-render the list for every pixel.
-     */
     measure() {
         this.watch();
         const box = this.options.container();
@@ -164,8 +54,6 @@ export class VirtualizeController {
             first,
             last,
         };
-        /* The host's own numbers changing is an outside cause, the same as a scroll
-           or a resize: a set that grew is not this controller chasing itself. */
         if (this.last?.count !== total || this.last.estimate !== size) {
             this.last = { count: total, estimate: size };
             this.settling = 0;
@@ -175,15 +63,10 @@ export class VirtualizeController {
             next.before === this.window.before &&
             next.after === this.window.after;
         if (same) {
-            // It settled, so nothing that came before it was a runaway either.
             this.settling = 0;
             return;
         }
         if (this.settling >= UNSTABLE) {
-            /* Hold what is *rendered*, which is `this.window`, rather than adopting a
-               reading nothing will draw. Refusing the update and keeping `next` would
-               leave the two disagreeing with no way back: the next measurement would
-               find them the same and do nothing. */
             this.report();
             return;
         }
@@ -191,17 +74,6 @@ export class VirtualizeController {
         this.window = next;
         this.host.requestUpdate();
     }
-    /**
-     * Says once that the box cannot be measured, and why.
-     *
-     * A warning rather than a throw, because the list still works: it holds a
-     * window, it draws rows, and a reader can scroll. What it cannot do is choose
-     * the window well, and that is the consumer's stylesheet to fix, not
-     * something this can decide on their behalf.
-     *
-     * Once per controller, because a warning per frame is one people filter out
-     * and this one has to be believed the day it is right.
-     */
     report() {
         if (this.warned) {
             return;