@jtakeit/kit 0.6.0 → 0.7.1

package/elements/booking.js

@@ -14,6 +14,8 @@
  *   POST /api/book                  → { id, state, amount_minor, currency, token, manage_path, telegram_url }
  *   POST /api/pay                   → { url } — only when amount_minor > 0
  *
+ * Every request names the protocol version: `X-Jtk-Booking: 1` (BOOKING_PROTOCOL).
+ *
  * The visitor's own page — cancel, move, add to calendar — is served by the
  * platform at `manage_path`; this form only has to link to it.
  *
@@ -22,9 +24,14 @@
  * Import this module once on the page and every `<form data-booking>` is
  * wired: the ones inside a `<jtk-booking>` by the element's own lifecycle,
  * which also covers markup the panel places later (`fl:placed`); the ones
- * written bare by a walk of the document at load. The markup is
- * `renderBookingForm`'s (`@jtakeit/kit/booking`); a hand-written form keeps
- * its `data-*` hooks and input `name`s.
+ * written bare by a walk of the document at load. The markup is the site's —
+ * the scaffold's `BookingForm.astro` written out, or `renderBookingForm`'s
+ * (`@jtakeit/kit/booking`) — and the element finds everything in it by a
+ * `data-*` hook or an input's `name`, never by a class: the list is
+ * `@jtakeit/kit/booking/hooks`. A hook left out is said in the console and
+ * its field is never shown; the CSS the behaviour needs (`[hidden]`, the
+ * steps, the native control under a drawn one) and the ARIA it depends on are
+ * put on the page by the element, so a form restyled from nothing keeps them.
  *
  * ── a stay of several nights ────────────────────────────────────────────────
  *
@@ -47,6 +54,40 @@
 import { money } from '../lib/money.mjs';
 import { wordsFor } from '../lib/booking/words.mjs';
 import { dressBooking } from './booking-ui.js';
+import { lacking } from '../lib/booking/hooks.mjs';
+
+/**
+ * The rules the behaviour cannot work without, whatever the site's own CSS
+ * says — put on the page once, by the element, at the lowest specificity
+ * that still wins where it must. Not a look: every state here is shown and
+ * hidden by the `hidden` attribute, the two steps by `data-stage`, a drawn
+ * control over a native one by `data-replaced`; a form an agent dressed from
+ * nothing lost all three with `booking.css` (12 October 2026). The first two
+ * are `!important`, as `hidden` is: a site's `display: grid` on a piece of
+ * the second step drew it on the first.
+ */
+const BASE = `
+[data-booking] [hidden] { display: none !important; }
+[data-booking][data-unsaid] :is([data-say], [data-say-wait]) { visibility: hidden; }
+:where([data-booking]) :where([data-replaced], .is-replaced, [data-sr], .booking__sr) {
+  position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden;
+  clip-path: inset(50%); white-space: nowrap; border: 0;
+}
+:where([data-booking]) :where([data-replaced], .is-replaced) { opacity: 0; pointer-events: none; }
+[data-booking][data-stage='1'] [data-step='2'], [data-booking][data-stage='2'] [data-step='1'],
+[data-booking][data-stage='done'] [data-step-ui] { display: none !important; }
+:where([data-booking] :focus-visible) { outline: 2px solid currentColor; outline-offset: 2px; }
+`;
+
+function putBase() {
+  if (typeof document === 'undefined' || document.querySelector('style[data-jtk-booking]')) return;
+  const style = document.createElement('style');
+  style.dataset.jtkBooking = '';
+  style.textContent = BASE;
+  // First in <head>, so a site's own rule of the same weight wins.
+  document.head.prepend(style);
+}
+let wiredCount = 0;
 
 // The words that depend on the kind of business, as the platform says them:
 // its availability answer carries the form's, in every language, the site's
