A nested scroller reaches its bottom edge. The document behind it no longer moves. The browser test exits zero. That is a useful signal, but it is not yet the release decision.
The counterintuitive part of overscroll-behavior is that “scroll chaining stopped” and “the page-level gesture was suppressed” are related but different claims. The current CSS Overscroll Behavior Level 1 Editor’s Draft defines scroll chaining as propagation from one scroll container to an ancestor and separately defines boundary default actions, including local effects such as overscroll affordances and non-local effects such as scroll chaining or navigation actions. contain suppresses non-local boundary default actions while preserving local ones; none also suppresses local boundary default actions. auto leaves the usual boundary behavior to the user agent.
This playbook treats those distinctions as an operational release contract, not as a CSS tutorial. The disposable, version-pinned fixture tests nested scrolling, boundary arrival, auto/contain/none, physical axes, wheel input and a non-scrollable inner region offline. The manifest includes separate cases for synthetic touch in Chromium and native browser navigation gestures. No browser run was executed for this article. Every fixture outcome below is therefore EXPECTED / NOT EXECUTED.
Define the Exact Operational Acceptance Contract
Start with the product boundary, not the declaration.
For this playbook, the intended contract is: when input is targeted inside a nested scroll container, available inner scroll range is consumed by that inner container. When the inner container reaches the relevant boundary, the behavior that follows must match the declared overscroll-behavior value on that axis. The evidence must distinguish three states: inner scrolling, ancestor scroll chaining, and any page- or browser-level boundary gesture.
The specification gives the vocabulary. A scroll boundary is reached when the scroll position reaches the edge of the scrollport. A non-scrollable container is always considered at its boundary in the relevant direction. A scroll chain links a scroll container to the nearest ancestor scroll container that is scrollable on that axis, and the viewport participates through the document’s scrollingElement.
That means an acceptance record needs more than one integer. It needs the inner element’s scroll offset and maximum range, the document scroller’s offset, the computed overscroll-behavior-x and -y, the input class, the axis, and whether the relevant boundary was actually reached. MDN’s scrollTop documentation is useful as an oracle input, but it also warns that Safari can expose overscroll through values beyond the normal maximum whereas Chrome and Firefox generally do not. A cross-browser gate therefore cannot reduce all state to scrollTop === max.
When diagnosing a sticky header’s scroll container, identify the scroll owner and measure the header’s position within it. Here, identify the same owner and measure where the input goes when that container reaches its boundary.
The release vocabulary is strict:
Decision | Meaning in this fixture |
ACCEPT | Required rows were actually executed; runtime identity, fixture identity, boundary precondition and observed state all match the frozen manifest. |
REPAIR | Evidence identifies a specific contract mismatch with a narrow CSS or fixture correction. |
RERUN | The candidate may be valid, but evidence is incomplete, duplicated, contaminated or tied to the wrong runtime/fixture revision. |
HOLD | Required browser/gesture coverage is absent, source identity is unresolved, or observations cannot support the intended claim. |
No fixture case has been executed, so no runtime row qualifies for ACCEPT. Every case remains EXPECTED / NOT EXECUTED.
Document the Runtime and Version Boundary
A release gate is only meaningful if the runtime is identifiable.
Pin the harness to Node.js 24.11.1 and Playwright 1.65.1. On November 21, 2026, npm listed 1.65.1 as the stable release and identified support for Chromium, Firefox and WebKit. Record the installed browser build with browser.version() at runtime.
The June 30, 2026 CSS Overscroll Behavior Level 1 Editor’s Draft, retrieved in November 2026, defines auto, contain, none and the newer chain value. The fixture tests the three established values: auto, contain and none.
MDN currently describes overscroll-behavior as controlling what happens when scrolling reaches the edge of a scroll container and documents the common dialog/background example: contain blocks background chaining while preserving local overscroll effects, whereas none additionally suppresses those local effects. MDN also cautions that not every part of the latest syntax is necessarily implemented by every browser.
Pin and Record the Environment
Use a clean directory:
mkdir overscroll-boundary-lab
cd overscroll-boundary-lab
npm init -y
npm install --save-exact [email protected]
npx playwright install chromium
node --version
npm ls playwright --depth=0The measurable environment test is not “installation succeeded.” The fixture must emit:
fixtureRevision
fixtureSha256
nodeVersion
playwrightVersion
browserName
browserVersion
platform
arch
viewport
deviceScaleFactor
hasTouch
timestampThe independently authored expectation is that playwrightVersion equals 1.65.1, the fixture hash matches the reviewed source, and the observed browser version is recorded rather than guessed. The rejection criterion is any missing identity field, package drift, browser-launch failure, hash mismatch or result row whose recorded runtime differs from the row being reviewed.
Playwright documents mouse.wheel() as dispatching a wheel event and explicitly says it does not wait for resulting scrolling to finish. The harness therefore waits for rendering opportunities and measures resulting state rather than interpreting the API call’s resolved promise as evidence that scrolling completed.
Create a Disposable Controlled Fixture
The fixture removes application frameworks, network requests, production data, animation, scroll snapping and third-party styles. That isolation matters because the experiment is about ownership of boundary behavior, not about whether a real application happens to arrive at the same visual state through several mechanisms.
A fixed overlay inside a transformed parent illustrates why ownership matters. Its position depends on which element establishes the containing block. In this fixture, the relevant question is which element owns the scroll boundary.
Create overscroll-fixture.cjs:
const { chromium } = require("playwright");
const crypto = require("node:crypto");
const fs = require("node:fs");
const os = require("node:os");
const pkg = require("playwright/package.json");
const REVISION = "overscroll-boundary-r1-2026-11-21";
const source = fs.readFileSync(__filename);
const sha256 = crypto.createHash("sha256").update(source).digest("hex");
const cases = [
{ id: "V_RANGE_AUTO", axis: "y", behavior: "auto", mode: "range" },
{ id: "V_BOUNDARY_AUTO", axis: "y", behavior: "auto", mode: "boundary" },
{ id: "V_BOUNDARY_CONTAIN", axis: "y", behavior: "contain", mode: "boundary" },
{ id: "V_BOUNDARY_NONE", axis: "y", behavior: "none", mode: "boundary" },
{ id: "H_BOUNDARY_AUTO", axis: "x", behavior: "auto", mode: "boundary" },
{ id: "H_BOUNDARY_CONTAIN", axis: "x", behavior: "contain", mode: "boundary" },
{ id: "H_BOUNDARY_NONE", axis: "x", behavior: "none", mode: "boundary" },
{ id: "NONSCROLL_AUTO", axis: "y", behavior: "auto", mode: "nonscroll" },
{ id: "NONSCROLL_CONTAIN", axis: "y", behavior: "contain", mode: "nonscroll" },
{ id: "WHEEL_EVENT_ONLY", axis: "y", behavior: "contain", mode: "eventOnly" },
];
function html(c) {
const axisCss = c.axis === "x"
? "width:280px;height:180px;overflow-x:auto;overflow-y:hidden"
: "width:280px;height:180px;overflow-y:auto;overflow-x:hidden";
const payload = c.mode === "nonscroll"
? "width:120px;height:120px"
: c.axis === "x"
? "width:900px;height:120px"
: "width:120px;height:900px";
return <!doctype html>
<meta charset="utf-8">
<style>
html,body{margin:0}
body{min-height:2400px;min-width:1800px}
#outerPad{height:500px;width:500px}
#inner{
${axisCss};
overscroll-behavior-${c.axis}:${c.behavior};
border:1px solid;
}
#payload{${payload}}
</style>
<div id="outerPad"></div>
<div id="inner"><div id="payload"></div></div>
<div style="height:1600px;width:1600px"></div>;
}
async function settle(page) {
await page.evaluate(() => new Promise(resolve =>
requestAnimationFrame(() => requestAnimationFrame(resolve))
));
}
async function snapshot(page, id, phase) {
return page.evaluate(({ id, phase }) => {
const inner = document.querySelector("#inner");
const root = document.scrollingElement;
const cs = getComputedStyle(inner);
return {
id, phase,
innerTop: inner.scrollTop,
innerLeft: inner.scrollLeft,
innerMaxY: inner.scrollHeight - inner.clientHeight,
innerMaxX: inner.scrollWidth - inner.clientWidth,
documentTop: root.scrollTop,
documentLeft: root.scrollLeft,
documentMaxY: root.scrollHeight - root.clientHeight,
documentMaxX: root.scrollWidth - root.clientWidth,
obx: cs.overscrollBehaviorX,
oby: cs.overscrollBehaviorY,
scrollingElement: root.tagName,
innerScrollableY: inner.scrollHeight > inner.clientHeight,
innerScrollableX: inner.scrollWidth > inner.clientWidth,
};
}, { id, phase });
}
async function run() {
const browser = await chromium.launch({ headless: true });
const context = await browser.newContext({
viewport: { width: 900, height: 600 },
deviceScaleFactor: 1,
hasTouch: true,
});
const page = await context.newPage();
const result = {
identity: {
fixtureRevision: REVISION,
fixtureSha256: sha256,
nodeVersion: process.version,
playwrightVersion: pkg.version,
browserName: "chromium",
browserVersion: browser.version(),
platform: os.platform(),
arch: os.arch(),
viewport: { width: 900, height: 600 },
deviceScaleFactor: 1,
hasTouch: true,
timestamp: new Date().toISOString(),
},
rows: []
};
for (const c of cases) {
await page.setContent(html(c));
await page.evaluate(() => {
document.scrollingElement.scrollTo(120, 200);
});
await settle(page);
const inner = page.locator("#inner");
if (c.mode === "boundary") {
await inner.evaluate((el, axis) => {
if (axis === "y") el.scrollTop = el.scrollHeight;
else el.scrollLeft = el.scrollWidth;
}, c.axis);
} else if (c.mode === "range") {
await inner.evaluate(el => el.scrollTop = 80);
}
await settle(page);
const before = await snapshot(page, c.id, "before-input");
const box = await inner.boundingBox();
if (!box) throw new Errormissing box ${c.id});
await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
if (c.mode === "eventOnly") {
await inner.dispatchEvent("wheel", {
deltaY: 300, bubbles: true, cancelable: true
});
} else {
await page.mouse.wheel(
c.axis === "x" ? 300 : 0,
c.axis === "y" ? 300 : 0
);
}
await settle(page);
const after = await snapshot(page, c.id, "after-input");
result.rows.push({ case: c, before, after });
}
console.log(JSON.stringify(result, null, 2));
await browser.close();
}
run().catch(err => {
console.error(err);
process.exitCode = 1;
});Run it only in the disposable directory:
node overscroll-fixture.cjs \
> evidence.json \
2> evidence.stderr
printf 'exit=%s\n' "$?" | tee evidence.exit
sha256sum overscroll-fixture.cjs evidence.json evidence.stderr evidence.exitAfter preserving the evidence and completing the comparisons, remove the disposable directory:
cd ..
rm -rf overscroll-boundary-labNo production browser profile, origin, credentials or application build is required.
Author an Independent Expected-Case Manifest
Freeze the oracle before execution. Do not derive expected values from the observed browser state after the run.
The CSSWG draft says contain prevents non-local boundary default actions, including scroll chaining and navigation; none has the same non-local suppression and additionally disables local boundary default actions such as overscroll affordances. auto permits the user agent’s usual boundary behavior. The specification also says a non-scrollable element is always at its scroll boundary, while a single-axis scroller participates only in its scrollable axis.
Those rules support the following manifest, but they do not establish how a particular browser exposes visual affordances or whether an automation layer can reproduce an operating-system navigation gesture. That distinction is why several rows deliberately stop short of a universal observation.
Case | Independent expectation | Status |
Nested vertical scroller with available range | Wheel input targeted in the inner container changes inner scrollTop; document offset remains stable while range remains. | EXPECTED / NOT EXECUTED |
Inner reaches vertical boundary, auto | Inner remains at its maximum; ancestor chaining is permitted, so document scrolling may occur in an implementation that chains this input. | EXPECTED / NOT EXECUTED |
Boundary, contain | Inner stays at boundary; ancestor scroll chaining must be suppressed for that axis; local overscroll affordance is not suppressed by this value. | EXPECTED / NOT EXECUTED |
Boundary, none | Inner stays at boundary; ancestor scroll chaining and local boundary affordances are suppressed by the CSS contract. | EXPECTED / NOT EXECUTED |
Horizontal auto/contain/none | Same value distinctions apply independently to the x axis. | EXPECTED / NOT EXECUTED |
Non-scrollable inner, auto | Element is already at boundary; usual boundary behavior remains permitted. | EXPECTED / NOT EXECUTED |
Non-scrollable inner, contain | The property is meaningful only if the element is a scroll container; confirm computed/layout status before using this row as proof. | EXPECTED / NOT EXECUTED |
Synthetic wheel event dispatched with dispatchEvent() | JavaScript event delivery alone is not accepted as proof of default scrolling. | EXPECTED / NOT EXECUTED |
Playwright mouse.wheel() | May cause browser scrolling; state must be measured after input. | EXPECTED / NOT EXECUTED |
Synthetic Chromium touch sequence | May exercise touch scrolling in one emulated environment; must not be generalized to native browser navigation gestures. | EXPECTED / NOT EXECUTED |
Browser-specific back/forward or pull-to-refresh gesture boundary | Requires an environment capable of the real browser/OS gesture; this harness does not prove it. | EXPECTED / NOT EXECUTED |
Preserve a Failing Case Before Repair
The canonical failure row is V_BOUNDARY_AUTO. Its independently expected purpose is to show the contrast: an inner scroller is already at maximum scrollTop, a downward user-like wheel input is sent over it, and auto does not suppress ancestor boundary behavior.
The measurable precondition is:
before.innerTop == before.innerMaxY
before.oby == "auto"
before.documentTop > 0The expected comparison signal is that after.documentTop may increase if this Chromium configuration performs scroll chaining for the supplied wheel input. The row is rejected as evidence if the inner boundary was never reached, the pointer was not over the inner element, the document had no remaining vertical range, or the computed property did not equal auto.
Do not “repair” that row. It is supposed to preserve the contrasting behavior. If a test suite silently changes it to contain because chaining looks like a failure, the suite destroys its own positive comparison.
Reproduce the Misleading Success Signal
A green process exit can coexist with a useless experiment.
The easiest false positive is a synthetic DOM wheel event. dispatchEvent("wheel") can invoke event listeners, bubble through the DOM and produce perfectly respectable logging, yet that does not establish that the browser performed its trusted default scrolling behavior. The fixture therefore includes WHEEL_EVENT_ONLY as an intentionally invalid substitute for the user-like input path.
Playwright’s documented mouse.wheel() method is different: it dispatches wheel input through the automation interface and is commonly used to scroll, but its documentation still says scrolling is conditional and that the method does not wait for scrolling to finish. The measured offsets remain the oracle.
Another misleading green is programmatic boundary setup. The specification explicitly notes that programmatic scrolling is clamped and cannot itself trigger boundary default actions. Setting inner.scrollTop = inner.scrollHeight is therefore valid for arranging the precondition, but the assignment cannot be counted as evidence that scroll chaining or a navigation action occurred.
A third false positive is checking only that the outer document did not move. With contain, that is relevant evidence for suppressed scroll chaining. It is not proof that every page or browser gesture was suppressed. The CSSWG model distinguishes local and non-local boundary default actions, and it specifically names navigation actions as non-local. Whether a browser exposes a particular navigation gesture, whether automation can synthesize it faithfully, and whether an OS-level gesture participates in the same path remain environment questions.
The admission rule is therefore: zero exit status confirms that the harness process completed. It does not confirm the CSS contract. Only row-level state reconciled against the independent manifest can do that.
Run a Correctness Comparison
A useful comparison changes one causal declaration while holding geometry, input, axis and measurement constant.
The positive comparison is V_BOUNDARY_CONTAIN: same DOM, same 280×180 inner scroller, same oversized payload, same document range, same pre-boundary document offset, same pointer position and same downward wheel delta. The intended difference is only:
overscroll-behavior-y: contain;
Against V_BOUNDARY_AUTO, the expected discriminator is the ancestor document offset. If the auto row chains and the contain row does not, the comparison supports the claimed causal relationship. Both remain EXPECTED / NOT EXECUTED until run.
The second comparison is V_BOUNDARY_NONE. For ancestor scroll chaining alone, contain and none are expected to agree: both suppress non-local boundary default actions. The distinction belongs to local boundary actions such as an overscroll affordance, which a headless numeric ledger may not expose. The harness must not fabricate a “none is stronger” numeric result when its sensors do not observe that local effect.
The same measurement can answer different questions. When testing how content-visibility and intrinsic size affect layout, the relevant evidence is how much space skipped content reserves and where downstream elements land. Viewport scrolling is a diagnostic in that test. Here, ancestor movement after boundary input is the outcome under comparison.
Reject an Invalid Negative Control
A valid negative control must be able to falsify the explanation.
Changing a border color is not a negative control. Neither is dispatching a synthetic JavaScript wheel event and expecting the browser to treat it like a trusted physical input. Those changes do not isolate overscroll-behavior.
Use V_RANGE_AUTO instead. Position the inner scroller at scrollTop = 80, ensure there is substantial remaining range, then issue the same downward wheel input. The independent expectation is that the inner element consumes movement and the document remains stable because the boundary precondition has not been reached.
Reject the control if any of these conditions holds:
before.innerTop >= before.innerMaxY
after.innerTop == before.innerTop
after.documentTop != before.documentTopDetermine why the inner range was not consumed or why the document moved before interpreting the boundary rows. Possible causes include a pointer-targeting failure, a geometry setup error, input emulation differences or an unexpected browser state. Do not let a broken control become proof for the main hypothesis.
Test Negative and Boundary Conditions
Boundary testing must cover axis, range and scroll-container status separately.
For the vertical rows, overscroll-behavior-y is the controlled property. For horizontal rows, use overscroll-behavior-x and verify scrollWidth > clientWidth. The specification says the two axes are considered independently when scrolling occurs in both dimensions. A one-axis success must not be promoted to a two-axis guarantee.
The non-scrollable row deserves particular care. The CSSWG draft says an element without potential to scroll because it does not overflow in the relevant direction is always considered to be at the scroll boundary. MDN similarly describes a container with no scrollable overflow as being at its boundary. But the property’s applicability is defined in terms of scroll containers, so the ledger needs to record actual scrollHeight, clientHeight, overflow styles and computed overscroll values rather than assuming a visually bounded box participates exactly like the overflowing fixture.
Touch is a separate evidence class. Playwright’s Touchscreen API is limited to tap gestures; its documentation points to manually dispatched touch events for other gesture emulation. Consequently, a swipe built from lower-level Chromium DevTools Protocol events would be a Chromium-specific synthetic comparison, not a portable Playwright cross-browser proof.
The browser-navigation-gesture row is still more constrained. The spec’s contain definition names navigation among non-local boundary default actions. That is a standards-level requirement for conforming implementations, not evidence that a headless Linux Chromium wheel simulation exercised a macOS trackpad back-swipe, iOS rubber-band navigation, Android pull-to-refresh path or any other platform gesture.
For that row the only honest status here is EXPECTED / NOT EXECUTED. A release that depends on a native page gesture must test the supported device/browser combination capable of producing that gesture and preserve a separate ledger row.
Capture Raw Evidence and Exit Status
Evidence must survive the test process.
Preserve evidence.json, evidence.stderr, evidence.exit, the exact fixture file, package lockfile and hashes. The JSON row should carry both before and after; do not reduce it to pass: true. A future reviewer needs enough state to determine whether the boundary existed and which scroller moved.
A useful normalized ledger is:
Case | Input | Expected state | Actual state | Identity valid? | Evidence status | Decision |
V_RANGE_AUTO | wheel y | inner moves; document stable | Not observed | Not observed | EXPECTED / NOT EXECUTED | HOLD |
V_BOUNDARY_AUTO | wheel y | chaining permitted | Not observed | Not observed | EXPECTED / NOT EXECUTED | HOLD |
V_BOUNDARY_CONTAIN | wheel y | document stable at boundary | Not observed | Not observed | EXPECTED / NOT EXECUTED | HOLD |
V_BOUNDARY_NONE | wheel y | document stable; local affordance distinction separate | Not observed | Not observed | EXPECTED / NOT EXECUTED | HOLD |
H_BOUNDARY_AUTO | wheel x | chaining permitted | Not observed | Not observed | EXPECTED / NOT EXECUTED | HOLD |
H_BOUNDARY_CONTAIN | wheel x | ancestor x-chain suppressed | Not observed | Not observed | EXPECTED / NOT EXECUTED | HOLD |
H_BOUNDARY_NONE | wheel x | ancestor x-chain suppressed | Not observed | Not observed | EXPECTED / NOT EXECUTED | HOLD |
NONSCROLL_AUTO | wheel y | usual boundary path permitted | Not observed | Not observed | EXPECTED / NOT EXECUTED | HOLD |
NONSCROLL_CONTAIN | wheel y | applicability/state must be verified | Not observed | Not observed | EXPECTED / NOT EXECUTED | HOLD |
WHEEL_EVENT_ONLY | DOM event | must not qualify as scrolling proof | Not observed | Not observed | EXPECTED / NOT EXECUTED | HOLD |
TOUCH_BOUNDARY_CONTAIN | synthetic touch | Chromium-specific comparison only | Not observed | Not observed | EXPECTED / NOT EXECUTED | HOLD |
NAV_GESTURE_CONTAIN | native gesture | no non-local navigation at boundary if implementation supports gesture | Not observed | Not observed | EXPECTED / NOT EXECUTED | HOLD |
The current MDN definition of document.scrollingElement makes the root element the standards-mode document scroller. Record the actual tag anyway; do not hard-code documentElement into the evidence narrative when the API can identify it directly.
Detect Missing Evidence and Duplicates
A run is invalid if expected case IDs are missing or duplicated.
Save the following post-run verifier as verify-ledger.cjs:
const fs = require("node:fs");
const doc = JSON.parse(fs.readFileSync("evidence.json", "utf8"));
const expected = [
"V_RANGE_AUTO",
"V_BOUNDARY_AUTO",
"V_BOUNDARY_CONTAIN",
"V_BOUNDARY_NONE",
"H_BOUNDARY_AUTO",
"H_BOUNDARY_CONTAIN",
"H_BOUNDARY_NONE",
"NONSCROLL_AUTO",
"NONSCROLL_CONTAIN",
"WHEEL_EVENT_ONLY"
];
const ids = doc.rows.map(r => r.case.id);
const duplicates = ids.filter((id, i) => ids.indexOf(id) !== i);
const missing = expected.filter(id => !ids.includes(id));
if (duplicates.length || missing.length) {
console.error({ duplicates, missing });
process.exit(2);
}
console.log("ledger-membership-valid");Run:
node verify-ledger.cjs
printf 'verify_exit=%s\n' "$?"The independent expectation is exactly one row per declared automatic case. The rejection criterion is any missing case, duplicate case, unknown case, or verification exit other than zero.
Even a zero verifier exit does not prove the browser behavior. It proves only ledger membership.
Reconcile Observed State Against Source Identity
The evidence gate should now compare four independent dimensions: source identity, runtime identity, boundary precondition and observed transition.
Source identity means the reviewed fixture hash equals the executed fixture hash. Runtime identity means Node, Playwright and browser version are all recorded. Boundary precondition means the inner container was genuinely at the edge for the boundary rows and genuinely away from it for the range control. The observed transition records whether the intended scroller moved after the input.
The same distinction matters when validating PostgreSQL ON CONFLICT DO NOTHING RETURNING under concurrency. A successful command alone cannot establish which ID was returned. The database test needs the transaction schedule and returned state, just as the scroll test needs the boundary precondition and measured offsets.
A reconciliation predicate for V_BOUNDARY_CONTAIN can be written as:
fixture hash matches reviewed revision
AND playwrightVersion == "1.65.1"
AND browserVersion is present
AND before.oby == "contain"
AND before.innerTop == before.innerMaxY
AND before.documentTop < before.documentMaxY
AND after.innerTop remains at boundary
AND after.documentTop == before.documentTopThat predicate is stronger than “the page did not move.” If the document was already at its own bottom boundary, it could not move regardless of overscroll-behavior; the row would be invalid. If the inner scroller had no range, the tested topology would differ. If the fixture hash changed, the output would belong to another source revision.
For V_RANGE_AUTO, acceptance is different:
before.innerTop < before.innerMaxY
AND after.innerTop > before.innerTop
AND after.documentTop == before.documentTopThe oracle is case-specific. One universal “outer did not move” assertion would erase the distinction between available inner range and boundary suppression.
Separate Official Guarantees From Local Observations
The standards text and an executed fixture answer different questions.
The CSSWG draft says contain must prevent non-local boundary default actions such as scroll chaining or navigation and says none adds suppression of local boundary default actions. It also says the specification does not require user agents to implement scroll chaining or overscroll affordances in the first place. If an implementation has no such boundary action, the corresponding values may have no visible side effect.
That is the documented semantic layer.
The local-observation layer would be narrower: “Chromium build X, under Playwright 1.65.1 on platform Y, moved the document by N CSS pixels for auto but not for contain after this wheel sequence.” No such observation exists in this article because no run was performed.
MDN adds an important engine-specific caution for state oracles: Safari can report scrollTop beyond the normal maximum during rubber-band overscroll unless that behavior is disabled, while Chrome and Firefox generally clamp. Therefore a future WebKit row may need a boundary predicate that tolerates transient overscroll rather than reusing an exact Chromium equality test.
There is also a documentation nuance worth preserving. The current MDN overscroll-behavior page describes the common practical distinction among auto, contain and none, while the current CSSWG draft also exposes chain. This playbook does not infer that every shipping browser implements the newest grammar merely because the Editor’s Draft contains it.
Bound the Scope of the Fix
The repair boundary is one declaration on one scroll container and one axis.
If the vertical nested scroller should stop ancestor chaining while retaining local overscroll feedback, the candidate is:
.inner {
overscroll-behavior-y: contain;
}If the product also requires suppression of local overscroll affordances on that container, the candidate becomes:
.inner {
overscroll-behavior-y: none;
}Do not promote that second declaration merely because it sounds “safer.” It changes the contract.
The measurable repair test is the same precondition and input as the preserved auto row, with only the target property changed. The independent expectation is document-offset stability at the inner boundary. The rejection criterion is any additional CSS, DOM or scroll-range change that makes the comparison non-causal.
Implement a Narrow Repair or Safer Workflow
A narrow repair changes only the boundary behavior required by the product.
Suppose the evidence eventually shows V_BOUNDARY_AUTO chains into the document and the product requirement is “keep wheel/touch scrolling inside this panel when it reaches its edge, but preserve any local overscroll affordance.” The narrow candidate is overscroll-behavior-y: contain.
Do not add overflow: hidden, touch-action, event-level preventDefault(), body locking or global root styles to this experiment. Those mechanisms answer different questions and would destroy the ability to attribute the result to overscroll-behavior.
The safest workflow is:
Preserve the original auto evidence and fixture hash.
Change only the target axis/value.
Assign a new fixture revision or candidate identifier.
Rerun the same range control, boundary row and negative control.
Compare raw before/after scroll offsets.
Run the horizontal axis separately if horizontal behavior is a requirement.
Execute touch/native-gesture rows only in environments capable of producing the intended input class.
Promote the candidate only when every required row has evidence.
Do not treat none as an automatic upgrade from contain. The CSSWG definitions explicitly differ on local boundary actions. A team that wants bounce feedback inside a native-feeling panel may prefer contain; a team that wants that effect suppressed may require none.
Likewise, do not apply the property to a random ancestor and accept success. The specification defines behavior for scroll container elements, and the test contract names the nested inner scroller as the owner. Evidence must show the property is computed on the element whose boundary is being exercised.
Test Recovery, Rollback and Rerun Safety
Recovery is intentionally bounded to fixture and CSS state.
Rollback means restore the previous declaration, reset scroll positions, reload the isolated document and rerun the preserved comparison. It does not mean “production rollback is guaranteed safe.” This laboratory has no production traffic, application state, framework lifecycle, browser extension, user data or service dependency.
A deterministic reset can be added before each row:
await page.evaluate(() => {
const root = document.scrollingElement;
const inner = document.querySelector("#inner");
root.scrollTo(120, 200);
inner.scrollTop = 0;
inner.scrollLeft = 0;
});
await settle(page);Then set only the row-specific inner precondition.
Rerun safety requires immutable artifacts. Do not overwrite evidence.json from an earlier candidate. Use candidate-specific directories:
mkdir -p artifacts/baseline-auto
node overscroll-fixture.cjs \
> artifacts/baseline-auto/evidence.json \
2> artifacts/baseline-auto/stderr.txt
cp evidence.exit artifacts/baseline-auto/
sha256sum overscroll-fixture.cjs package-lock.json \
> artifacts/baseline-auto/hashes.txtA similar approach applies when testing how Python’s create_task captures request context. A pinned fixture and an expected-case manifest distinguish predictions from observations. Preserve the source revision so that a reviewer can tell whether two runs exercised the same code.
Recovery succeeds only if the baseline comparison can be reproduced under the same recorded environment after the repair candidate is removed. If baseline behavior cannot be recreated, classify the result RERUN or HOLD rather than declaring the repair causal.
Assign Ownership and Escalation
Assign three owners.
The component owner defines whether the product needs contain or none, which axes matter, and whether a browser-level navigation gesture is in scope. The test owner maintains the pinned fixture and ledger. The release owner decides whether the required browser/device matrix has enough evidence.
The measurable ownership check is that each required manifest row has a named environment and disposition before release. The independent expectation is that no required row remains ambiguous. The rejection criterion is a release decision that depends on an unowned “somebody should test mobile later” row.
Escalate to HOLD when native gesture behavior is required but only wheel evidence exists, when a browser-specific row lacks the actual browser/device, or when scroll state differs across reruns without a source/runtime explanation.
Decide ACCEPT, REPAIR, RERUN or HOLD
The final decision is mechanical.
Evidence condition | Decision |
All required rows executed; fixture/runtime identity valid; controls discriminate; boundary preconditions proven; observations match manifest | ACCEPT |
Required row executed and shows a reproducible mismatch attributable to the target overscroll-behavior value or placement | REPAIR |
Runtime correct but row missing, duplicated, pointer/input targeting uncertain, document at wrong boundary, or fixture artifact incomplete | RERUN |
Required native/browser gesture not executed; browser/version unknown; exact source revision unknown; conflicting evidence unresolved | HOLD |
The decision for this fixture is HOLD. No experiment has been executed, and every case in the manifest remains EXPECTED / NOT EXECUTED.
If evidence shows that contain stopped the ancestor document from scrolling when the nested scroller was at its boundary, you have validated stopped scroll chaining for that tested input, axis and runtime. You have not automatically validated every page-level gesture.
The CSS standard does place navigation gestures in the category of non-local boundary default actions that contain suppresses, so the standards contract is broader than scroll chaining alone. But an operational claim that a specific browser navigation gesture was stopped still requires evidence from an environment that can exercise that gesture.
Likewise, none is not merely “stronger chaining prevention.” For chaining, it shares the contain behavior; its extra contract is suppression of local boundary effects.
That separation is the release gate: standards semantics tell you what the values mean; the fixture tells you what a recorded environment did; the expected-case manifest tells you what you intended to test; and the ledger determines whether the evidence is admissible.
Develop the Relevant Skills With Refonte Learning
Refonte Learning’s Frontend Development program lists a four-month duration and a commitment of 10–12 hours per week. Its competencies include HTML5/CSS3, JavaScript ES6+, responsive web design, React, Redux, APIs/AJAX, Git, accessibility and performance optimization. Its curriculum includes Web HTML/CSS Foundations, Advanced CSS Techniques, API Integration and a Capstone Project.
The same page states a basic understanding of programming concepts as a requirement, says HTML/CSS familiarity is a plus, and separately lists “working towards a bachelor’s or higher-level degree” as an obligatory admission prerequisite. It names FrontEnd Developer, UI Developer and Web Developer as career results. Upon successful completion, the page says it offers a Training Certificate and a Certificate of Internship.
The program describes mentoring and project work. Its FAQ names Git, npm, React and Visual Studio Code. The curriculum covers HTML/CSS foundations and advanced CSS topics. This playbook’s overscroll-behavior example, Playwright fixture, expected-case manifest and release procedure are independent of the published curriculum.
