feat(page): logbook design

docs/design.md

@@ -0,0 +1,88 @@
+# Design
+
+firsthour is a logbook: roles are entries stamped by age, and the page exists to show what arrived since you last looked.
+
+All values live in one token block at the top of `public/style.css`. `test/style.test.ts` fails on any color or length outside it.
+
+## Type
+
+One family: [Recursive](https://github.com/arrowtype/recursive), self-hosted at `public/fonts/recursive.woff2` (latin, `wght` + `MONO` axes, 73 KB, OFL in `recursive-OFL.txt`). No font is loaded from another origin.
+
+| Token | Use |
+|---|---|
+| `--axes-text` (`MONO` 0) | company, role, body |
+| `--axes-mono` (`MONO` 1) | age, source, status, counts, brand, group headers |
+| `--size-body` 15 px | rows; the floor for text a reader acts on |
+| `--size-meta` 13 px | status, source, footer |
+| `--weight-strong` 640 | company, new age, group headers |
+
+`CASL` stays 0: the face reads linear, not casual.
+
+The CSP needs `font-src 'self'`. Without it, `default-src 'none'` blocks the font, and the only report is a console message. `scripts/probe.mjs` checks the header and the font URL on a live Worker.
+
+## Color
+
+Each color is written once as `light-dark(light, dark)`. The system theme picks a side; `data-theme` on `<html>` pins it.
+
+| Token | Light | Dark | Role | Contrast on paper (light / dark) |
+|---|---|---|---|---|
+| `--paper` | `#e1edf0` | `#051a1d` | page | |
+| `--ink` | `#14202b` | `#cde3e0` | text, rows not read yet | 13.8 / 13.4 |
+| `--ink-2` | `#45545e` | `#8fabab` | read rows, meta | 6.6 / 7.3 |
+| `--signal` | `#0a6b4c` | `#5fd3a5` | new rows, First hour, focus | 5.5 / 9.7 |
+| `--alert` | `#a3261b` | `#ff8f80` | failed sources, stale banner | 6.2 / 8.1 |
+| `--rule-strong` | = ink | = ink | masthead, group rules, input | |
+| `--rule` | `#c3d5d9` | `#17393c` | row dividers (decorative) | |
+
+Every text token reads at 4.5:1 or better on paper in both themes, and the test pins it. Read rows use `--ink-2`, so dimming never drops below that floor.
+
+The palette is cool on purpose: sift, the sibling HN reader, is warm cream. No firsthour token sits within ΔE 5 (CIE76) of a sift token.
+
+## Rows
+
+```
+desktop   age │ company │ role, then who may apply                    │ source
+mobile    age │ company                                               │ source
+                role
+```
+
+Age leads, in mono with tabular figures: `12m`, `3h`, `2d`. Company and role come from the title's `Company | Role | …` convention (`parts` in `public/lib.js`); URLs are dropped from display because the link is built from a validated id, and HN job stories have no company part. The source is one word: `HN`, `HN jobs`, `board`. The filter matches company and role only.
+
+Rows wrap; they never truncate. In HN titles the restriction ("US only", "visa possible") usually comes last, which is what an ellipsis would hide. Titles are capped at 160 characters upstream. Touch screens get rows of at least 44 px; mouse rows stay dense.
+
+## New and read
+
+| Row | Means |
+|---|---|
+| signal tick, signal age | **new**: arrived since your last visit (it was not listed then) |
+| full ink | not read yet: never on screen in an earlier visit |
+| `--ink-2` | read |
+
+- A row is read once most of it has been on screen (IntersectionObserver, 60 %). Rows you never scrolled to keep full ink, though they lose the tick once they have been listed.
+- The count line opens with the same tick, as the key: "12 new since Thu, Oct 8, 11:45 AM". It counts arrivals only.
+- A first visit has no baseline: no ticks, nothing dimmed.
+- A record from before reading was tracked loads as all read.
+- Screen readers get the word "new", which is visually hidden.
+- First hour is the only group header in signal color: it is the event the page is named for.
+
+## Theme
+
+`auto` / `light` / `dark` sits in the masthead. `public/theme.js` is a classic script placed before the stylesheet, so the first paint uses the stored choice. Storage failure means auto.
+
+`light-dark()` has been Baseline since May 2024. In an older browser the color tokens are invalid, and the page falls back to default black on the canvas: readable, without the palette.
+
+## Rules
+
+- Tokens only: a new value is a new token.
+- Rows wrap; text is never truncated.
+- Calm: a finite list with an end. No badges, no counters beyond the new count and the filter's "N of M", no animation.
+- Untrusted text is rendered with `textContent` only.
+
+What this design avoids:
+- cream paper;
+- small uppercase tracked labels;
+- a grey meta line above every title;
+- an amber accent;
+- the system font stack;
+- rounded cards;
+- palette values copied from a framework.

public/app.js

@@ -1,5 +1,5 @@
 // @ts-check
-import { age, allDown, group, isActive, isNew, loadSeen, matches, nextSeen, parseFilter, saveSeen, statusText } from './lib.js';
+import { age, allDown, group, isActive, isNew, isRead, loadSeen, loadTheme, matches, nextSeen, parseFilter, parts, saveSeen, saveTheme, sourceLabel, statusText } from './lib.js';
 
 /** @typedef {import('./lib.js').Posts} Posts */
 
@@ -26,6 +26,19 @@ const seen = loadSeen(storage());
 let posts = null;
 /** @type {string[]} */
 let shown = [];
+/** Ids whose row was on screen during this visit. @type {Set<string>} */
+const viewed = new Set();
+const onScreen = new IntersectionObserver(
+  (entries) => {
+    for (const entry of entries) {
+      const id = entry.target instanceof HTMLElement ? entry.target.dataset.id : undefined;
+      if (!entry.isIntersecting || !id) continue;
+      viewed.add(id);
+      onScreen.unobserve(entry.target);
+    }
+  },
+  { threshold: 0.6 },
+);
 
 /**
  * @param {string} tag
@@ -67,12 +80,10 @@ function render() {
   renderStatus(posts);
 
   const fresh = visible.filter((item) => isNew(item, seen)).length;
-  count.textContent = [
-    isActive(filter) ? `${visible.length} of ${posts.items.length}` : '',
-    seen && fresh > 0 ? `${fresh} new since ${dateTimeFmt.format(new Date(seen.at))}` : '',
-  ]
-    .filter(Boolean)
-    .join(' · ');
+  count.replaceChildren(
+    ...(isActive(filter) ? [el('span', { text: `${visible.length} of ${posts.items.length}` })] : []),
+    ...(seen && fresh > 0 ? [el('span', { class: 'new-count', text: `${fresh} new since ${dateTimeFmt.format(new Date(seen.at))}` })] : []),
+  );
 
   if (allDown(posts)) {
     list.replaceChildren(el('p', { class: 'empty', text: 'Every source is unavailable right now.' }), retryButton());
@@ -96,29 +107,32 @@ function render() {
   list.replaceChildren(
     ...(groups[0]?.label === 'First hour' ? [] : [nextThreadLine(posts)]),
     ...groups.map((g) =>
-      el('section', {}, [
+      el('section', { class: g.label === 'First hour' ? 'first' : '' }, [
         el('h2', { text: g.label }),
         el(
           'ol',
           {},
-          g.items.map((item) =>
-            el('li', {}, [
-              el('a', { class: isNew(item, seen) ? 'row new' : 'row', href: item.url }, [
-                el('span', { class: 'age', text: age(item.posted_at, now) }),
-                el('span', { class: 'body' }, [
-                  el('span', { class: 'where' }, [
-                    el('span', { text: item.where }),
-                    isNew(item, seen) ? el('span', { class: 'mark', text: 'new' }) : null,
-                  ]),
-                  el('span', { class: 'title', text: item.title }),
-                ]),
-              ]),
-            ]),
-          ),
+          g.items.map((item) => el('li', {}, [row(item, now)])),
         ),
       ]),
     ),
   );
+  onScreen.disconnect();
+  for (const node of list.querySelectorAll('.row')) onScreen.observe(node);
+}
+
+/** @param {import('./lib.js').Item} item @param {number} now */
+function row(item, now) {
+  const fresh = isNew(item, seen);
+  const { company, role } = parts(item);
+  const a = el('a', { class: ['row', fresh ? 'new' : '', isRead(item, seen) ? 'read' : ''].filter(Boolean).join(' '), href: item.url }, [
+    el('span', { class: 'age' }, [el('span', { text: age(item.posted_at, now) }), fresh ? el('span', { class: 'mark', text: 'new' }) : null]),
+    el('span', { class: 'co', text: company }),
+    el('span', { class: 'role', text: role }),
+    el('span', { class: 'src', text: sourceLabel(item) }),
+  ]);
+  a.dataset.id = item.id;
+  return a;
 }
 
 /** @param {Posts} p */
@@ -155,8 +169,27 @@ function onFilter() {
 }
 
 function markSeen() {
-  if (posts) saveSeen(storage(), nextSeen(seen, posts.items.map((item) => item.id), shown), new Date());
+  if (posts) saveSeen(storage(), nextSeen(seen, posts.items.map((item) => item.id), shown, viewed), new Date());
+}
+
+const themeButtons = /** @type {NodeListOf<HTMLButtonElement>} */ (document.querySelectorAll('[data-theme-choice]'));
+
+/** @param {import('./lib.js').Theme} theme */
+function applyTheme(theme) {
+  if (theme === 'auto') delete document.documentElement.dataset.theme;
+  else document.documentElement.dataset.theme = theme;
+  for (const button of themeButtons) button.setAttribute('aria-pressed', String(button.dataset.themeChoice === theme));
+}
+
+for (const button of themeButtons) {
+  button.addEventListener('click', () => {
+    const theme = button.dataset.themeChoice;
+    if (theme !== 'auto' && theme !== 'light' && theme !== 'dark') return;
+    saveTheme(storage(), theme);
+    applyTheme(theme);
+  });
 }
+applyTheme(loadTheme(storage()));
 
 input.value = new URL(location.href).searchParams.get('q') ?? '';
 input.addEventListener('input', onFilter);

public/fonts/recursive-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2019 The Recursive Project Authors (github.com/arrowtype/recursive)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

public/index.html

@@ -7,19 +7,30 @@
     <meta name="description" content="Fresh remote roles from Hacker News and the companies hiring there, while they are still new." />
     <meta name="color-scheme" content="light dark" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <link rel="preload" href="/fonts/recursive.woff2" as="font" type="font/woff2" crossorigin />
+    <script src="/theme.js"></script>
     <link rel="stylesheet" href="/style.css" />
     <script type="module" src="/app.js"></script>
   </head>
   <body>
-    <header>
-      <h1>firsthour</h1>
-      <p class="tagline">Fresh remote roles from Hacker News and the companies hiring there.</p>
-      <p id="status" class="status" aria-live="polite"></p>
+    <header class="masthead">
+      <div>
+        <h1>firsthour</h1>
+        <p class="tagline">Remote roles from Hacker News and its hiring companies, logged as they appear.</p>
+      </div>
+      <nav class="theme" aria-label="Theme">
+        <button type="button" data-theme-choice="auto">auto</button>
+        <button type="button" data-theme-choice="light">light</button>
+        <button type="button" data-theme-choice="dark">dark</button>
+      </nav>
     </header>
+    <p id="status" class="status" aria-live="polite"></p>
     <main>
-      <label for="q" class="visually-hidden">Filter</label>
-      <input id="q" type="search" placeholder="Filter: go, backend, -onsite" autocomplete="off" spellcheck="false" />
-      <p id="count" class="count" aria-live="polite"></p>
+      <div class="controls">
+        <label for="q" class="visually-hidden">Filter</label>
+        <input id="q" type="search" placeholder="Filter: go, backend, -onsite" autocomplete="off" spellcheck="false" />
+        <p id="count" class="count" aria-live="polite"></p>
+      </div>
       <div id="notice"></div>
       <div id="list" aria-busy="true"><p class="muted">Loading…</p></div>
     </main>