k0-board 0.4.0 → 0.5.0

package/web/whatsnew.css

@@ -0,0 +1,211 @@
+/* What's New: what changed between the version you had and the one you are running.
+   Colours and fonts live in base.css.
+
+   It is the ChangeLog's twin — a sheet of paper you read top to bottom rather than a board you
+   look at — so it borrows that page's measure, its top bar and its waiting bar deliberately.
+   Two pages that do the same thing should not look like two different products. */
+@import url('/base.css');
+
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--ink);
+  font-family: var(--sans);
+  font-size: 1rem;
+  line-height: 1.55;
+  -webkit-font-smoothing: antialiased;
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+
+/* ── The top bar ─────────────────────────────────────────────────────── */
+.topbar {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  padding: 10px 18px;
+  background: var(--paper);
+  border-bottom: 1px solid var(--line);
+  flex: none;
+  /* Four things in a row, and on a narrow window they wrap rather than squeeze the title out. */
+  flex-wrap: wrap;
+}
+.topbar .home {
+  font: 700 1.2rem/1 var(--mono);
+  letter-spacing: 1px;
+  color: var(--ink);
+  text-decoration: none;
+}
+.topbar .home:hover { color: var(--muted); }
+.topbar h1 {
+  margin: 0;
+  font: 600 1rem/1 var(--sans);
+  color: var(--muted);
+  flex: 1;
+}
+
+/* The language sits next to the levels and has to look like it belongs with them, so it takes
+   the house button: base.css styles buttons, not selects. */
+.topbar select {
+  font: inherit;
+  font-size: .82rem;
+  font-weight: 600;
+  color: var(--muted);
+  border: 1px solid var(--line);
+  background: var(--paper);
+  border-radius: 8px;
+  padding: 5px 9px;
+  cursor: pointer;
+  flex: none;
+}
+.topbar select:hover { background: #fff; border-color: #c9c3b4; }
+
+/* The three levels, as one connected control rather than three loose buttons: they are a scale
+   of how much you want to be told, and exactly one of them is always the answer. */
+.levels { display: flex; flex: none; }
+.levels button {
+  border-radius: 0;
+  border-left-width: 0;
+  padding: 5px 13px;
+  font-size: .82rem;
+  font-weight: 600;
+  color: var(--muted);
+}
+.levels button:first-child { border-left-width: 1px; border-radius: 8px 0 0 8px; }
+.levels button:last-child { border-radius: 0 8px 8px 0; }
+.levels button[aria-checked='true'] {
+  background: var(--ink);
+  border-color: var(--ink);
+  color: var(--paper);
+}
+.levels button[aria-checked='true'] + button { border-left-color: var(--ink); }
+
+/* ── The sheet ───────────────────────────────────────────────────────── */
+.sheet {
+  flex: 1;
+  overflow-y: auto;
+  padding: 30px 18px 80px;
+}
+.sheet > * { max-width: 44rem; margin-inline: auto; }
+
+/* The sentence about the two versions. It is the first thing read and the only thing on the
+   page that is always there, so it carries a little more weight than the prose under it. */
+.span { margin-bottom: 24px; }
+.span p { margin: 0; font-size: 1.08rem; }
+.span .also { margin-top: 5px; font-size: .9rem; color: var(--muted); }
+
+.note {
+  margin: 0;
+  color: var(--muted);
+  font-size: .95rem;
+}
+
+/* ── The page the model wrote ────────────────────────────────────────── */
+.prose > :first-child { margin-top: 0; }
+.prose > :last-child { margin-bottom: 0; }
+.prose h2 { margin: 0 0 14px; font: 700 1.35rem/1.25 var(--sans); }
+.prose h3 { margin: 28px 0 8px; font: 600 1.06rem/1.3 var(--sans); }
+.prose h4 { margin: 20px 0 6px; font: 600 .95rem/1.3 var(--sans); }
+.prose p { margin: 0 0 13px; }
+.prose ul, .prose ol { margin: 0 0 13px; padding-left: 20px; }
+.prose li { margin-bottom: 4px; }
+.prose code {
+  font: .85em var(--mono);
+  background: var(--paper);
+  border: 1px solid var(--line);
+  border-radius: 4px;
+  padding: 1px 5px;
+}
+.prose pre {
+  background: var(--paper);
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  padding: 12px 14px;
+  overflow-x: auto;
+}
+.prose pre code { border: none; padding: 0; background: none; }
+.prose blockquote {
+  margin: 0 0 13px;
+  padding-left: 14px;
+  border-left: 2px solid var(--line);
+  color: var(--muted);
+}
+.prose a { color: inherit; }
+
+/* ── The entries underneath ──────────────────────────────────────────── */
+/* Open while there is nothing else on the page, because a fold you have to click to find
+   something to read is a blank screen with extra steps. */
+.entries {
+  background: var(--paper);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 14px 24px;
+  margin-top: 30px;
+}
+.entries summary {
+  cursor: pointer;
+  font-size: .78rem;
+  color: var(--muted);
+  list-style: none;
+}
+.entries summary::-webkit-details-marker { display: none; }
+.entries summary::before { content: '▸ '; }
+.entries[open] summary::before { content: '▾ '; }
+
+.version { padding-top: 16px; }
+.version + .version {
+  margin-top: 16px;
+  border-top: 1px dashed var(--line);
+}
+.version h3 {
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+  margin: 0;
+  font: 700 1rem/1 var(--mono);
+}
+.version h3 time { font: 400 .78rem/1 var(--sans); color: var(--muted); }
+/* The section names are a filing label, not a heading: small, quiet, and out of the way of the
+   lines, which are the part anybody actually reads. */
+.version h4 {
+  margin: 14px 0 4px;
+  font: 600 .72rem/1 var(--sans);
+  text-transform: uppercase;
+  letter-spacing: .09em;
+  color: var(--muted);
+}
+.version ul { margin: 0; padding-left: 20px; font-size: .92rem; }
+.version li { margin-bottom: 4px; }
+.version .empty { margin: 12px 0 0; font-size: .9rem; color: var(--muted); }
+
+/* ── While the words are being written ───────────────────────────────── */
+.waiting { margin-bottom: 26px; }
+.waiting .bar {
+  height: 3px;
+  background: var(--line);
+  border-radius: 2px;
+  overflow: hidden;
+}
+.waiting .bar i {
+  display: block;
+  height: 100%;
+  width: 32%;
+  border-radius: 2px;
+  background: var(--ink);
+  animation: sweep 1.5s ease-in-out infinite;
+}
+@keyframes sweep {
+  from { transform: translateX(-105%); }
+  to { transform: translateX(420%); }
+}
+/* Handwriting, like the other places where k0 speaks rather than reports. */
+.waiting .phrase {
+  margin: 10px 0 0;
+  font: 600 1.25rem/1 var(--hand);
+  color: var(--muted);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .waiting .bar i { animation: none; width: 100%; opacity: .35; }
+}

package/web/whatsnew.html

@@ -0,0 +1,49 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>k0 — What's New</title>
+  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="stylesheet" href="/whatsnew.css">
+</head>
+<body>
+  <header class="topbar">
+    <a class="home" href="/" title="Back to the dashboard">k0</a>
+    <h1>What's New</h1>
+
+    <!-- Two controls, and both of them change who the page is being written for rather than
+         what is in it. Both send it back to the model, and both are remembered: coming back to
+         this page to find it in a language you do not read is the whole page wasted. -->
+    <select id="lang" aria-label="Language"></select>
+
+    <div class="levels" id="levels" role="radiogroup" aria-label="How technical">
+      <button type="button" role="radio" data-level="plain" aria-checked="false">Plain</button>
+      <button type="button" role="radio" data-level="normal" aria-checked="false">Normal</button>
+      <button type="button" role="radio" data-level="nerd" aria-checked="false">Nerd</button>
+    </div>
+  </header>
+
+  <main class="sheet" id="sheet">
+    <!-- Which two versions this page stands between, said the way you would say it out loud. -->
+    <div class="span" id="span"></div>
+
+    <div class="waiting" id="waiting" hidden>
+      <div class="bar"><i></i></div>
+      <p class="phrase" id="phrase"></p>
+    </div>
+
+    <div class="prose" id="prose"></div>
+    <p class="note" id="note" hidden></p>
+
+    <!-- The changelog itself, on screen from the first moment. While the words are being written
+         it is what there is to read; afterwards it is what you check them against. -->
+    <details class="entries" id="entries" open>
+      <summary>The entries, exactly as they were written</summary>
+      <div class="versions" id="versions"></div>
+    </details>
+  </main>
+
+  <script type="module" src="/whatsnew.js"></script>
+</body>
+</html>

package/web/whatsnew.js

@@ -0,0 +1,339 @@
+import { render } from '/md.js'
+
+// ── What's New ───────────────────────────────────────────────────────────────
+// k0 moved on while you were not looking. This is the page that says what it did — written by
+// your own Claude, in your language, at the level of detail you asked for.
+//
+// It is built the way the ChangeLog page is, and for the same reason: the entries come back
+// from the server at once and are on screen before you have finished reading the heading, while
+// the words take a model half a minute. So there is never a spinner over an empty sheet. At
+// worst this page is a changelog, which is what everybody else ships and what people have been
+// reading for twenty years.
+
+const $ = (s) => document.querySelector(s)
+
+const api = async (url, opts) => {
+  const r = await fetch(url, { headers: { 'content-type': 'application/json' }, ...opts })
+  if (!r.ok) throw new Error((await r.json().catch(() => ({}))).error || r.statusText)
+  return r.json()
+}
+
+const LEVELS = ['plain', 'normal', 'nerd']
+
+// Not a claim about what the model can write — it will write in anything — but a list short
+// enough to pick from without scrolling. Whatever the browser is set to is added to it, so the
+// one language that matters to the person reading is never the missing one.
+const LANGS = ['en', 'it', 'es', 'fr', 'de', 'pt', 'nl', 'pl', 'sv', 'ru', 'tr', 'ja', 'zh']
+
+// Keep a Changelog's order, which is the order a changelog is read in everywhere. A section
+// under some other heading is kept and shown after these rather than dropped: somebody wrote it.
+const SECTIONS = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']
+
+// Something to read while the model reads. They say what is actually going on, which is the
+// only reason a waiting message is ever worth having.
+const PHRASES = [
+  'Reading the changelog…',
+  'Working out what you will actually notice…',
+  'Putting the lines that are about one thing together…',
+  'Leaving out what changed nothing for you…',
+  'Putting it in your own words…',
+]
+
+let facts = null
+let poll = null
+let phrases = null
+let quiet = 0 // rounds in a row with no job running and nothing written
+let touched = false // the reader opened or closed the entries by hand
+
+// Bumped every time the controls change. A reply to the question before this one is thrown
+// away: it is a whole page in the wrong language, and it would arrive looking authoritative.
+let asking = 0
+
+// ── What was asked for ───────────────────────────────────────────────────────
+const clean = (tag) => (/^[a-z]{2,3}$/.test(String(tag || '').toLowerCase()) ? String(tag).toLowerCase() : '')
+
+let lang = clean(localStorage.getItem('k0-whatsnew-lang')) || clean((navigator.language || '').split('-')[0]) || 'en'
+let level = LEVELS.includes(localStorage.getItem('k0-whatsnew-level'))
+  ? localStorage.getItem('k0-whatsnew-level')
+  : 'normal'
+
+/**
+ * The pair goes on the query string of the POST as well as in its body, and on the GET too,
+ * because the writer keeps one job per key: the page has to say which job it is asking about on
+ * the way in and on the way back, or a language switched mid-run polls the old run and paints
+ * its answer.
+ */
+// `from` is the version the page is actually showing, sent back rather than left to the server to
+// work out a second time. Marking the page read moves the mark the server would compute it from,
+// and without this a language chosen after that would be answered with a summary of a shorter span
+// than the entries printed underneath it.
+const writeUrl = () =>
+  `/api/whatsnew/write?lang=${encodeURIComponent(lang)}&level=${encodeURIComponent(level)}` +
+  `&from=${encodeURIComponent(facts?.from ?? '')}`
+
+function fillLangs() {
+  const names = new Intl.DisplayNames(['en'], { type: 'language', fallback: 'code' })
+  const sel = $('#lang')
+  for (const tag of LANGS.includes(lang) ? LANGS : [lang, ...LANGS]) {
+    const o = document.createElement('option')
+    o.value = tag
+    o.textContent = names.of(tag)
+    sel.append(o)
+  }
+  sel.value = lang
+}
+
+function markLevel() {
+  for (const b of document.querySelectorAll('#levels button')) {
+    b.setAttribute('aria-checked', String(b.dataset.level === level))
+  }
+}
+
+// ── Painting ─────────────────────────────────────────────────────────────────
+/**
+ * A date written `2026-09-02` goes through the Date constructor as midnight UTC, which prints as
+ * the day before in every timezone behind Greenwich. The three numbers are pulled out by hand
+ * instead, and a date in any other shape is shown exactly as it arrived.
+ */
+function niceDate(iso) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(String(iso || ''))
+  if (!m) return String(iso || '')
+  return new Date(+m[1], +m[2] - 1, +m[3]).toLocaleDateString(undefined, {
+    day: 'numeric',
+    month: 'long',
+    year: 'numeric',
+  })
+}
+
+/** The two versions as a sentence. A page that opens on `0.3.1 → 0.4.0` is a diff, not a page. */
+function spanLine(d) {
+  const n = d.entries?.length || 0
+  if (!d.to) return 'k0 does not know which version it is running.'
+  if (!d.from) return `You are running k0 ${d.to}. There is no earlier version to hold it against yet.`
+  if (d.from === d.to) return `You are still on k0 ${d.to}, the version you had the last time you looked.`
+  const later = n > 1 ? `, ${n} versions later` : ''
+  return `You had k0 ${d.from}. You are running ${d.to} now${later}.`
+}
+
+function paintSpan(d) {
+  const box = $('#span')
+  box.textContent = ''
+  const p = document.createElement('p')
+  p.textContent = spanLine(d)
+  box.append(p)
+  // Only when the server has said so: this page is also reached from the mark that appears when
+  // npm has something newer, and in that case the two versions on their own explain nothing.
+  if (d.latest && d.latest !== d.to) {
+    const also = document.createElement('p')
+    also.className = 'also'
+    also.textContent = `npm has ${d.latest}, which is newer than what is installed here.`
+    box.append(also)
+  }
+  if (d.to) document.title = `k0 — What's New in ${d.to}`
+}
+
+function versionBlock(e) {
+  const art = document.createElement('article')
+  art.className = 'version'
+
+  const h = document.createElement('h3')
+  h.textContent = e.version || ''
+  if (e.date) {
+    const t = document.createElement('time')
+    t.textContent = niceDate(e.date)
+    h.append(t)
+  }
+  art.append(h)
+
+  const sections = e.sections || {}
+  const has = (name) => Array.isArray(sections[name]) && sections[name].length
+  const names = [...SECTIONS.filter(has), ...Object.keys(sections).filter((s) => !SECTIONS.includes(s) && has(s))]
+
+  if (!names.length) {
+    const p = document.createElement('p')
+    p.className = 'empty'
+    p.textContent = 'Nothing written down under this version.'
+    art.append(p)
+    return art
+  }
+
+  for (const name of names) {
+    const h4 = document.createElement('h4')
+    h4.textContent = name
+    const ul = document.createElement('ul')
+    for (const line of sections[name]) {
+      const li = document.createElement('li')
+      li.textContent = line // a changelog line is a line, not markup: it goes in as it was typed
+      ul.append(li)
+    }
+    art.append(h4, ul)
+  }
+  return art
+}
+
+function paintEntries(d) {
+  const box = $('#versions')
+  box.textContent = ''
+  for (const e of d.entries || []) box.append(versionBlock(e))
+  $('#entries').hidden = !(d.entries || []).length
+}
+
+function paintProse(text) {
+  const box = $('#prose')
+  box.textContent = ''
+  if (!text) return
+  box.innerHTML = render(text)
+  // The entries were what there was to read while the waiting went on; now there is a page, so
+  // they step back and become the thing you check it against. Unless they were opened or closed
+  // by hand, in which case that stands — nothing moves under the reader's own decision.
+  if (!touched) $('#entries').open = false
+}
+
+function note(message) {
+  const p = $('#note')
+  p.textContent = message
+  p.hidden = !message
+}
+
+// ── Waiting ──────────────────────────────────────────────────────────────────
+function waiting(on) {
+  $('#waiting').hidden = !on
+  clearInterval(phrases)
+  if (!on) return
+  let i = 0
+  $('#phrase').textContent = PHRASES[0]
+  phrases = setInterval(() => {
+    i = (i + 1) % PHRASES.length
+    $('#phrase').textContent = PHRASES[i]
+  }, 2600)
+}
+
+function stop() {
+  clearInterval(poll)
+  poll = null
+  waiting(false)
+}
+
+/** True once there is nothing left to wait for. */
+function arrived(state) {
+  if (state.text) {
+    stop()
+    paintProse(state.text)
+    return true
+  }
+  if (state.error) {
+    stop()
+    note(state.error)
+    return true
+  }
+  if (state.running) {
+    quiet = 0
+    return false
+  }
+  // Nothing running, nothing written and nothing gone wrong: the job died on its way out and
+  // nobody is coming back with a page. Two rounds of that and this stops asking, because the
+  // alternative is a bar that sweeps until the tab is closed.
+  quiet += 1
+  if (quiet < 2) return false
+  stop()
+  note('The writing stopped before it got anywhere. The entries are below, as they were written.')
+  return true
+}
+
+async function writeUp() {
+  const mine = ++asking
+  quiet = 0
+  note('')
+  paintProse('')
+  waiting(true)
+
+  try {
+    const started = await api(writeUrl(), { method: 'POST', body: JSON.stringify({ lang, level }) })
+    if (mine !== asking) return
+    if (arrived(started)) return
+  } catch (err) {
+    if (mine !== asking) return
+    stop()
+    note(String(err.message || err))
+    return
+  }
+
+  poll = setInterval(async () => {
+    if (mine !== asking) return
+    try {
+      const state = await api(writeUrl())
+      if (mine === asking) arrived(state)
+    } catch {
+      /* the server is restarting: the next round will find it */
+    }
+  }, 1000)
+}
+
+// ── Loading ──────────────────────────────────────────────────────────────────
+
+/**
+ * The mark on the board goes out, and this is the only thing that puts it out.
+ *
+ * Here rather than on the way out of the tab: closing a tab is not the same as having read what
+ * was in it, and the server's own comment says so. It goes after the entries are painted, because
+ * by then what changed is on the screen — the write-up says it better, but the entries are the
+ * substance and they are already readable. Nothing waits for this and nothing depends on it: a
+ * page that could not tell the server it had been read is still a page that was read.
+ */
+const markSeen = () => api('/api/whatsnew/seen', { method: 'POST' }).catch(() => {})
+
+async function load() {
+  stop()
+  try {
+    facts = await api('/api/whatsnew')
+  } catch (err) {
+    note(String(err.message || err))
+    return
+  }
+
+  paintSpan(facts)
+  paintEntries(facts)
+  markSeen()
+
+  if (!(facts.entries || []).length) {
+    // Nothing to summarise. Saying so costs a line; asking a model to say so costs half a minute
+    // and comes back with the same line.
+    note('Nothing changed between the two versions.')
+    return
+  }
+  if (!facts.writer?.can) {
+    note(`${facts.writer?.why || 'Claude Code is not on this machine.'} The entries are below, as they were written.`)
+    return
+  }
+  writeUp()
+}
+
+/** A control moved: the same facts, the same page, asked for again. */
+function again() {
+  if (!facts || !(facts.entries || []).length || !facts.writer?.can) return
+  stop()
+  writeUp()
+}
+
+$('#levels').onclick = (e) => {
+  const b = e.target.closest('button[data-level]')
+  if (!b || b.dataset.level === level) return
+  level = b.dataset.level
+  localStorage.setItem('k0-whatsnew-level', level)
+  markLevel()
+  again()
+}
+
+$('#lang').onchange = () => {
+  lang = $('#lang').value
+  localStorage.setItem('k0-whatsnew-lang', lang)
+  again()
+}
+
+$('#entries').querySelector('summary').onclick = () => {
+  touched = true
+}
+
+fillLangs()
+markLevel()
+load()