From 537c4af5288f977f3c1fcc4f931b61fbcf0c328b Mon Sep 17 00:00:00 2001
From: Javi R <4920956+rameerez@users.noreply.github.com>
Date: Sat, 10 Oct 2026 05:13:19 +0100
Subject: [PATCH 1/2] 0.2.0: the model-year step

Garages put this picker in booking forms, and those forms ask for the
model year; it is the top feature request. The API now carries
`years_on_record` ({first, last} or null) on every model in
GET /makes/{slug}/models, the endpoint the model step already calls, so
the year step needs no request of its own.

- New options: `year` (the third <select>, needs `model`),
  `placeholderYear` ("Year"), `initialYear` (also read from a
  server-rendered selection, reapplied on form reset), `yearFallback`.
- Picking a model fills the years newest first, then announces; a make
  change clears model AND year before announcing. onChange and .value
  gain `year` (number, null, or "other") ONLY when a year select is
  attached, so {make, model} consumers see the exact shape they had.
- The models list is stored with the model select it fills, past the
  stale-response guard, and the year fill reads the model select's
  value at fill time: a late list for an old make can never date the
  new one's models.
- yearFallback "range" (default): a model with no span (about 1 in 8,
  plus "Other / not listed") gets the current year back 40, so the
  field never dead-ends. "none": placeholder only, select disabled
  (the host's own disabled state is restored on re-enable and destroy).
- A missing `years_on_record` key (older API, mocks) or a malformed span
  is treated as null.

Tests: 18 -> 27; the only edit to an existing test is the version
assertion. Demo, README, CHANGELOG, package version updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                     |   8 +
 README.md                        |  31 +++-
 demo/index.html                  |   3 +
 make-model-dropdown.js           | 136 +++++++++++++++-
 package-lock.json                |   4 +-
 package.json                     |   2 +-
 test/make-model-dropdown.test.js | 271 ++++++++++++++++++++++++++++++-
 7 files changed, 439 insertions(+), 16 deletions(-)
 create mode 100644 CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..3ee8c99
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.2.0
+
+- **Model year step.** A new optional `year` select is filled from the chosen model's `years_on_record` span, newest first. Changing the make clears model and year before `onChange` fires, and changing the model refills the year before `onChange` fires. The spans come with the models list already loaded, so the year step makes no request of its own.
+- New options: `year`, `placeholderYear` (default `"Year"`), `initialYear` (a server-rendered selected year works too, and form reset restores it), and `yearFallback` for models with no span: `"range"` (default, the current year back 40 years, so the field never dead-ends) or `"none"` (placeholder only, select disabled).
+- `onChange` and `.value` gain `year` (a number, `null`, or `"other"` with `includeOther`) only when a year select is attached. Widgets without `year` behave exactly as in 0.1.4.
+- Older API responses without `years_on_record` are handled the same as `null`.
diff --git a/README.md b/README.md
index 203dfba..8f2238a 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ Get a free publishable API key at [vehiclesdb.com](https://vehiclesdb.com/settin
 <select id="make"></select>
 <select id="model"></select>
 
-<script src="https://cdn.jsdelivr.net/npm/make-model-dropdown@0.1.4"></script>
+<script src="https://cdn.jsdelivr.net/npm/make-model-dropdown@0.2.0"></script>
 <script>
   VehiclesDropdown.attach({
     key: "vdb_pk_your_key",
@@ -45,6 +45,7 @@ VehiclesDropdown.attach({
   key: "vdb_pk_…",        // required — your publishable key
   make: "#make",           // required — <select> element or selector
   model: "#model",         // optional — the dependent model <select>
+  year: "#year",           // optional — the model-year <select> (needs `model`)
 
   kind: "car",             // only one kind: car, motorcycle, moped, van, truck, bus
   country: "de",           // only vehicles evidenced in a register country
@@ -52,6 +53,8 @@ VehiclesDropdown.attach({
   topMakes: 40,            // only the N most-registered makes, best first (default: all)
   initialMake: "audi",     // preselect a make on load (slug or name)
   initialModel: "a3",      // preselect a model once its make's models load
+  initialYear: 2019,       // preselect a year once its model's years fill
+  yearFallback: "range",   // a model with no register span: "range" (default) or "none"
   values: "slug",          // option values: "slug" (default) or "name"
   includeOther: true,      // append "Other / not listed" — pickers should never dead-end
 
@@ -60,14 +63,34 @@ VehiclesDropdown.attach({
 
   placeholderMake: "Make",
   placeholderModel: "Model",
+  placeholderYear: "Year",
   attribution: true,       // the CC-BY credit line (keep it on — see below)
 
-  onChange: ({ make, model }) => {},
+  onChange: ({ make, model, year }) => {}, // `year` only when a year select is attached
   onError: (error) => {}
 })
 ```
 
-`attach` returns an instance with `.value` (`{ make, model }`) and `.destroy()`.
+`attach` returns an instance with `.value` (`{ make, model }`, plus `year` with a year select) and `.destroy()`.
+
+### Model year
+
+Booking and quote forms ask for the year, so the widget can fill a third `<select>`:
+
+```js
+VehiclesDropdown.attach({ key: "vdb_pk_your_key", make: "#make", model: "#model", year: "#year" })
+```
+
+Picking a model fills the year select from that model's span, newest first (most bookings are for recent cars); changing the make clears model and year together. `onChange` then reports `{ make, model, year }`, where `year` is a number, `null` when nothing is picked, or `"other"` for the `includeOther` escape hatch, exactly like make and model. Without `year`, nothing changes: the payload stays `{ make, model }`.
+
+The years are register years, not production years: the span runs from the first to the latest year the official registers have the model on record, which can differ from the factory's own dates.
+
+About one model in eight has no span on record (and an "Other / not listed" model never has one). `yearFallback` decides what those models get:
+
+- `"range"` (default): the current year back to 40 years ago. The year field never dead-ends, so a customer whose model the registers cannot date can still book.
+- `"none"`: the placeholder only (plus Other with `includeOther`), and the year select is disabled, for forms that would rather not offer years the registers cannot back up.
+
+No extra request is made: the spans come with the model list the widget already loads.
 
 ### Logos
 
@@ -94,7 +117,7 @@ npm ci
 npm test
 ```
 
-The test suite runs the published UMD artifact in a real DOM implementation and covers dependent loading, credential-scoped caches, combobox keyboard/blur behavior, labels, callback isolation, and object-URL cleanup.
+The test suite runs the published UMD artifact in a real DOM implementation and covers dependent loading, the year step and its fallbacks, credential-scoped caches, combobox keyboard/blur behavior, labels, callback isolation, and object-URL cleanup.
 
 ## License
 
diff --git a/demo/index.html b/demo/index.html
index b2936f8..8a486c3 100644
--- a/demo/index.html
+++ b/demo/index.html
@@ -25,6 +25,8 @@ <h1>VehiclesDropdown demo</h1>
     <select id="make" name="make"></select>
     <label for="model">Model</label>
     <select id="model" name="model"></select>
+    <label for="year">Year</label>
+    <select id="year" name="year"></select>
   </form>
 
   <pre id="state">{}</pre>
@@ -39,6 +41,7 @@ <h1>VehiclesDropdown demo</h1>
         apiBase: "http://localhost:3000/api/v1",
         make: "#make",
         model: "#model",
+        year: "#year",
         search: true,
         logos: true,
         includeOther: true,
diff --git a/make-model-dropdown.js b/make-model-dropdown.js
index 61cc8f8..fea9492 100644
--- a/make-model-dropdown.js
+++ b/make-model-dropdown.js
@@ -4,7 +4,8 @@
  *
  * A dependent make → model picker for any web page, powered by the VehiclesDB
  * API: 14,000+ models across 850+ makes (cars, motorcycles, mopeds, vans,
- * trucks, buses), reconciled from official registers of 14 countries.
+ * trucks, buses), reconciled from official registers of 14 countries. An
+ * optional third step picks the model year.
  *
  * Zero dependencies. No build step. MIT licensed.
  * Data: CC-BY 4.0 (identity layer) — the widget renders attribution for you.
@@ -23,6 +24,8 @@
     topMakes: null,        // e.g. 40 — only the N most-registered makes, best first
     initialMake: null,     // slug (or name) preselected on load, e.g. "audi"
     initialModel: null,    // slug (or name) preselected once its make's models load
+    initialYear: null,     // e.g. 2019 — preselected once its model's years fill
+    yearFallback: "range", // a model with no register span: "range" | "none"
     values: "slug",        // what option values hold: "slug" | "name"
     includeOther: false,   // append an "Other / not listed" escape hatch
     logos: false,          // render make logos (combobox mode only)
@@ -30,11 +33,16 @@
     attribution: true,     // "Vehicle data by VehiclesDB" line (CC-BY credit)
     placeholderMake: "Make",
     placeholderModel: "Model",
+    placeholderYear: "Year",
     requiredMessage: "Please select a vehicle make.", // validity message on a required make field
-    onChange: null,        // ({ make, model }) => {}
+    onChange: null,        // ({ make, model }) => {} — plus `year` when a year select is attached
     onError: null          // (error) => {}
   }
 
+  // How far back `yearFallback: "range"` reaches: the current year down to
+  // forty years ago covers the cars a garage actually sees on its ramps.
+  const FALLBACK_YEARS = 40
+
   // In-page caches — the dataset is immutable per release, so one fetch per
   // URL per pageview is the right amount of network.
   const jsonCache = new Map()
@@ -132,6 +140,24 @@
     select.add(new Option("Other / not listed", "other"))
   }
 
+  // A model's register span, or null. `years_on_record` reached the API
+  // after the widget did, so a missing key (older responses, mocks) means
+  // the same as an explicit null — and so does anything that is not a sane
+  // {first, last} pair. Never trust a span enough to render nonsense.
+  function yearSpan(model) {
+    const span = model && model.years_on_record
+    if (!span || !Number.isInteger(span.first) || !Number.isInteger(span.last)) return null
+    return span.first <= span.last ? span : null
+  }
+
+  // Years as fillSelect items, NEWEST FIRST: a garage books a recent car far
+  // more often than a classic, so the likely answer sits at the top.
+  function yearItems(first, last) {
+    const items = []
+    for (let year = last; year >= first; year -= 1) items.push({ name: String(year), slug: String(year) })
+    return items
+  }
+
   function attributionLine(container) {
     const p = document.createElement("p")
     p.className = "vdb-attribution"
@@ -175,6 +201,21 @@
       if (!this.config.initialModel && this.modelSelect?.value) {
         this.config.initialModel = this.modelSelect.value
       }
+      // The year depends on the model, so a year select without one has
+      // nothing to fill from — say so now, not with a silently empty field.
+      this.yearSelect = this.config.year ? resolveEl(this.config.year, "year") : null
+      if (this.yearSelect && !this.modelSelect) {
+        throw new Error("VehiclesDropdown: year needs a model <select> to depend on")
+      }
+      if (this.yearSelect && (this.yearSelect === this.makeSelect || this.yearSelect === this.modelSelect)) {
+        throw new Error("VehiclesDropdown: year must be a different <select> element from make and model")
+      }
+      if (!this.config.initialYear && this.yearSelect?.value) {
+        this.config.initialYear = this.yearSelect.value
+      }
+      // `yearFallback: "none"` disables the year select; remember the host's
+      // own setting so re-enabling (and destroy) never overrides it.
+      this.yearDisabled = this.yearSelect ? this.yearSelect.disabled : false
       this.destroyed = false
       this.logoUrls = new Map()
       this.objectUrls = new Set()
@@ -183,17 +224,20 @@
         this.combobox?.sync()
         this.makeChanged()
       }
-      this.handleModelChange = () => { this.notify() }
+      this.handleModelChange = () => { this.modelChanged() }
+      this.handleYearChange = () => { this.notify() }
       this.makeSelect.addEventListener("change", this.handleMakeChange)
       if (this.modelSelect) this.modelSelect.addEventListener("change", this.handleModelChange)
+      if (this.yearSelect) this.yearSelect.addEventListener("change", this.handleYearChange)
       this.form = this.makeSelect.form
       this.handleFormReset = () => {
         // The reset event fires before the browser restores form controls.
         // Wait one task, then rebuild the dependent options for the restored
-        // make and reapply the configured/server-rendered initial model.
+        // make and reapply the configured/server-rendered initial model and year.
         setTimeout(() => {
           if (this.destroyed) return
           this.initialModelApplied = false
+          this.initialYearApplied = false
           this.combobox?.sync()
           this.makeChanged()
         }, 0)
@@ -202,7 +246,7 @@
 
       if (this.config.search || this.config.logos) this.enhance()
       if (this.config.attribution) {
-        const anchor = (this.modelSelect || this.makeSelect).parentElement || this.makeSelect
+        const anchor = (this.yearSelect || this.modelSelect || this.makeSelect).parentElement || this.makeSelect
         this.attributionEl = attributionLine(anchor)
       }
 
@@ -256,9 +300,12 @@
       // make, so reporting {make: "suzuki", model: "golf"} for the moment
       // between the change and the fetch is not a lag, it is a wrong answer —
       // and onChange consumers write it straight into their form state.
+      // The year belongs to the old model, so it goes with it.
+      this.models = null
       if (this.modelSelect) {
         fillSelect(this.modelSelect, this.config.placeholderModel, [], this.config, "")
       }
+      if (this.yearSelect) this.fillYears()
       this.notify()
       if (this.destroyed) return
       if (!this.modelSelect) return
@@ -281,6 +328,10 @@
         const url = `${this.api}/makes/${encodeURIComponent(slug)}/models?${params}`
         const data = await fetchJSON(url, this.config.key, "models")
         if (this.destroyed || this.makeSelect.value !== makeValue) return
+        // The list and the select it fills are swapped TOGETHER, past the
+        // stale-response guard: the year step reads its spans from this list,
+        // so it can only ever describe the models actually on screen.
+        this.models = data.models
         fillSelect(this.modelSelect, this.config.placeholderModel, data.models, this.config, "")
         if (this.config.includeOther) appendOther(this.modelSelect)
 
@@ -297,7 +348,7 @@
             Array.from(this.modelSelect.options).forEach((option) => {
               option.defaultSelected = option.value === this.modelSelect.value
             })
-            this.notify()
+            this.modelChanged()
           }
         }
       } catch (error) {
@@ -305,6 +356,63 @@
       }
     }
 
+    modelChanged() {
+      // Same rule as the make: refill the year for THIS model before
+      // announcing, so no payload ever pairs a model with another one's year.
+      if (this.yearSelect) this.fillYears()
+      this.notify()
+    }
+
+    // The year step makes no request: the spans ride on the models list the
+    // model step already fetched (this.models). So its only race is the
+    // model select itself — read its value NOW, at fill time, never from a
+    // value captured earlier, and look it up in the list that filled it.
+    fillYears() {
+      const select = this.yearSelect
+      const modelValue = this.modelSelect.value
+      select.disabled = this.yearDisabled
+      if (!modelValue) {
+        fillSelect(select, this.config.placeholderYear, [], this.config, "")
+        return
+      }
+
+      // "Other / not listed" has no span by definition; it takes the
+      // fallback like any other model the registers cannot date.
+      const model = modelValue === "other"
+        ? null
+        : this.models?.find((m) => optionValue(this.config, m) === modelValue)
+      const span = yearSpan(model)
+      // THE DEFAULT IS A RANGE, NOT A DEAD END. About one model in eight has
+      // no register span, and a booking form whose year field goes blank for
+      // that customer is a lost booking; the picker should never dead-end.
+      // "none" is the opt-out for forms that would rather ask nothing than
+      // offer years the registers cannot vouch for.
+      const current = new Date().getFullYear()
+      const none = !span && this.config.yearFallback === "none"
+      const items = span ? yearItems(span.first, span.last)
+        : none ? []
+        : yearItems(current - FALLBACK_YEARS, current)
+      fillSelect(select, this.config.placeholderYear, items, this.config, "")
+      if (this.config.includeOther) appendOther(select)
+      if (none) select.disabled = true
+
+      // The preselected year, applied exactly once and only to its intended
+      // model — after that the person is driving.
+      const wantedModel = this.config.initialModel
+      const intendedInitialModel = !wantedModel || modelValue === wantedModel ||
+        model?.slug === wantedModel || model?.name === wantedModel
+      if (this.config.initialYear && !this.initialYearApplied && intendedInitialModel) {
+        this.initialYearApplied = true
+        const wanted = String(this.config.initialYear)
+        if (!select.disabled && Array.from(select.options).some((option) => option.value && option.value === wanted)) {
+          select.value = wanted
+          Array.from(select.options).forEach((option) => {
+            option.defaultSelected = option.value === select.value
+          })
+        }
+      }
+    }
+
     async logoUrl(slug) {
       const cacheKey = requestCacheKey(logoURL(this.api, slug), this.config.key)
       if (this.logoUrls.has(cacheKey)) return this.logoUrls.get(cacheKey)
@@ -623,10 +731,18 @@
     }
 
     get value() {
-      return {
+      const value = {
         make: this.makeSelect.value || null,
         model: this.modelSelect ? (this.modelSelect.value || null) : null
       }
+      // `year` exists only when a year select does: {make, model} consumers
+      // keep the exact shape they were written against. A year is a number;
+      // the escape hatch reports "other" like make and model do.
+      if (this.yearSelect) {
+        const year = this.yearSelect.value
+        value.year = !year ? null : year === "other" ? "other" : Number(year)
+      }
+      return value
     }
 
     destroy() {
@@ -634,6 +750,10 @@
       this.destroyed = true
       this.makeSelect.removeEventListener("change", this.handleMakeChange)
       if (this.modelSelect) this.modelSelect.removeEventListener("change", this.handleModelChange)
+      if (this.yearSelect) {
+        this.yearSelect.removeEventListener("change", this.handleYearChange)
+        this.yearSelect.disabled = this.yearDisabled
+      }
       this.form?.removeEventListener("reset", this.handleFormReset)
       if (this.combobox) this.combobox.destroy()
       if (this.attributionEl) this.attributionEl.remove()
@@ -645,6 +765,6 @@
 
   return {
     attach(options) { return new Instance(options) },
-    version: "0.1.4"
+    version: "0.2.0"
   }
 })
diff --git a/package-lock.json b/package-lock.json
index 280fa01..cf2ee5a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "make-model-dropdown",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "make-model-dropdown",
-      "version": "0.1.4",
+      "version": "0.2.0",
       "license": "MIT",
       "devDependencies": {
         "jsdom": "^26.1.0"
diff --git a/package.json b/package.json
index c0245df..6f05d66 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "make-model-dropdown",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Car make and model dropdown for any web page. A dependent make/model picker with live vehicle data from the VehiclesDB API: 14,000+ models, 850+ makes, cars and motorcycles to trucks and buses, from official registers of 14 countries. Zero dependencies.",
   "keywords": [
     "car make model dropdown",
diff --git a/test/make-model-dropdown.test.js b/test/make-model-dropdown.test.js
index cb3943c..ed51eb7 100644
--- a/test/make-model-dropdown.test.js
+++ b/test/make-model-dropdown.test.js
@@ -12,7 +12,7 @@ test("the published browser script installs the documented global", () => {
 
   browser.window.eval(source)
 
-  assert.equal(browser.window.VehiclesDropdown.version, "0.1.4")
+  assert.equal(browser.window.VehiclesDropdown.version, "0.2.0")
   assert.equal(typeof browser.window.VehiclesDropdown.attach, "function")
   browser.window.close()
 })
@@ -597,3 +597,272 @@ test("a consumer onChange bug is not delivered to onError as an API failure", as
   await new Promise((resolve) => setTimeout(resolve, 20))
   assert.equal(apiErrors.length, 0, "onError is for API failures, not consumer exceptions")
 })
+
+// The year step. Every select below is driven the way a person drives it:
+// set the value, then dispatch the change event the browser would.
+function pick(select, value) {
+  select.value = value
+  select.dispatchEvent(new Event("change", { bubbles: true }))
+}
+
+function optionValues(select) {
+  return Array.from(select.options).map((option) => option.value)
+}
+
+test("the year step fills the chosen model's register span, newest first", async () => {
+  const document = installDOM(`<select id="make"></select><select id="model"></select><select id="year"></select>`)
+  const base = apiBase("year-span")
+  const changes = []
+  global.fetch = async (url) => new URL(url).pathname.endsWith("/models")
+    ? jsonResponse({ models: [{ name: "A3", slug: "a3", years_on_record: { first: 2018, last: 2021 } }] })
+    : jsonResponse({ makes: [{ name: "Audi", slug: "audi" }] })
+
+  const instance = attach({
+    key: "year-span-key", apiBase: base, make: "#make", model: "#model", year: "#year",
+    attribution: false, onChange(value) { changes.push(value) }
+  })
+  await waitFor(() => document.querySelector("#make").options.length === 2)
+  pick(document.querySelector("#make"), "audi")
+  await waitFor(() => document.querySelector("#model").options.length === 2)
+  const year = document.querySelector("#year")
+  assert.deepEqual(optionValues(year), [""], "no model yet, no years yet")
+
+  const before = changes.length
+  pick(document.querySelector("#model"), "a3")
+  assert.deepEqual(optionValues(year), ["", "2021", "2020", "2019", "2018"])
+  assert.equal(year.options[0].textContent, "Year")
+  assert.equal(changes.length, before + 1, "one model pick, one announcement")
+  assert.deepEqual(changes.at(-1), { make: "audi", model: "a3", year: null })
+
+  pick(year, "2019")
+  assert.deepEqual(changes.at(-1), { make: "audi", model: "a3", year: 2019 })
+  assert.deepEqual(instance.value, { make: "audi", model: "a3", year: 2019 })
+})
+
+test("a model the registers cannot date falls back to a recent range, or to nothing", async () => {
+  const document = installDOM(`
+    <select id="make-a"></select><select id="model-a"></select><select id="year-a"></select>
+    <select id="make-b"></select><select id="model-b"></select><select id="year-b"></select>
+  `)
+  const base = apiBase("year-fallback")
+  global.fetch = async (url) => new URL(url).pathname.endsWith("/models")
+    ? jsonResponse({ models: [
+      { name: "Q7", slug: "q7", years_on_record: null },
+      { name: "Q5", slug: "q5" }, // an older API response: no key at all
+      { name: "A3", slug: "a3", years_on_record: { first: 2020, last: 2021 } }
+    ] })
+    : jsonResponse({ makes: [{ name: "Audi", slug: "audi" }] })
+
+  attach({ key: "fallback-key", apiBase: base, make: "#make-a", model: "#model-a", year: "#year-a", attribution: false })
+  const none = attach({
+    key: "fallback-key", apiBase: base, make: "#make-b", model: "#model-b", year: "#year-b",
+    yearFallback: "none", attribution: false
+  })
+  await waitFor(() => document.querySelector("#make-a").options.length === 2 && document.querySelector("#make-b").options.length === 2)
+  pick(document.querySelector("#make-a"), "audi")
+  pick(document.querySelector("#make-b"), "audi")
+  await waitFor(() => document.querySelector("#model-a").options.length === 4 && document.querySelector("#model-b").options.length === 4)
+
+  // "range" (the default): the current year down forty, so the field never dead-ends.
+  const current = new Date().getFullYear()
+  const range = document.querySelector("#year-a")
+  for (const model of ["q7", "q5"]) {
+    pick(document.querySelector("#model-a"), model)
+    assert.equal(range.options.length, 1 + 41, `${model}: placeholder plus ${current}..${current - 40}`)
+    assert.equal(range.options[1].value, String(current))
+    assert.equal(range.options[41].value, String(current - 40))
+    assert.equal(range.disabled, false)
+  }
+
+  // "none": only the placeholder, and the field says it has nothing to ask.
+  const empty = document.querySelector("#year-b")
+  pick(document.querySelector("#model-b"), "q5")
+  assert.deepEqual(optionValues(empty), [""])
+  assert.equal(empty.disabled, true)
+  pick(document.querySelector("#model-b"), "a3")
+  assert.deepEqual(optionValues(empty), ["", "2021", "2020"])
+  assert.equal(empty.disabled, false, "a dated model re-enables the field")
+
+  pick(document.querySelector("#model-b"), "q7")
+  none.destroy()
+  instances = instances.filter((candidate) => candidate !== none)
+  assert.equal(empty.disabled, false, "destroy hands the host its own disabled state back")
+})
+
+test("a make change clears the model and the year before announcing", async () => {
+  const document = installDOM(`<select id="make"></select><select id="model"></select><select id="year"></select>`)
+  const base = apiBase("year-clear")
+  const changes = []
+  global.fetch = async (url) => {
+    if (url.includes("/audi/models")) {
+      return jsonResponse({ models: [{ name: "A3", slug: "a3", years_on_record: { first: 2018, last: 2021 } }] })
+    }
+    if (url.includes("/bmw/models")) return new Promise(() => {}) // still loading
+    return jsonResponse({ makes: [{ name: "Audi", slug: "audi" }, { name: "BMW", slug: "bmw" }] })
+  }
+
+  attach({
+    key: "year-clear-key", apiBase: base, make: "#make", model: "#model", year: "#year",
+    attribution: false, onChange(value) { changes.push(value) }
+  })
+  await waitFor(() => document.querySelector("#make").options.length === 3)
+  pick(document.querySelector("#make"), "audi")
+  await waitFor(() => document.querySelector("#model").options.length === 2)
+  pick(document.querySelector("#model"), "a3")
+  pick(document.querySelector("#year"), "2019")
+  assert.deepEqual(changes.at(-1), { make: "audi", model: "a3", year: 2019 })
+
+  pick(document.querySelector("#make"), "bmw")
+  // SYNCHRONOUSLY, before BMW's models arrive: an Audi year against a BMW is
+  // a wrong answer, not a lag.
+  assert.deepEqual(optionValues(document.querySelector("#year")), [""])
+  assert.deepEqual(changes.at(-1), { make: "bmw", model: null, year: null })
+})
+
+test("a late model list for an older make can never fill the years", async () => {
+  const document = installDOM(`<select id="make"></select><select id="model"></select><select id="year"></select>`)
+  const base = apiBase("year-stale")
+  const resolvers = {}
+  global.fetch = async (url) => {
+    if (!url.includes("/models")) {
+      return jsonResponse({ makes: [{ name: "Audi", slug: "audi" }, { name: "BMW", slug: "bmw" }] })
+    }
+    return new Promise((resolve) => {
+      resolvers[url.includes("/audi/") ? "audi" : "bmw"] = resolve
+    })
+  }
+
+  attach({ key: "year-stale-key", apiBase: base, make: "#make", model: "#model", year: "#year", attribution: false })
+  await waitFor(() => document.querySelector("#make").options.length === 3)
+  const make = document.querySelector("#make")
+  pick(make, "audi")
+  await waitFor(() => resolvers.audi)
+  pick(make, "bmw")
+  await waitFor(() => resolvers.bmw)
+
+  // The same slug under both makes, with different spans: the only way the
+  // years could tell which list filled them.
+  resolvers.bmw(jsonResponse({ models: [{ name: "Sport", slug: "sport", years_on_record: { first: 2020, last: 2021 } }] }))
+  await waitFor(() => document.querySelector("#model").options.length === 2)
+  resolvers.audi(jsonResponse({ models: [{ name: "Sport", slug: "sport", years_on_record: { first: 1990, last: 1992 } }] }))
+  await new Promise((resolve) => setTimeout(resolve, 10))
+
+  pick(document.querySelector("#model"), "sport")
+  assert.deepEqual(optionValues(document.querySelector("#year")), ["", "2021", "2020"])
+})
+
+test("initialYear waits for its intended model and survives a form reset", async () => {
+  const document = installDOM(`
+    <form id="vehicle">
+      <select id="make"></select><select id="model"></select><select id="year"></select>
+    </form>
+  `)
+  const base = apiBase("year-initial")
+  const changes = []
+  global.fetch = async (url) => new URL(url).pathname.endsWith("/models")
+    ? jsonResponse({ models: [
+      { name: "A1", slug: "a1", years_on_record: { first: 2010, last: 2024 } },
+      { name: "A3", slug: "a3", years_on_record: { first: 2015, last: 2022 } }
+    ] })
+    : jsonResponse({ makes: [{ name: "Audi", slug: "audi" }] })
+
+  attach({
+    key: "year-initial-key", apiBase: base, make: "#make", model: "#model", year: "#year",
+    initialMake: "audi", initialModel: "a3", initialYear: 2019, attribution: false,
+    onChange(value) { changes.push(value) }
+  })
+  const year = document.querySelector("#year")
+  await waitFor(() => year.value === "2019")
+  assert.equal(document.querySelector("#model").value, "a3")
+  assert.equal(year.selectedOptions[0].defaultSelected, true, "a form reset must land back here")
+  assert.deepEqual(changes.at(-1), { make: "audi", model: "a3", year: 2019 })
+
+  pick(document.querySelector("#model"), "a1")
+  assert.equal(year.value, "", "the person is driving now; a new model resets the year")
+  pick(year, "2012")
+
+  document.querySelector("#vehicle").reset()
+  await waitFor(() => document.querySelector("#model").value === "a3" && year.value === "2019")
+})
+
+test("a server-rendered year is reapplied once its model's years fill", async () => {
+  const document = installDOM(`
+    <select id="make"><option value="audi" selected>Audi</option></select>
+    <select id="model"><option value="a3" selected>A3</option></select>
+    <select id="year"><option value="2019" selected>2019</option></select>
+  `)
+  const base = apiBase("year-server")
+  global.fetch = async (url) => new URL(url).pathname.endsWith("/models")
+    ? jsonResponse({ models: [{ name: "A3", slug: "a3", years_on_record: { first: 2015, last: 2022 } }] })
+    : jsonResponse({ makes: [{ name: "Audi", slug: "audi" }] })
+
+  const instance = attach({ key: "year-server-key", apiBase: base, make: "#make", model: "#model", year: "#year", attribution: false })
+  await waitFor(() => document.querySelector("#year").options.length === 9)
+  assert.deepEqual(instance.value, { make: "audi", model: "a3", year: 2019 })
+})
+
+test("Other / not listed reaches the year step and never strands it", async () => {
+  const document = installDOM(`<select id="make"></select><select id="model"></select><select id="year"></select>`)
+  const base = apiBase("year-other")
+  const changes = []
+  global.fetch = async (url) => new URL(url).pathname.endsWith("/models")
+    ? jsonResponse({ models: [{ name: "A3", slug: "a3", years_on_record: { first: 2020, last: 2021 } }] })
+    : jsonResponse({ makes: [{ name: "Audi", slug: "audi" }] })
+
+  attach({
+    key: "year-other-key", apiBase: base, make: "#make", model: "#model", year: "#year",
+    includeOther: true, attribution: false, onChange(value) { changes.push(value) }
+  })
+  await waitFor(() => document.querySelector("#make").options.length === 3)
+  const make = document.querySelector("#make")
+  const model = document.querySelector("#model")
+  const year = document.querySelector("#year")
+  pick(make, "audi")
+  await waitFor(() => model.options.length === 3)
+  pick(model, "a3")
+  assert.deepEqual(optionValues(year), ["", "2021", "2020", "other"])
+  pick(year, "other")
+  assert.deepEqual(changes.at(-1), { make: "audi", model: "a3", year: "other" })
+
+  // An unlisted model has no span, so it takes the fallback range — plus Other.
+  pick(model, "other")
+  assert.equal(year.options[1].value, String(new Date().getFullYear()))
+  assert.equal(year.options[year.options.length - 1].value, "other")
+  assert.deepEqual(changes.at(-1), { make: "audi", model: "other", year: null })
+
+  pick(make, "other")
+  assert.deepEqual(optionValues(model), ["", "other"])
+  assert.deepEqual(optionValues(year), [""])
+  assert.deepEqual(changes.at(-1), { make: "other", model: null, year: null })
+})
+
+test("a widget without a year select keeps the exact {make, model} contract", async () => {
+  const document = installDOM(`<select id="make"></select><select id="model"></select><select id="year"></select>`)
+  const base = apiBase("year-absent")
+  const changes = []
+  global.fetch = async (url) => new URL(url).pathname.endsWith("/models")
+    ? jsonResponse({ models: [{ name: "A3", slug: "a3", years_on_record: { first: 2020, last: 2021 } }] })
+    : jsonResponse({ makes: [{ name: "Audi", slug: "audi" }] })
+
+  const instance = attach({
+    key: "year-absent-key", apiBase: base, make: "#make", model: "#model",
+    attribution: false, onChange(value) { changes.push(value) }
+  })
+  await waitFor(() => document.querySelector("#make").options.length === 2)
+  pick(document.querySelector("#make"), "audi")
+  await waitFor(() => document.querySelector("#model").options.length === 2)
+  pick(document.querySelector("#model"), "a3")
+
+  assert.deepEqual(changes.at(-1), { make: "audi", model: "a3" })
+  assert.deepEqual(Object.keys(instance.value), ["make", "model"])
+  assert.equal(document.querySelector("#year").options.length, 0, "an unconfigured select is never touched")
+})
+
+test("attach validates the year select contract synchronously", () => {
+  installDOM(`<select id="make"></select><select id="model"></select><select id="year"></select>`)
+
+  assert.throws(() => VehiclesDropdown.attach({ key: "key", make: "#make", year: "#year" }), /needs a model/)
+  assert.throws(() => VehiclesDropdown.attach({ key: "key", make: "#make", model: "#model", year: "#model" }), /different <select>/)
+  assert.throws(() => VehiclesDropdown.attach({ key: "key", make: "#make", model: "#model", year: "#make" }), /different <select>/)
+  assert.throws(() => VehiclesDropdown.attach({ key: "key", make: "#make", model: "#model", year: "#missing" }), /year element not found/)
+})

From e3c28e00a68e2be1825147b9341debfd6eba3d27 Mon Sep 17 00:00:00 2001
From: Javi R <4920956+rameerez@users.noreply.github.com>
Date: Sat, 10 Oct 2026 05:24:35 +0100
Subject: [PATCH 2/2] 0.2.0 review fixes: sane spans, kept years, host-owned
 disabled

Five review findings against 537c4af, each with a test that fails on it:

- Spans are sane only within 1886 <= first <= last <= next year;
  anything else takes the fallback. {last: 1e300} passed
  Number.isInteger and, as 1e300 - 1 === 1e300, never finished counting
  down; {first: -8000} built 10,028 options; {0, 0} rendered "0";
  {last: 2099} offered 70+ future years. Lists are now capped near 140.
- A host-supplied year (initialYear or a server-rendered selection)
  outside the span is kept: inserted newest-first in its place,
  selected, and announced once via console.warn. Register spans make
  this common in edit forms; it used to come back as year null.
- `disabled` belongs to the host. The widget sets it only for its own
  reason (yearFallback "none" with nothing to choose), remembers that it
  did, and only ever undoes that, on refill and on destroy. initialYear
  no longer skips a host-disabled field.
- yearFallback "none" with includeOther leaves the select enabled with
  placeholder + Other; it is disabled only when there is nothing to pick.
- initialYear now also checks the intended initial make, and tests pin
  both the make and the model checks (each one's removal fails a test).
  The `this.models = null` on make change stays: a test shows it is
  observable when host code injects a model option mid-fetch.

Also: the widget's prose (file header, README, package.json description)
no longer states a register-country count, which had already drifted
(14 -> 15 with Norway); it says "official national vehicle registers".

Tests: 27 -> 32.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                     |   4 +-
 README.md                        |   6 +-
 make-model-dropdown.js           |  89 ++++++++++----
 package.json                     |   2 +-
 test/make-model-dropdown.test.js | 199 +++++++++++++++++++++++++++++++
 5 files changed, 276 insertions(+), 24 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3ee8c99..894e067 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,4 +5,6 @@
 - **Model year step.** A new optional `year` select is filled from the chosen model's `years_on_record` span, newest first. Changing the make clears model and year before `onChange` fires, and changing the model refills the year before `onChange` fires. The spans come with the models list already loaded, so the year step makes no request of its own.
 - New options: `year`, `placeholderYear` (default `"Year"`), `initialYear` (a server-rendered selected year works too, and form reset restores it), and `yearFallback` for models with no span: `"range"` (default, the current year back 40 years, so the field never dead-ends) or `"none"` (placeholder only, select disabled).
 - `onChange` and `.value` gain `year` (a number, `null`, or `"other"` with `includeOther`) only when a year select is attached. Widgets without `year` behave exactly as in 0.1.4.
-- Older API responses without `years_on_record` are handled the same as `null`.
+- Older API responses without `years_on_record`, and spans outside 1886 to next year, are handled the same as `null`.
+- A host-supplied year outside the model's span is kept (inserted in order and selected, with one `console.warn`), never dropped.
+- The widget disables the year select only for `yearFallback: "none"` with nothing to choose (with `includeOther`, Other stays choosable), and only ever undoes its own disabling.
diff --git a/README.md b/README.md
index 8f2238a..6591076 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Car, motorcycle and truck make and model dropdown
 
-**The make/model picker you stopped hand-maintaining.** `make-model-dropdown` turns two `<select>` elements into a dependent make → model dropdown, populated live from the [VehiclesDB API](https://vehiclesdb.com/api): **14,000+ models across 850+ makes**, six vehicle kinds — cars, motorcycles (motorbikes), mopeds, vans, trucks and buses — reconciled from the official vehicle registers of 14 countries and refreshed monthly. One `kind` option turns the same widget into a car picker, a motorcycle picker or a truck picker.
+**The make/model picker you stopped hand-maintaining.** `make-model-dropdown` turns two `<select>` elements into a dependent make → model dropdown, populated live from the [VehiclesDB API](https://vehiclesdb.com/api): **14,000+ models across 850+ makes**, six vehicle kinds — cars, motorcycles (motorbikes), mopeds, vans, trucks and buses — reconciled from official national vehicle registers and refreshed monthly. One `kind` option turns the same widget into a car picker, a motorcycle picker or a truck picker.
 
 Zero dependencies. No build step. Works with plain HTML forms, React, Vue, Rails, anything that renders a `<select>`.
 
@@ -88,7 +88,9 @@ The years are register years, not production years: the span runs from the first
 About one model in eight has no span on record (and an "Other / not listed" model never has one). `yearFallback` decides what those models get:
 
 - `"range"` (default): the current year back to 40 years ago. The year field never dead-ends, so a customer whose model the registers cannot date can still book.
-- `"none"`: the placeholder only (plus Other with `includeOther`), and the year select is disabled, for forms that would rather not offer years the registers cannot back up.
+- `"none"`: no years, for forms that would rather not offer years the registers cannot back up. With `includeOther` the select stays enabled with the placeholder and Other, so that choice can still be made; without it there is nothing to choose, so the select is disabled. The widget only ever undoes its own disabling and never overrides a `disabled` your page sets.
+
+A year the host supplies (`initialYear`, or a server-rendered selected option in an edit form) is never dropped: if it falls outside the model's span it is added to the list in its place, selected, and logged once with `console.warn`.
 
 No extra request is made: the spans come with the model list the widget already loads.
 
diff --git a/make-model-dropdown.js b/make-model-dropdown.js
index fea9492..6eedacb 100644
--- a/make-model-dropdown.js
+++ b/make-model-dropdown.js
@@ -4,7 +4,7 @@
  *
  * A dependent make → model picker for any web page, powered by the VehiclesDB
  * API: 14,000+ models across 850+ makes (cars, motorcycles, mopeds, vans,
- * trucks, buses), reconciled from official registers of 14 countries. An
+ * trucks, buses), reconciled from official national vehicle registers. An
  * optional third step picks the model year.
  *
  * Zero dependencies. No build step. MIT licensed.
@@ -42,6 +42,11 @@
   // How far back `yearFallback: "range"` reaches: the current year down to
   // forty years ago covers the cars a garage actually sees on its ramps.
   const FALLBACK_YEARS = 40
+  // The bounds of a believable register span: nothing was registered as a
+  // motor vehicle before 1886 (the Benz Patent-Motorwagen), and nothing is on
+  // record past next year's model year. They also cap every year list at
+  // ~140 rows, whatever the payload says.
+  const FIRST_YEAR = 1886
 
   // In-page caches — the dataset is immutable per release, so one fetch per
   // URL per pageview is the right amount of network.
@@ -143,11 +148,14 @@
   // A model's register span, or null. `years_on_record` reached the API
   // after the widget did, so a missing key (older responses, mocks) means
   // the same as an explicit null — and so does anything that is not a sane
-  // {first, last} pair. Never trust a span enough to render nonsense.
-  function yearSpan(model) {
+  // {first, last} pair inside FIRST_YEAR..next year. Never trust a span
+  // enough to render nonsense: `last: 1e300` passes Number.isInteger and,
+  // since 1e300 - 1 === 1e300, would never finish counting down.
+  function yearSpan(model, currentYear) {
     const span = model && model.years_on_record
     if (!span || !Number.isInteger(span.first) || !Number.isInteger(span.last)) return null
-    return span.first <= span.last ? span : null
+    const sane = FIRST_YEAR <= span.first && span.first <= span.last && span.last <= currentYear + 1
+    return sane ? span : null
   }
 
   // Years as fillSelect items, NEWEST FIRST: a garage books a recent car far
@@ -213,9 +221,10 @@
       if (!this.config.initialYear && this.yearSelect?.value) {
         this.config.initialYear = this.yearSelect.value
       }
-      // `yearFallback: "none"` disables the year select; remember the host's
-      // own setting so re-enabling (and destroy) never overrides it.
-      this.yearDisabled = this.yearSelect ? this.yearSelect.disabled : false
+      // `disabled` belongs to the host. The widget only ever disables the
+      // year select for its OWN reason (yearFallback "none" with nothing to
+      // choose), remembers that it did, and only ever undoes that.
+      this.yearDisabledByWidget = false
       this.destroyed = false
       this.logoUrls = new Map()
       this.objectUrls = new Set()
@@ -370,9 +379,9 @@
     fillYears() {
       const select = this.yearSelect
       const modelValue = this.modelSelect.value
-      select.disabled = this.yearDisabled
       if (!modelValue) {
         fillSelect(select, this.config.placeholderYear, [], this.config, "")
+        this.disableYear(false)
         return
       }
 
@@ -381,36 +390,76 @@
       const model = modelValue === "other"
         ? null
         : this.models?.find((m) => optionValue(this.config, m) === modelValue)
-      const span = yearSpan(model)
+      const current = new Date().getFullYear()
+      const span = yearSpan(model, current)
       // THE DEFAULT IS A RANGE, NOT A DEAD END. About one model in eight has
       // no register span, and a booking form whose year field goes blank for
       // that customer is a lost booking; the picker should never dead-end.
       // "none" is the opt-out for forms that would rather ask nothing than
       // offer years the registers cannot vouch for.
-      const current = new Date().getFullYear()
       const none = !span && this.config.yearFallback === "none"
       const items = span ? yearItems(span.first, span.last)
         : none ? []
         : yearItems(current - FALLBACK_YEARS, current)
       fillSelect(select, this.config.placeholderYear, items, this.config, "")
       if (this.config.includeOther) appendOther(select)
-      if (none) select.disabled = true
 
       // The preselected year, applied exactly once and only to its intended
-      // model — after that the person is driving.
+      // make and model — after that the person is driving.
+      const make = this.makes?.find((m) => optionValue(this.config, m) === this.makeSelect.value)
+      const wantedMake = this.config.initialMake
       const wantedModel = this.config.initialModel
+      const intendedInitialMake = !wantedMake || make?.slug === wantedMake || make?.name === wantedMake
       const intendedInitialModel = !wantedModel || modelValue === wantedModel ||
         model?.slug === wantedModel || model?.name === wantedModel
-      if (this.config.initialYear && !this.initialYearApplied && intendedInitialModel) {
+      if (this.config.initialYear && !this.initialYearApplied && intendedInitialMake && intendedInitialModel) {
         this.initialYearApplied = true
-        const wanted = String(this.config.initialYear)
-        if (!select.disabled && Array.from(select.options).some((option) => option.value && option.value === wanted)) {
-          select.value = wanted
-          Array.from(select.options).forEach((option) => {
-            option.defaultSelected = option.value === select.value
-          })
+        this.keepYear(String(this.config.initialYear), modelValue)
+      }
+
+      // Disabled only when there is truly nothing to choose: with
+      // includeOther the escape hatch is a choice, and so is a kept year.
+      this.disableYear(none && select.options.length === 1)
+    }
+
+    // NEVER DROP A VALUE THE HOST GAVE US. Spans are register years, so an
+    // edit form's saved 2024 against a model on record 2015–2022 is common,
+    // not an error — keep it as an option, in its place (newest first), and
+    // say so once, the way a dropped make is announced.
+    keepYear(wanted, modelValue) {
+      const select = this.yearSelect
+      if (!Array.from(select.options).some((option) => option.value && option.value === wanted)) {
+        if (wanted === "other") appendOther(select)
+        else if (/^\d+$/.test(wanted)) {
+          const before = Array.from(select.options).find((option) =>
+            option.value === "other" || (option.value && Number(option.value) < Number(wanted)))
+          select.add(new Option(wanted, wanted), before || null)
+        } else {
+          console.warn(`[VehiclesDropdown] initial year ${JSON.stringify(wanted)} is not a year; selection cleared`)
+          return
+        }
+        if (!this.yearKeptWarned) {
+          this.yearKeptWarned = true
+          console.warn(`[VehiclesDropdown] year ${JSON.stringify(wanted)} is not on record for model ${JSON.stringify(modelValue)}; kept as given`)
         }
       }
+      select.value = wanted
+      Array.from(select.options).forEach((option) => {
+        option.defaultSelected = option.value === select.value
+      })
+    }
+
+    // The widget's own reason to disable the year select, and only that:
+    // set on entering it (unless the host already had the field disabled),
+    // cleared on leaving it, never a write-back of the host's state.
+    disableYear(disable) {
+      if (disable && !this.yearDisabledByWidget && !this.yearSelect.disabled) {
+        this.yearSelect.disabled = true
+        this.yearDisabledByWidget = true
+      } else if (!disable && this.yearDisabledByWidget) {
+        this.yearSelect.disabled = false
+        this.yearDisabledByWidget = false
+      }
     }
 
     async logoUrl(slug) {
@@ -752,7 +801,7 @@
       if (this.modelSelect) this.modelSelect.removeEventListener("change", this.handleModelChange)
       if (this.yearSelect) {
         this.yearSelect.removeEventListener("change", this.handleYearChange)
-        this.yearSelect.disabled = this.yearDisabled
+        this.disableYear(false)
       }
       this.form?.removeEventListener("reset", this.handleFormReset)
       if (this.combobox) this.combobox.destroy()
diff --git a/package.json b/package.json
index 6f05d66..65fb234 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "make-model-dropdown",
   "version": "0.2.0",
-  "description": "Car make and model dropdown for any web page. A dependent make/model picker with live vehicle data from the VehiclesDB API: 14,000+ models, 850+ makes, cars and motorcycles to trucks and buses, from official registers of 14 countries. Zero dependencies.",
+  "description": "Car make and model dropdown for any web page. A dependent make/model picker with live vehicle data from the VehiclesDB API: 14,000+ models, 850+ makes, cars and motorcycles to trucks and buses, from official national vehicle registers. Zero dependencies.",
   "keywords": [
     "car make model dropdown",
     "motorcycle make model dropdown",
diff --git a/test/make-model-dropdown.test.js b/test/make-model-dropdown.test.js
index ed51eb7..129ab3f 100644
--- a/test/make-model-dropdown.test.js
+++ b/test/make-model-dropdown.test.js
@@ -866,3 +866,202 @@ test("attach validates the year select contract synchronously", () => {
   assert.throws(() => VehiclesDropdown.attach({ key: "key", make: "#make", model: "#model", year: "#make" }), /different <select>/)
   assert.throws(() => VehiclesDropdown.attach({ key: "key", make: "#make", model: "#model", year: "#missing" }), /year element not found/)
 })
+
+test("initialYear never lands on a make or model it was not meant for", async () => {
+  const document = installDOM(`
+    <select id="make-a"><option value="volkswagen" selected>Volkswagen</option></select>
+    <select id="model-a"></select><select id="year-a"></select>
+    <select id="make-b"><option value="volkswagen" selected>Volkswagen</option></select>
+    <select id="model-b"></select><select id="year-b"></select>
+  `)
+  const base = apiBase("year-intended")
+  global.fetch = async (url) => {
+    if (url.includes("/volkswagen/models")) {
+      return jsonResponse({ models: [{ name: "Golf", slug: "golf", years_on_record: { first: 2015, last: 2022 } }] })
+    }
+    if (url.includes("/audi/models")) {
+      return jsonResponse({ models: [{ name: "A3", slug: "a3", years_on_record: { first: 2015, last: 2022 } }] })
+    }
+    return jsonResponse({ makes: [{ name: "Audi", slug: "audi" }, { name: "Volkswagen", slug: "volkswagen" }] })
+  }
+
+  // An initial model and no initial make: the make check passes for any
+  // make, so only the model check stands between the Golf and the A3's year.
+  attach({
+    key: "year-intended-key", apiBase: base, make: "#make-a", model: "#model-a", year: "#year-a",
+    initialModel: "a3", initialYear: 2019, attribution: false
+  })
+  // Without one: a Volkswagen is still not the Audi the year was meant for.
+  attach({
+    key: "year-intended-key", apiBase: base, make: "#make-b", model: "#model-b", year: "#year-b",
+    initialMake: "audi", initialYear: 2019, attribution: false
+  })
+  await waitFor(() => document.querySelector("#model-a").options.length === 2 && document.querySelector("#model-b").options.length === 2)
+  for (const side of ["a", "b"]) {
+    pick(document.querySelector(`#model-${side}`), "golf")
+    assert.equal(document.querySelector(`#year-${side}`).value, "", `${side}: an Audi's year must never date the host's Golf`)
+  }
+
+  for (const side of ["a", "b"]) {
+    pick(document.querySelector(`#make-${side}`), "audi")
+    await waitFor(() => Array.from(document.querySelector(`#model-${side}`).options).some((option) => option.value === "a3"))
+    pick(document.querySelector(`#model-${side}`), "a3")
+    assert.equal(document.querySelector(`#year-${side}`).value, "2019", `${side}: the intended A3 gets its year`)
+  }
+})
+
+test("malformed spans take the fallback instead of rendering nonsense", async () => {
+  const document = installDOM(`<select id="make"></select><select id="model"></select><select id="year"></select>`)
+  const base = apiBase("year-malformed")
+  const current = new Date().getFullYear()
+  const spans = {
+    ancient: { first: -8000, last: 2026 },
+    zero: { first: 0, last: 0 },
+    future: { first: 2020, last: 2099 },
+    reversed: { first: 2022, last: 2015 },
+    strings: { first: "2010", last: "2020" },
+    // Last on purpose: 1e300 passes Number.isInteger and 1e300 - 1 === 1e300,
+    // so the old countdown never finished.
+    endless: { first: 2020, last: 1e300 }
+  }
+  global.fetch = async (url) => new URL(url).pathname.endsWith("/models")
+    ? jsonResponse({ models: [
+      ...Object.entries(spans).map(([slug, span]) => ({ name: slug, slug, years_on_record: span })),
+      { name: "edges", slug: "edges", years_on_record: { first: 1886, last: current + 1 } }
+    ] })
+    : jsonResponse({ makes: [{ name: "Audi", slug: "audi" }] })
+
+  attach({ key: "year-malformed-key", apiBase: base, make: "#make", model: "#model", year: "#year", attribution: false })
+  await waitFor(() => document.querySelector("#make").options.length === 2)
+  pick(document.querySelector("#make"), "audi")
+  await waitFor(() => document.querySelector("#model").options.length === 8)
+  const year = document.querySelector("#year")
+
+  for (const slug of Object.keys(spans)) {
+    pick(document.querySelector("#model"), slug)
+    assert.equal(year.options.length, 1 + 41, `${slug}: the fallback range, not the payload`)
+    assert.equal(year.options[1].value, String(current))
+  }
+
+  // The widest span the bounds admit stays a bounded list.
+  pick(document.querySelector("#model"), "edges")
+  assert.equal(year.options[1].value, String(current + 1))
+  assert.equal(year.options[year.options.length - 1].value, "1886")
+  assert.ok(year.options.length < 150)
+})
+
+test("a saved year outside the model's span is kept, in its place, and announced", async () => {
+  const document = installDOM(`
+    <select id="make-a"><option value="audi" selected>Audi</option></select>
+    <select id="model-a"><option value="a3" selected>A3</option></select>
+    <select id="year-a"><option value="2024" selected>2024</option></select>
+    <select id="make-b"></select><select id="model-b"></select><select id="year-b"></select>
+  `)
+  const base = apiBase("year-kept")
+  global.fetch = async (url) => new URL(url).pathname.endsWith("/models")
+    ? jsonResponse({ models: [{ name: "A3", slug: "a3", years_on_record: { first: 2015, last: 2022 } }] })
+    : jsonResponse({ makes: [{ name: "Audi", slug: "audi" }] })
+  const warnings = []
+  const originalWarn = console.warn
+  console.warn = (...parts) => warnings.push(parts.join(" "))
+  try {
+    // An edit form: the register span ends in 2022, the customer's car is a 2024.
+    const edit = attach({ key: "year-kept-key", apiBase: base, make: "#make-a", model: "#model-a", year: "#year-a", attribution: false })
+    // A configured initial year older than the span, with Other enabled.
+    attach({
+      key: "year-kept-key", apiBase: base, make: "#make-b", model: "#model-b", year: "#year-b",
+      initialMake: "audi", initialModel: "a3", initialYear: 2010, includeOther: true, attribution: false
+    })
+    await waitFor(() => document.querySelector("#year-a").options.length === 10 && document.querySelector("#year-b").value === "2010")
+
+    assert.deepEqual(optionValues(document.querySelector("#year-a")),
+      ["", "2024", "2022", "2021", "2020", "2019", "2018", "2017", "2016", "2015"])
+    assert.deepEqual(edit.value, { make: "audi", model: "a3", year: 2024 })
+    assert.deepEqual(optionValues(document.querySelector("#year-b")).slice(-3), ["2015", "2010", "other"])
+  } finally {
+    console.warn = originalWarn
+  }
+  assert.equal(warnings.filter((line) => line.includes("2024")).length, 1, "the kept year should be named, once")
+  assert.equal(warnings.filter((line) => line.includes("2010")).length, 1)
+})
+
+test("the host owns disabled; the widget only ever undoes its own", async () => {
+  const document = installDOM(`
+    <select id="make-a"></select><select id="model-a"></select><select id="year-a" disabled></select>
+    <select id="make-b"></select><select id="model-b"></select><select id="year-b"></select>
+    <select id="make-c"></select><select id="model-c"></select><select id="year-c"></select>
+    <select id="make-d"></select><select id="model-d"></select><select id="year-d"></select>
+  `)
+  const base = apiBase("year-disabled")
+  global.fetch = async (url) => new URL(url).pathname.endsWith("/models")
+    ? jsonResponse({ models: [
+      { name: "A1", slug: "a1", years_on_record: { first: 2010, last: 2024 } },
+      { name: "A3", slug: "a3", years_on_record: { first: 2015, last: 2022 } },
+      { name: "Q7", slug: "q7", years_on_record: null }
+    ] })
+    : jsonResponse({ makes: [{ name: "Audi", slug: "audi" }] })
+  const options = (side, extra) => Object.assign({
+    key: "year-disabled-key", apiBase: base, make: `#make-${side}`, model: `#model-${side}`,
+    year: `#year-${side}`, attribution: false
+  }, extra)
+
+  // a: disabled by the host at attach time, enabled by the host after a pick.
+  attach(options("a", { initialMake: "audi", initialModel: "a3", initialYear: 2019 }))
+  // b: enabled at attach time, disabled by the host afterwards.
+  const b = attach(options("b"))
+  // c: disabled by the widget itself ("none", nothing to choose).
+  const c = attach(options("c", { yearFallback: "none" }))
+  // d: "none" with Other enabled — Other is a choice, so the field stays usable.
+  attach(options("d", { yearFallback: "none", includeOther: true }))
+  const year = (side) => document.querySelector(`#year-${side}`)
+
+  await waitFor(() => year("a").value === "2019", "initialYear applies to a host-disabled field")
+  assert.equal(year("a").disabled, true, "the host's disabled is left alone")
+  year("a").disabled = false
+  pick(document.querySelector("#model-a"), "a1")
+  assert.equal(year("a").disabled, false, "a host enable survives the next refill")
+
+  for (const side of ["b", "c", "d"]) pick(document.querySelector(`#make-${side}`), "audi")
+  await waitFor(() => ["b", "c", "d"].every((side) => document.querySelector(`#model-${side}`).options.length >= 4))
+
+  year("b").disabled = true
+  pick(document.querySelector("#model-b"), "a3")
+  assert.equal(year("b").disabled, true, "a host disable survives the next refill")
+  b.destroy()
+  assert.equal(year("b").disabled, true, "destroy never re-enables what the host disabled")
+
+  pick(document.querySelector("#model-c"), "q7")
+  assert.equal(year("c").disabled, true)
+  c.destroy()
+  instances = instances.filter((candidate) => candidate !== b && candidate !== c)
+  assert.equal(year("c").disabled, false, "destroy undoes the widget's own disabling")
+
+  pick(document.querySelector("#model-d"), "q7")
+  assert.deepEqual(optionValues(year("d")), ["", "other"])
+  assert.equal(year("d").disabled, false, "Other must stay choosable")
+})
+
+test("the previous make's models never date a model during the next make's fetch", async () => {
+  const document = installDOM(`<select id="make"></select><select id="model"></select><select id="year"></select>`)
+  const base = apiBase("year-between")
+  global.fetch = async (url) => {
+    if (url.includes("/audi/models")) {
+      return jsonResponse({ models: [{ name: "A3", slug: "a3", years_on_record: { first: 2018, last: 2021 } }] })
+    }
+    if (url.includes("/bmw/models")) return new Promise(() => {}) // still loading
+    return jsonResponse({ makes: [{ name: "Audi", slug: "audi" }, { name: "BMW", slug: "bmw" }] })
+  }
+
+  attach({ key: "year-between-key", apiBase: base, make: "#make", model: "#model", year: "#year", attribution: false })
+  await waitFor(() => document.querySelector("#make").options.length === 3)
+  pick(document.querySelector("#make"), "audi")
+  await waitFor(() => document.querySelector("#model").options.length === 2)
+  pick(document.querySelector("#make"), "bmw")
+
+  // Host code injecting an option mid-fetch (an edit form restoring its
+  // saved model, say) must not be dated from Audi's list.
+  const model = document.querySelector("#model")
+  model.add(new Option("A3", "a3"))
+  pick(model, "a3")
+  assert.equal(document.querySelector("#year").options[1].value, String(new Date().getFullYear()))
+})