tests: tighten browser-setup.js comments

- Fix dated claim that window.ko comes from /lib/ko.js <script>;
  it's set by the bundled IIFE in /tests/source/setup.js.
- Drop "34 tests fail" specific count (historical, pre-polyfill).
- Collapse duplicate phrasings ("isHappyDom is never true here"
  was in both the header and the body).
- Shorten the punctuation-filter, sinon-restore, and ctx-arg
  shim comments to one concise paragraph each.

Author: Brian M Hunt

builds/knockout/helpers/browser-setup.js

@@ -1,59 +1,33 @@
 // Setup for running TKO specs in a real browser under Mocha.
-// Counterpart to vitest-setup.js — same concerns, different host.
+// Counterpart to vitest-setup.js. Loaded as the first import of
+// the test bundle (tko.io/scripts/bundle-tests.mjs).
 //
-// Loaded as the first import of the test bundle (see
-// tko.io/scripts/bundle-tests.mjs). When this module runs, it
-// assumes:
-//
-//   - mocha.setup('bdd') has already been called on the page,
-//     so `before` / `after` / `beforeEach` / `afterEach` are
-//     global Mocha hooks.
-//   - window.ko was set by loading /lib/ko.js via a <script>
-//     tag before the bundle.
-//
-// Responsibilities:
-//   - Expose `chai`, `expect`, `sinon` as the globals the specs
-//     and mocha-test-helpers.js expect.
-//   - `isHappyDom` is never true here (real browser).
-//   - Force `ko.options.jsxCleanBatchSize = 0` before the suite
-//     runs so the 25ms JSX cleanup timer does not race test
-//     teardown.
+// Assumes `mocha.setup('bdd')` already ran (so `before` / `after`
+// / `beforeEach` / `afterEach` are global) and `globalThis.ko`
+// was set by the bundled IIFE in /tests/source/setup.js, which
+// this module is imported from.
 
 import * as chai from 'chai'
 import sinon from 'sinon'
-// Register punctuation filters (`uppercase`, `lowercase`, `tail`, …)
-// on the shared `@tko/utils` options so `Parser` instances created
-// ad-hoc by specs (`new Parser().parse("x | tail")`) can resolve
-// them. The knockout builder ALSO registers these via
-// `builder.create({ filters })` at page startup, but it assigns to
-// a module-local `knockout.options` — not the same reference that
-// Parser reads from. Writing to the shared `options.filters` here
-// is safe: it's the same object the Builder later augments, and
-// earlier writes are idempotent for the punctuation set.
+// Register punctuation filters on shared `@tko/utils` options so
+// specs that construct Parsers directly (`new Parser().parse('x | tail')`)
+// can resolve them. The builder registers the same filters at page
+// startup but on a module-local options reference — not this one.
 import { filters as punctuationFilters } from '@tko/filter.punches'
 import { options as sharedOptions } from '@tko/utils'
 
 globalThis.chai = chai
 globalThis.expect = chai.expect
 globalThis.sinon = sinon
+globalThis.isHappyDom = () => false
 
 sharedOptions.filters = Object.assign(sharedOptions.filters || {}, punctuationFilters)
 
-// A real browser is never happy-dom — specs that skip under
-// happy-dom run here.
-globalThis.isHappyDom = () => false
-
-// Specs depend on helpers registered as globals by
-// mocha-test-helpers.js — `prepareTestNode`, `restoreAfter`,
-// `expectContainHtml`, etc. That module also overrides
-// `globalThis.after` to a cleanup-stack pusher (not a Mocha
-// suite hook) and wires root `beforeEach` / `afterEach` hooks
-// that flush the cleanup stack. Must be imported after Mocha's
-// `bdd` UI has been set up (the HTML page does
-// `mocha.setup('bdd')` before loading the bundle), otherwise
-// its `beforeEach(function () { … })` at module top throws.
+// mocha-test-helpers wires root beforeEach/afterEach hooks, so it
+// must be imported after `mocha.setup('bdd')` ran.
 import './mocha-test-helpers.js'
 