@@ -90,10 +131,25 @@ export function lasting(minutes, words) {
  * Wires one form. Idempotent: a form already wired is left alone.
  * @param {HTMLFormElement} form
  */
+/**
+ * The booking protocol's version this element speaks, named on every request
+ * (the platform's wiki/79). A page is a file in a build: when the platform
+ * changes, a site keeps the kit it was built with, and the platform answers it
+ * by this number for as long as a live site speaks it — so it moves only with
+ * a change the platform cannot make by adding, and the platform says which
+ * versions it answers when it refuses one.
+ */
+export const BOOKING_PROTOCOL = 1;
+const SPOKEN = { 'x-jtk-booking': String(BOOKING_PROTOCOL) };
+
 export function wireBooking(form) {
   if (form.dataset.jtkWired === '1') return;
   form.dataset.jtkWired = '1';
 
+  putBase();
+  const missing = lacking(form);
+  if (missing.length > 0) console.error(`booking form: it has no ${missing.join(', ')}, and cannot book without them — the hooks are listed in @jtakeit/kit/booking/hooks`);
+
   /** @type {Record<string, string>} */
   // The form's own words under the page's: a form rendered by an older kit
   // carries none of the newer ones.
@@ -102,8 +158,10 @@ export function wireBooking(form) {
   // once there is one, wins — an owner may switch without a rebuild.
   let daily = form.dataset.scale === 'daily';
   const api = form.dataset.api ?? '/api/';
-  /** @template {HTMLElement} T @param {string} sel @returns {T} */
-  const q = (sel) => /** @type {any} */ (form.querySelector(sel));
+  // A hook the form left out is an element of its kind that is never on the
+  // page: the field it stands for is never shown, and nothing here throws.
+  /** @template {HTMLElement} T @param {string} sel @param {string} [tag] @returns {T} */
+  const q = (sel, tag = 'div') => /** @type {any} */ (form.querySelector(sel) ?? document.createElement(tag));
   const lang = form.dataset.locale ?? 'en';
   const pageLang = () => document.documentElement.lang || 'en';
 
@@ -111,6 +169,12 @@ export function wireBooking(form) {
   const select = /** @type {HTMLSelectElement | null} */ (form.querySelector('select[name=service]'));
   const boxes = /** @type {HTMLInputElement[]} */ ([...form.querySelectorAll('input[type=checkbox][name=service]')]);
   const total = /** @type {HTMLElement | null} */ (form.querySelector('[data-total]'));
+  // A checkbox's row and the service's name in it, by their hooks; the
+  // classes of an older kit's markup where a form has no hooks.
+  /** @param {HTMLInputElement} box */
+  const rowOf = (box) => /** @type {HTMLElement | null} */ (box.closest('[data-service-row], .booking__service, label'));
+  /** @param {Element} row */
+  const nameIn = (row) => /** @type {HTMLElement | null} */ (row.querySelector('[data-service-name], .booking__service-name'));
   const picked = () => (select ? (select.value ? [select.value] : []) : boxes.filter((b) => b.checked).map((b) => b.value));
   function showTotal() {
     if (!total) return;
@@ -126,14 +190,14 @@ export function wireBooking(form) {
     total.hidden = false;
   }
   const resource = /** @type {HTMLSelectElement | null} */ (form.querySelector('[name=resource]'));
-  /** @type {HTMLSelectElement} */ const party = q('[name=party]');
-  /** @type {HTMLSelectElement} */ const quantity = q('[name=quantity]');
+  /** @type {HTMLSelectElement} */ const party = q('[name=party]', 'select');
+  /** @type {HTMLSelectElement} */ const quantity = q('[name=quantity]', 'select');
   /** @type {HTMLElement} */ const quantityField = q('[data-quantity-field]');
-  /** @type {HTMLSelectElement} */ const hours = q('[name=hours]');
+  /** @type {HTMLSelectElement} */ const hours = q('[name=hours]', 'select');
   /** @type {HTMLElement} */ const hoursField = q('[data-hours-field]');
   /** @type {HTMLElement} */ const partyField = q('[data-party-field]');
-  /** @type {HTMLInputElement} */ const day = q('[name=day]');
-  /** @type {HTMLElement | null} */ const ends = q('[data-ends]');
+  /** @type {HTMLInputElement} */ const day = q('[name=day]', 'input');
+  /** @type {HTMLElement | null} */ const ends = form.querySelector('[data-ends]');
   // The day's floor is the browser's today, not the build's: `min` was
   // written when the site was built, and a site built on Friday is read on
   // Saturday (10 October 2026).
@@ -156,11 +220,25 @@ export function wireBooking(form) {
   /** @type {HTMLElement} */ const error = q('[data-booking-error]');
   /** @type {HTMLButtonElement} */ const submit = q('[data-submit]');
   /** @type {HTMLElement} */ const challenge = q('[data-challenge]');
-  /** @type {HTMLInputElement} */ const back = q('[name=back]');
+  /** @type {HTMLInputElement} */ const back = q('[name=back]', 'input');
   /** @type {HTMLElement} */ const backField = q('[data-back-field]');
   /** @type {HTMLElement} */ const lengthHint = q('[data-length]');
   /** @type {HTMLElement} */ const stayTotal = q('[data-stay-total]');
 
+  // The ARIA the behaviour depends on, whatever the copy kept: the hint is
+  // read as it changes, the refusal as it appears, the answer takes the focus
+  // and is read, and a refusal is tied to its fields by the error's id.
+  if (!hint.hasAttribute('aria-live')) hint.setAttribute('aria-live', 'polite');
+  if (!error.getAttribute('role')) error.setAttribute('role', 'alert');
+  if (!error.id) error.id = `jtk-booking-error-${++wiredCount}`;
+  {
+    /** @type {HTMLElement} */ const answerBox = q('[data-done]');
+    if (!answerBox.getAttribute('role')) answerBox.setAttribute('role', 'status');
+    if (!answerBox.hasAttribute('tabindex')) answerBox.tabIndex = -1;
+    const keepSaid = form.querySelector('[data-keep-said]');
+    if (keepSaid && !keepSaid.getAttribute('role')) keepSaid.setAttribute('role', 'status');
+  }
+
   /** @param {Record<string, Record<string, string>>} [all] */
   function hear(all) {
     const mine = all?.[lang] ?? all?.en;
@@ -172,11 +250,15 @@ export function wireBooking(form) {
         el.textContent = words[el.dataset.say ?? ''] ?? el.textContent;
       }
     }
+    unsay();
+  }
+  function unsay() {
     form.classList.remove('booking--unsaid');
+    delete form.dataset.unsaid;
   }
   // Held back at most this long: a platform that is slow to answer is not
   // a reason for a form without a button.
-  setTimeout(() => form.classList.remove('booking--unsaid'), 3000);
+  setTimeout(unsay, 3000);
   {
     const first = select?.options[0]?.value ?? boxes[0]?.value ?? '';
     const from = new Date();
@@ -185,10 +267,11 @@ export function wireBooking(form) {
     to.setDate(to.getDate() + 1);
     if (first) {
       const params = new URLSearchParams({ service: first, from: from.toISOString(), to: to.toISOString() });
-      void fetch(api + 'availability?' + params.toString(), { cache: 'no-store' })
+      void fetch(api + 'availability?' + params.toString(), { cache: 'no-store', headers: SPOKEN })
         .then((r) => (r.ok ? r.json() : {}))
         .then((data) => {
           hear(data.words);
+          hearCombine(data.combine);
           sayEmptyServices(data.empty_services ?? []);
         })
         .catch(() => hear());
@@ -207,6 +290,23 @@ export function wireBooking(form) {
   // sign made up while it is asked (11 October 2026).
   let currency = form.dataset.currency || '';
 
+  // One service or several, as the platform answers it now: the owner flips
+  // `combine` in the panel and a checklist built while it was on keeps to one
+  // choice once it is off, rather than offering two the booking refuses.
+  let single = false;
+  /** @param {unknown} said */
+  function hearCombine(said) {
+    if (typeof said !== 'boolean' || boxes.length === 0) return;
+    single = !said;
+    if (!single) return;
+    let kept = false;
+    for (const box of boxes) {
+      if (box.checked && kept) box.checked = false;
+      if (box.checked) kept = true;
+    }
+    showTotal();
+  }
+
   /** @type {string | null} */ let chosen = null;
   let zone = '';
   let turnstileToken = '';
@@ -223,7 +323,7 @@ export function wireBooking(form) {
 
   // The widget, if this host has one. Asked at runtime so the site carries
   // no key: which widget covers a host is the platform's to decide.
-  void fetch(api + 'turnstile', { cache: 'no-store' })
+  void fetch(api + 'turnstile', { cache: 'no-store', headers: SPOKEN })
     .then((r) => r.json())
     .then((data) => {
       if (!data.sitekey) return;
@@ -294,10 +394,25 @@ export function wireBooking(form) {
   function quantityChosen() {
     return quantityField.hidden ? 1 : Number(quantity.value) || 1;
   }
-  /** @param {string} text */
-  function say(text) {
+  // The fields the last refusal was about: marked invalid and described by
+  // the sentence, so a screen reader reads it on the field itself and not
+  // only as it appears (WCAG 3.3.1, 12 October 2026).
+  /** @type {HTMLElement[]} */ let blamed = [];
+  /** @param {string} text @param {HTMLElement[]} [fields] the fields it is about */
+  function say(text, fields = []) {
     error.textContent = text;
     error.hidden = text === '';
+    for (const field of blamed) {
+      field.removeAttribute('aria-invalid');
+      const rest = (field.getAttribute('aria-describedby') ?? '').split(/\s+/).filter((id) => id && id !== error.id);
+      if (rest.length) field.setAttribute('aria-describedby', rest.join(' '));
+      else field.removeAttribute('aria-describedby');
+    }
+    blamed = text === '' || !error.id ? [] : fields;
+    for (const field of blamed) {
+      field.setAttribute('aria-invalid', 'true');
+      field.setAttribute('aria-describedby', [field.getAttribute('aria-describedby'), error.id].filter(Boolean).join(' '));
+    }
   }
 
   // A refusal as a sentence in the visitor's language. The platform answers
@@ -485,7 +600,7 @@ export function wireBooking(form) {
     const can = who && !who.startsWith('class:') && !who.startsWith('empty:') && does.has(who) ? does.get(who) : null;
     let moved = false;
     for (const box of boxes) {
-      const row = box.closest('.booking__service');
+      const row = rowOf(box);
       const off = can !== null && !can.has(box.value);
       if (off && !box.disabled) {
         box.disabled = true;
@@ -496,12 +611,14 @@ export function wireBooking(form) {
         offByMe.delete(box);
       }
       row?.classList.toggle('is-off', offByMe.has(box));
-      let note = row?.querySelector('.booking__service-off') ?? null;
+      if (row) row.toggleAttribute('data-off', offByMe.has(box));
+      let note = row?.querySelector('[data-service-off], .booking__service-off') ?? null;
       if (offByMe.has(box) && row) {
-        const nameEl = row.querySelector('.booking__service-name');
+        const nameEl = nameIn(row);
         if (!note && nameEl) {
           note = document.createElement('span');
           note.className = 'booking__service-off';
+          note.setAttribute('data-service-off', '');
           nameEl.insertAdjacentElement('afterend', note);
         }
         if (note) note.textContent = words.notWith.replace('{who}', name.split(' ')[0] || name);
@@ -550,7 +667,8 @@ export function wireBooking(form) {
       const box = boxes.find((b) => b.value === one.slug);
       if (box && !box.disabled) {
         box.disabled = true;
-        const name = box.closest('.booking__service')?.querySelector('.booking__service-name');
+        const row = rowOf(box);
+        const name = row ? nameIn(row) : null;
         if (name) name.textContent = said;
         if (box.checked) { box.checked = false; showTotal(); moved = true; }
       }
@@ -579,6 +697,7 @@ export function wireBooking(form) {
       return;
     }
     hint.textContent = '…';
+    slots.setAttribute('aria-busy', 'true');
 
     const from = new Date(day.value + 'T00:00:00');
     const to = new Date(from);
@@ -596,11 +715,12 @@ export function wireBooking(form) {
     if (n !== null) params.set('count', String(n));
 
     try {
-      const answer = await fetch(api + 'availability?' + params.toString(), { cache: 'no-store' });
+      const answer = await fetch(api + 'availability?' + params.toString(), { cache: 'no-store', headers: SPOKEN }).finally(() => slots.removeAttribute('aria-busy'));
       if (!answer.ok) throw new Error(await answer.text());
       if (mine !== asking) return;
       const data = await answer.json();
       hear(data.words);
+      hearCombine(data.combine);
       lastClasses = data.classes ?? [];
       lastResources = data.resources ?? [];
       offerChoices(lastClasses, lastResources, data.empty_classes ?? []);
@@ -646,6 +766,7 @@ export function wireBooking(form) {
         const button = document.createElement('button');
         button.type = 'button';
         button.className = 'booking__slot';
+        button.dataset.slot = '';
         // Which one is chosen, said as well as drawn.
         button.setAttribute('aria-pressed', 'false');
         button.textContent = daily
@@ -660,7 +781,7 @@ export function wireBooking(form) {
           if (hint.textContent === words.retime) hint.textContent = '';
           sayEnds(slot);
           offerQuantity(data.quantity_max ?? 1, (slot.free ?? []).length);
-          for (const other of slots.querySelectorAll('.booking__slot')) {
+          for (const other of slots.querySelectorAll('[data-slot]')) {
             other.classList.remove('is-chosen');
             other.setAttribute('aria-pressed', 'false');
           }
@@ -705,7 +826,13 @@ export function wireBooking(form) {
   // The look — the steps, the week, the parts of the day, the drawn choice
   // — over the form, where the form asks for it.
   if (form.dataset.ui) dressBooking(form, words);
-  for (const box of boxes) box.addEventListener('change', () => { showTotal(); void load(); });
+  for (const box of boxes) {
+    box.addEventListener('change', () => {
+      if (single && box.checked) for (const other of boxes) if (other !== box) other.checked = false;
+      showTotal();
+      void load();
+    });
+  }
   resource?.addEventListener('change', () => { greyByResource(); void load(); });
   greyByResource();
   // A new first date keeps the stay's length: five nights from the 10th
@@ -729,8 +856,14 @@ export function wireBooking(form) {
     const email = String(data.get('email') ?? '').trim();
     if (picked().length === 0) { say(words.pickService); return; }
     if (!chosen) { say(words.pick); return; }
-    if (name === '') { /** @type {HTMLInputElement} */ (q('[name=name]')).focus(); return; }
-    if (phone === '' && email === '') { say(words.needContact); return; }
+    /** @type {HTMLInputElement} */ const nameInput = q('[name=name]');
+    if (name === '') { say(words.needName, [nameInput]); nameInput.focus(); return; }
+    if (phone === '' && email === '') {
+      /** @type {HTMLInputElement} */ const phoneInput = q('[name=phone]');
+      say(words.needContact, [phoneInput, q('[name=email]')]);
+      phoneInput.focus();
+      return;
+    }
 
     submit.disabled = true;
     submit.textContent = words.sending;
@@ -763,7 +896,7 @@ export function wireBooking(form) {
       }
       const answer = await fetch(api + 'book', {
         method: 'POST',
-        headers: { 'content-type': 'application/json' },
+        headers: { 'content-type': 'application/json', ...SPOKEN },
         body: JSON.stringify(body),
       });
       if (answer.status === 409) { say(words.taken); await load(); return; }
@@ -783,7 +916,11 @@ export function wireBooking(form) {
    * @param {{ state: string; start: string; ends: string; amount_minor: number; currency: string; id: string; manage_path: string; telegram_url: string; resource?: string; class?: string; group?: { quantity: number; amount_minor: number; bookings: { resource: string; resource_name?: string }[] } }} made
    */
   function done(made) {
-    for (const el of /** @type {NodeListOf<HTMLElement>} */ (form.querySelectorAll('.field, .booking__times, .booking__services, [data-submit], [data-challenge]'))) el.hidden = true;
+    // Everything that asks, gone; the answer stays. By the hooks — the
+    // classes are an older kit's markup.
+    for (const el of /** @type {NodeListOf<HTMLElement>} */ (form.querySelectorAll('[data-field], [data-times], [data-services], [data-submit], [data-challenge], .field, .booking__times, .booking__services'))) {
+      if (!el.contains(form.querySelector('[data-done]'))) el.hidden = true;
+    }
     /** @type {HTMLElement} */ const box = q('[data-done]');
     box.hidden = false;
     // After the lines are written below — see the end of this function.
@@ -824,10 +961,14 @@ export function wireBooking(form) {
       link.setAttribute('aria-label', words.manage);
       link.addEventListener('focus', () => link.select());
       copy.textContent = words.copy;
+      /** @type {HTMLElement | null} */ const told = q('[data-keep-said]');
       copy.addEventListener('click', async () => {
         try { await navigator.clipboard.writeText(href); } catch { link.select(); document.execCommand('copy'); }
         copy.textContent = words.copied;
-        setTimeout(() => { copy.textContent = words.copy; }, 1600);
+        // Said as well as drawn: a button's own words changing under the
+        // focus is read by some screen readers and not by others.
+        if (told) told.textContent = words.copied;
+        setTimeout(() => { copy.textContent = words.copy; if (told) told.textContent = ''; }, 1600);
       });
       open.href = href;
       open.textContent = words.open;
@@ -851,7 +992,7 @@ export function wireBooking(form) {
         event.preventDefault();
         const answer = await fetch(api + 'pay', {
           method: 'POST',
-          headers: { 'content-type': 'application/json' },
+          headers: { 'content-type': 'application/json', ...SPOKEN },
           body: JSON.stringify({ booking: made.id, return: made.manage_path || '/' }),
         });
         if (!answer.ok) { say(await reason(answer)); return; }

package/elements/lead.js

@@ -27,18 +27,39 @@ export function wireLead(form) {
   if (!status || !button) return;
   const original = label?.textContent ?? '';
 
+  /*
+   * A sentence about a field is said on the field (WCAG 3.3.1): the input is
+   * marked invalid and described by the sentence, so a screen reader reads
+   * it when the field is reached and not only when it appears. It was drawn
+   * under the field and tied to nothing (12 October 2026).
+   */
+  /** @param {string} field */
+  const inputOf = (field) => /** @type {HTMLInputElement | null} */ (form.elements.namedItem(field));
+
   /** @param {string} field @param {string} message */
   const showError = (field, message) => {
     /** @type {HTMLElement | null} */ const el = form.querySelector(`[data-error-for="${field}"]`);
     if (!el) return;
     el.textContent = message;
     el.hidden = !message;
+    const input = inputOf(field);
+    if (!input || !message) return;
+    if (!el.id) el.id = `${form.id || 'lead'}-${field}-error`;
+    input.setAttribute('aria-invalid', 'true');
+    const described = (input.getAttribute('aria-describedby') ?? '').split(/\s+/).filter(Boolean);
+    if (!described.includes(el.id)) input.setAttribute('aria-describedby', [...described, el.id].join(' '));
   };
 
   const clearErrors = () => {
     for (const el of /** @type {NodeListOf<HTMLElement>} */ (form.querySelectorAll('[data-error-for]'))) {
       el.textContent = '';
       el.hidden = true;
+      const input = inputOf(el.dataset.errorFor ?? '');
+      if (!input) continue;
+      input.removeAttribute('aria-invalid');
+      const rest = (input.getAttribute('aria-describedby') ?? '').split(/\s+/).filter((id) => id && id !== el.id);
+      if (rest.length) input.setAttribute('aria-describedby', rest.join(' '));
+      else input.removeAttribute('aria-describedby');
     }
   };
 
@@ -49,15 +70,16 @@ export function wireLead(form) {
     form.removeAttribute('data-state');
 
     const data = new FormData(form);
-    let ok = true;
+    /** @type {HTMLInputElement | null} */ let first = null;
     for (const field of ['name', 'contact']) {
-      const input = /** @type {HTMLInputElement | null} */ (form.elements.namedItem(field));
+      const input = inputOf(field);
       if (!input?.value.trim()) {
         showError(field, input?.dataset.message ?? '');
-        ok = false;
+        first ??= input;
       }
     }
-    if (!ok) return;
+    // And the visitor is taken to the first thing to fix (3.3.1).
+    if (first) { first.focus(); return; }
 
     button.disabled = true;
     if (label) label.textContent = form.dataset.sending ?? original;

package/elements/writing.js

@@ -14,15 +14,27 @@
  *
  * Collapsed, it is a pill with the phase; a press opens it; the choice is
  * remembered in this browser.
+ *
+ * ── the stage, while the page has no words ──────────────────────────────────
+ *
+ * A scaffold just laid out is a page of empty fields and asterisks, and a
+ * developer who opens localhost to watch the agent saw that and nothing else
+ * (13 October 2026). So while the page being looked at has not one word in it
+ * yet, the element covers it with a stage: a page assembling itself, what the
+ * agent is on, what is left, the panel's steps meanwhile, and the promise that
+ * the page will appear here by itself. The moment the page has its first
+ * words, the stage goes and the page is loaded again — nobody presses
+ * anything. A page the files do not know (a listing, an entry) is never
+ * covered, nor is any page when the dev server cannot be read.
  */
-import { PHASES, PHASE_NAMES, phasesOf, sayPhase, meanwhile } from '../lib/phases.mjs';
+import { PHASES, PHASE_NAMES, phasesOf, sayPhase, meanwhile, blankHere } from '../lib/phases.mjs';
 
 const STORE = 'jtk-writing:collapsed';
 
 const CSS = `
 :host{position:fixed;right:16px;bottom:16px;z-index:2147483000;font:13px/1.45 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;-webkit-font-smoothing:antialiased;
-  --bg:#fbfaf7;--ink:#1d1b17;--ink2:#3f3b33;--muted:#6b665c;--faint:#9b958a;--line:#e6e1d6;--line2:#d8d2c4;--ok:#2f7d5a;--attn:#9a6b1c;--shadow:0 12px 36px rgba(30,25,15,.16),0 2px 6px rgba(30,25,15,.08)}
-@media (prefers-color-scheme:dark){:host{--bg:#1c1b18;--ink:#f1ede5;--ink2:#d9d3c7;--muted:#a8a295;--faint:#716c62;--line:#33302a;--line2:#443f36;--ok:#5bb38a;--attn:#d4a24a;--shadow:0 12px 36px rgba(0,0,0,.5)}}
+  --paper:#f4f1ea;--glow:rgba(212,162,74,.16);--bg:#fbfaf7;--ink:#1d1b17;--ink2:#3f3b33;--muted:#6b665c;--faint:#9b958a;--line:#e6e1d6;--line2:#d8d2c4;--ok:#2f7d5a;--attn:#9a6b1c;--shadow:0 12px 36px rgba(30,25,15,.16),0 2px 6px rgba(30,25,15,.08)}
+@media (prefers-color-scheme:dark){:host{--paper:#141311;--glow:rgba(212,162,74,.12);--bg:#1c1b18;--ink:#f1ede5;--ink2:#d9d3c7;--muted:#a8a295;--faint:#716c62;--line:#33302a;--line2:#443f36;--ok:#5bb38a;--attn:#d4a24a;--shadow:0 12px 36px rgba(0,0,0,.5)}}
 *{box-sizing:border-box;margin:0;padding:0}
 button{font:inherit;color:inherit;background:none;border:0;cursor:pointer}
 a{color:var(--ink);text-decoration:underline;text-decoration-color:var(--line2);text-underline-offset:3px}
@@ -41,7 +53,9 @@ a:hover{text-decoration-color:var(--ink)}
 .seg.done,.mini i.done{background:var(--ok)}.seg.current,.mini i.current{background:var(--attn)}.seg.current{animation:pulse 2.4s ease-in-out infinite}
 .seg.unseen{background:transparent;border:1px solid var(--line2)}
 @keyframes pulse{50%{opacity:.45}}@media (prefers-reduced-motion:reduce){.seg.current,.card.enter{animation:none}}
-.names{display:flex;gap:4px;margin-top:6px}.names span{flex:1;min-width:0;font-size:10px;color:var(--faint);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.names .current{color:var(--ink);font-weight:600}.names .done{color:var(--muted)}
+/* One line under the strip: the phase it is in, whole, and the one after —
+   seven names in 340 px were seven ellipses (13 October 2026). */
+.names{display:flex;gap:8px;align-items:baseline;margin-top:7px;font-size:12px}.names .current{color:var(--ink);font-weight:600}.names .next{color:var(--faint)}
 .say{display:flex;gap:9px;align-items:flex-start;margin-top:12px;font-weight:600;font-size:13.5px;line-height:1.35}.say i{flex:none;width:8px;height:8px;border-radius:999px;background:var(--attn);margin-top:5px}
 .todo{list-style:none;margin:6px 0 0 17px;color:var(--muted);font-size:12.5px}.todo li+li{margin-top:2px}
 .rule{height:1px;background:var(--line);margin:12px 0 10px}
@@ -54,6 +68,35 @@ a:hover{text-decoration-color:var(--ink)}
 .foot{margin-top:10px;color:var(--faint);font-size:11px}
 `;
 
+const STAGE_CSS = `
+.stage{position:fixed;inset:0;z-index:2147482999;display:grid;place-items:center;overflow:auto;padding:32px 20px;
+  background:radial-gradient(1200px 600px at 50% -10%,var(--glow),transparent 60%),var(--paper);color:var(--ink);
+  font:15px/1.5 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;animation:fade .4s ease both}
+.stage.leaving{animation:out .35s ease both}
+@keyframes fade{from{opacity:0}to{opacity:1}}@keyframes out{to{opacity:0}}
+.wrap{width:min(560px,100%);display:grid;gap:22px}
+.sheet{position:relative;height:210px;border-radius:18px;background:var(--bg);border:1px solid var(--line);box-shadow:var(--shadow);overflow:hidden;padding:18px}
+.bar{height:10px;width:34%;border-radius:999px}
+.row{display:flex;gap:8px;margin-top:22px}.row b{display:block;height:9px;border-radius:999px}
+.hero{height:46px;width:72%;border-radius:12px;margin-top:18px}
+.cards{display:grid;grid-template-columns:repeat(3,1fr);gap:10px;margin-top:18px}.cards b{display:block;height:46px;border-radius:10px}
+.sk{background:linear-gradient(90deg,var(--line) 0%,var(--line2) 50%,var(--line) 100%);background-size:200% 100%;animation:shine 1.8s linear infinite;opacity:0;transform:translateY(6px)}
+.sk{animation:shine 1.8s linear infinite,rise .6s cubic-bezier(.22,.61,.36,1) forwards}
+.d1{animation-delay:0s,.1s}.d2{animation-delay:.1s,.35s}.d3{animation-delay:.2s,.6s}.d4{animation-delay:.3s,.85s}.d5{animation-delay:.4s,1.1s}.d6{animation-delay:.5s,1.35s}
+@keyframes shine{to{background-position:-200% 0}}@keyframes rise{to{opacity:1;transform:none}}
+.caret{position:absolute;right:18px;bottom:16px;display:flex;gap:5px}.caret i{width:6px;height:6px;border-radius:999px;background:var(--attn);animation:dot 1.2s ease-in-out infinite}
+.caret i:nth-child(2){animation-delay:.15s}.caret i:nth-child(3){animation-delay:.3s}@keyframes dot{50%{opacity:.25;transform:translateY(-3px)}}
+.kicker{font-size:12px;font-weight:700;letter-spacing:.12em;text-transform:uppercase;color:var(--faint)}
+.big{font-size:clamp(24px,4vw,32px);line-height:1.15;font-weight:650;letter-spacing:-.01em;margin-top:6px}
+.now{display:flex;gap:10px;align-items:flex-start;margin-top:10px;color:var(--ink2)}.now i{flex:none;width:9px;height:9px;border-radius:999px;background:var(--attn);margin-top:7px;animation:pulse 2.4s ease-in-out infinite}
+.promise{color:var(--muted);font-size:14px}
+.right{margin:6px 0 0 19px;color:var(--muted);font-size:13px}
+.stage .strip{margin-top:0}
+.cols{display:grid;grid-template-columns:1fr 1fr;gap:18px}@media (max-width:560px){.cols{grid-template-columns:1fr}}
+.stage .todo{margin:6px 0 0;padding-left:16px;list-style:disc}
+@media (prefers-reduced-motion:reduce){.stage,.stage.leaving,.sk,.caret i,.now i{animation:none!important}.sk{opacity:1;transform:none}}
+`;
+
 const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 
 function ago(iso) {
@@ -90,7 +133,7 @@ class JtkWriting extends HTMLElement {
   connectedCallback() {
     const root = this.attachShadow({ mode: 'open' });
     const style = document.createElement('style');
-    style.textContent = CSS;
+    style.textContent = CSS + STAGE_CSS;
     this.box = document.createElement('div');
     root.append(style, this.box);
     root.addEventListener('click', (event) => {
@@ -128,6 +171,19 @@ class JtkWriting extends HTMLElement {
     const where = phasesOf(progress, half);
     const n = where.index + 1;
 
+    // The stage, while this page has not one word in it (see the top).
+    const blank = !this.failed && blankHere(progress);
+    if (this.wasBlank && !blank && progress !== null) {
+      // Its first words: let the page be the page.
+      this.leave();
+      return;
+    }
+    this.wasBlank = blank;
+    if (blank) {
+      this.stage(where, progress, half);
+      return;
+    }
+
     if (this.collapsed) {
       this.show(`<button class="pill" data-toggle aria-expanded="false" aria-label="Where the site is: phase ${n} of 7">
         <span class="mini">${where.phases.map((p) => `<i class="${p.state}"></i>`).join('')}</span>
@@ -148,15 +204,18 @@ class JtkWriting extends HTMLElement {
         ? `<p class="note">The platform could not be read: ${esc(platform.error)}</p>`
         : `<p class="note">Not connected to the platform yet — in the working tree: <code>npx jtkit session &lt;session_id&gt; &lt;watch_key&gt;</code>, both from the session's answer.</p>`;
 
+    const last = this.state?.lastChange ?? null;
     const foot = [
-      this.failed ? 'the dev server did not answer' : progress?.changedAt ? `read from the files, changed ${ago(progress.changedAt)}` : 'read from the files',
+      this.failed ? 'the dev server did not answer'
+        : last ? `last change: ${last.path.split('/').slice(-2).join('/')} · ${ago(last.at)}`
+        : progress?.changedAt ? `read from the files, changed ${ago(progress.changedAt)}` : 'read from the files',
       half?.until ? `platform through the session until ${until(half.until)}` : '',
     ].filter(Boolean).join(' · ');
 
     this.show(`<section class="card${this.enter ? ' enter' : ''}" aria-label="Where the site is">
       <div class="head"><span class="title">What the agent is doing</span><span class="count">phase ${n} of 7</span><button class="hide" data-toggle aria-label="Collapse">–</button></div>
       <ol class="strip" aria-label="The seven phases">${where.phases.map((p, i) => `<li class="seg ${p.state}" title="${i + 1}. ${PHASE_NAMES[p.key]}"></li>`).join('')}</ol>
-      <div class="names" aria-hidden="true">${where.phases.map((p, i) => `<span class="${p.state}">${i + 1}. ${PHASE_NAMES[p.key]}</span>`).join('')}</div>
+      <p class="names"><span class="current">${n}. ${esc(PHASE_NAMES[where.current] ?? '')}</span>${where.index < 6 ? `<span class="next">next: ${esc(PHASE_NAMES[where.phases[where.index + 1].key])}</span>` : ''}</p>
       <p class="say"><i></i><span>${esc(say)}</span></p>
       ${todo.length > 0 && where.current !== 'preview'
         ? `<ul class="todo">${todo.slice(0, 4).map((line) => `<li>${esc(line)}</li>`).join('')}${todo.length > 4 ? `<li>+ ${todo.length - 4} more — <code>jtkit progress</code></li>` : ''}</ul>`
@@ -169,6 +228,48 @@ class JtkWriting extends HTMLElement {
     </section>`);
   }
 
+  /** The stage over a page with no words yet: what is happening, and that it will appear. */
+  stage(where, progress, half) {
+    const say = sayPhase(where, progress, half);
+    const todo = (progress?.missing ?? []).slice(0, 4);
+    const steps = meanwhile(half);
+    const open = half ? steps.open : [];
+    document.documentElement.style.overflow = 'hidden';
+    this.show(`<section class="stage" role="status" aria-live="polite" aria-label="The site is being written">
+      <div class="wrap">
+        <div class="sheet" aria-hidden="true">
+          <div class="bar sk d1"></div>
+          <div class="hero sk d2"></div>
+          <div class="row"><b class="sk d3" style="width:58%"></b><b class="sk d3" style="width:24%"></b></div>
+          <div class="cards"><b class="sk d4"></b><b class="sk d5"></b><b class="sk d6"></b></div>
+          <div class="caret"><i></i><i></i><i></i></div>
+        </div>
+        <div>
+          <p class="kicker">Phase ${where.index + 1} of 7 · ${esc(PHASE_NAMES[where.current] ?? '')}</p>
+          <h1 class="big">The site is being written</h1>
+          <p class="now"><i></i><span>${esc(say)}</span></p>
+          ${this.state?.lastChange ? `<p class="right">right now: <code>${esc(this.state.lastChange.path)}</code> · ${esc(ago(this.state.lastChange.at))}</p>` : ''}
+        </div>
+        <ol class="strip" aria-hidden="true">${where.phases.map((p) => `<li class="seg ${p.state}"></li>`).join('')}</ol>
+        <div class="cols">
+          ${todo.length > 0 ? `<div><p class="label">Still to do</p><ul class="todo">${todo.map((line) => `<li>${esc(line)}</li>`).join('')}</ul></div>` : ''}
+          ${open.length > 0
+            ? `<div><p class="label">Meanwhile, in the panel</p><ul class="steps">${open.map((s) => `<li><i class="o"></i><span>${esc(s.name)}</span></li>`).join('')}</ul>${half?.panel ? `<a class="panel" href="${esc(half.panel)}" target="_blank" rel="noopener">Open the panel ↗</a>` : ''}</div>`
+            : ''}
+        </div>
+        <p class="promise">This page appears here by itself the moment it has its first words — leave the tab open.</p>
+      </div>
+    </section>`);
+  }
+
+  /** The page has its words: the stage fades and the page is read again. */
+  leave() {
+    this.wasBlank = false;
+    const stage = this.box.querySelector('.stage');
+    stage?.classList.add('leaving');
+    setTimeout(() => location.reload(), stage ? 350 : 0);
+  }
+
   /** Put this on the page, unless it is what is there already. */
   show(html) {
     const key = html.replace(' enter', '');
@@ -176,6 +277,7 @@ class JtkWriting extends HTMLElement {
     this.shown = key;
     this.box.innerHTML = html;
     this.enter = false;
+    if (!html.includes('class="stage"')) document.documentElement.style.removeProperty('overflow');
   }
 }