+// Disable the 25ms JSX cleanup timer so it can't race test teardown.
 before(() => {
   if (globalThis.ko?.options) {
     globalThis.ko.options.jsxCleanBatchSize = 0
@@ -62,42 +36,24 @@ before(() => {
 
 // Iframe focus-event polyfill.
 //
-// Each spec runs inside a hidden iframe spawned by
-// `tko.io/src/pages/tests.astro` via `tests-frame.html`. Chromium
-// refuses to grant programmatic `iframe.contentWindow.focus()`
-// true system focus from a parent that already has focus — the
-// iframe's window never passes `document.hasFocus() === true`, so
-// the browser suppresses `focusin` / `focusout` events when specs
-// call `element.focus()` / `element.blur()` inside. The
-// `hasfocus` binding observes those events (not
-// `document.activeElement`); 34 tests fail as a result, both
-// under Playwright and under a real Chrome tab.
+// Chromium refuses to grant programmatic `iframe.contentWindow.focus()`
+// true system focus from a parent that already holds focus — the
+// iframe never passes `document.hasFocus() === true`, so `focusin`
+// / `focusout` are suppressed when specs call `element.focus()`
+// inside. The `hasfocus` binding observes those events (not
+// `document.activeElement`), so without this patch those specs
+// fail under both Playwright and a real Chrome tab.
+//
+// Wrap `focus`/`blur` to dispatch the missing events synchronously
+// after the native call. If the browser DOES regain system focus
+// and fires them too, observers see duplicates — harmless for
+// these specs (state-checking, not call-count).
 //
-// Fix: wrap `HTMLElement.prototype.focus` and `.blur` to ALSO
-// dispatch the `focus` / `focusin` / `blur` / `focusout` events
-// synchronously after the native call. If the browser ALSO fires
-// them (whenever it does regain system focus), observers see
-// duplicates — harmless for the specs in this suite (they observe
-// state, not call count). Scope-guarded to the iframe context
-// (`window.parent !== window`) so the parent page is never
-// patched.
+// Scope-guarded to iframes (`window.parent !== window`) so the
+// parent page is never patched.
 //
-// References:
-//   - https://github.com/testing-library/user-event/issues/553
-//     `.focus()` does not fire focus events if the window is not
-//     focused. Confirmed across browsers; the same gate applies
-//     to unfocused iframes.
-//   - https://github.com/cypress-io/cypress/issues/8111
-//     iframe elements that focus are blurred immediately when
-//     they lack system focus.
-//   - https://github.com/jsdom/jsdom/pull/2996
-//     Reference implementation of synthetic focusin/focusout
-//     dispatch in jsdom; same shape as the wrap below.
-//   - https://html.spec.whatwg.org/multipage/interaction.html#focusing-elements
-//     The spec allows `.focus()` to succeed programmatically even
-//     when the owner isn't "being rendered"; event delivery,
-//     however, is gated on system focus of the top-level browsing
-//     context — that's the Chromium behaviour this patch bridges.
+// Refs: https://github.com/jsdom/jsdom/pull/2996 (same shape as
+// this wrap), https://html.spec.whatwg.org/multipage/interaction.html#focusing-elements.
 if (window.parent !== window && !HTMLElement.prototype.__tkoFocusPatched) {
   const HE = HTMLElement.prototype
   HE.__tkoFocusPatched = true
@@ -121,35 +77,22 @@ if (window.parent !== window && !HTMLElement.prototype.__tkoFocusPatched) {
   }
 }
 
-// Spies, stubs, and fake timers installed via the non-sandboxed
-// `sinon.spy(obj, 'method')` / `sinon.stub(...)` / `sinon.useFakeTimers()`
-// APIs remain wrapped on their targets until explicitly restored.
-// Specs that forget to restore (or whose `this.after(...)` cleanup
-// entry ran out of order) leak state into the next test, producing
-// `+0 to deeply equal N` on call-count assertions or
-// `Can't install fake timers twice` when the next spec re-installs.
-// `sinon.restore()` is a no-op for sandbox-scoped fakes, so scoped
-// specs are unaffected — only the pathological globals get reset.
-// This hook lives only in the browser runner; Vitest's
-// per-file module isolation shields it from the problem.
+// Unscoped sinon fakes (`sinon.spy(obj,'m')`, `sinon.useFakeTimers()`)
+// leak across specs if not restored, producing bogus call-count
+// diffs or "Can't install fake timers twice". `sinon.restore()` is
+// a no-op for sandbox-scoped fakes. Vitest isolates per-file so
+// doesn't need this hook.
 afterEach(() => {
   if (globalThis.sinon?.restore) globalThis.sinon.restore()
 })
 
 // Vitest-style context-arg shim.
 //
-// Some specs are written for Vitest and take the test context as a
-// single arg, e.g. `function (ctx: any) { if (isHappyDom()) return
-// ctx.skip('...') }`. Mocha inspects `fn.length` to decide whether
-// the test expects a `done` callback; a 1-arg function is treated as
-// async-with-done, and since these specs never call done(), Mocha
-// times them out (~10s each).
-//
-// Fix: wrap `it` so that 1-arg specs that look like ctx-style (use
-// `.skip(...)` and never call `done(...)`) are invoked with a fake
-// ctx `{ skip }` and the wrapper's arity is hidden from Mocha.
-// Genuine Mocha done-callback specs (identified by a `done(` call
-// in the source) pass through unchanged.
+// Specs written `function (ctx) { if (isHappyDom()) return ctx.skip(…) }`
+// look like Mocha done-callback specs (`fn.length === 1`) and time
+// out after ~10s because they never call done. Wrap `it` to detect
+// the ctx shape (uses `.skip(...)` and never calls `done(`) and
+// invoke with a synthetic `{ skip }` while hiding arity from Mocha.
 {
   const wrap = orig =>
     function (name, fn) {