anentrypoint-design 0.0.414 → 0.0.416

package/dist/ui_kits/dashboard/app.js

@@ -1,15 +1,22 @@
 import * as webjsx from 'webjsx';
-import { Topbar, Crumb, Status, Side, AppShell, Panel, Heading, Lede, Chip, Kpi, Table, Receipt, Changelog, Row, RowLink } from 'ds/components.js';
+import { Topbar, Crumb, Status, Side, AppShell, Panel, Heading, Lede, Chip, Kpi, BarChart, Table, Receipt, Changelog, Row } from 'ds/components.js';
 import { mountKit } from 'ds/bootstrap.js';
 const h = webjsx.createElement;
 
 const root = document.getElementById('root');
 
 const kpis = [
-    ['24,891', 'requests · 24h'],
-    ['184ms',  'avg latency · p50'],
-    ['0.42%',  'error rate · 5xx+4xx'],
-    ['94.7%',  'cache hit · edge']
+    ['24,891', 'requests · 24h', { delta: '+12.4%', tone: 'up',   spark: [8, 11, 9, 14, 16, 15, 19, 22, 20, 24] }],
+    ['184ms',  'avg latency · p50', { delta: '-6.1%', tone: 'up',  spark: [220, 210, 205, 198, 190, 188, 184, 186, 182, 184] }],
+    ['0.42%',  'error rate · 5xx+4xx', { delta: '+0.08%', tone: 'down', spark: [0.2, 0.25, 0.3, 0.28, 0.35, 0.3, 0.38, 0.4, 0.36, 0.42] }],
+    ['94.7%',  'cache hit · edge', { delta: '+1.2%', tone: 'up', spark: [90, 91, 92, 91, 93, 92, 94, 93, 95, 94.7] }]
+];
+
+const channelBreakdown = [
+    { label: 'edge cache', value: 412, display: '412 rps' },
+    { label: 'origin fetch', value: 187, display: '187 rps' },
+    { label: 'feed api', value: 1200, display: '1.2k rps' },
+    { label: 'upload api', value: 24, display: '24 rps' }
 ];
 
 const tableHeaders = ['endpoint', 'rps', 'p95', 'errors', 'status'];
@@ -36,57 +43,139 @@ const changelog = [
     { date: '2026-05-07', ver: 'v0.4.10', msg: 'migrate session store · add p99 to /metrics' }
 ];
 
+// No 01/02/03 index: the feed is already ordered by the `meta` age column, so a
+// counter would carry no information and would read as a ranking that isn't one.
+// The rail tone is the real signal — it says what KIND of event this was, which
+// is what an operator scans for.
 const events = [
-    { code: '01', title: 'deploy succeeded',  sub: 'v0.4.12 · all regions',     meta: '2m' },
-    { code: '02', title: 'cache flushed',     sub: 'edge-cache · eu-west-1',    meta: '14m' },
-    { code: '03', title: 'p95 spike',         sub: '/api/upload · 1.4s',        meta: '38m' },
-    { code: '04', title: 'cron ran',          sub: 'reindex-search · ok',       meta: '1h' },
-    { code: '05', title: 'config reloaded',   sub: 'feature flags',             meta: '3h' }
+    { title: 'deploy succeeded',  sub: 'v0.4.12 · all regions',  meta: '2m',  rail: 'green' },
+    { title: 'cache flushed',     sub: 'edge-cache · eu-west-1', meta: '14m' },
+    { title: 'p95 spike',         sub: '/api/upload · 1.4s',     meta: '38m', rail: 'flame' },
+    { title: 'cron ran',          sub: 'reindex-search · ok',    meta: '1h',  rail: 'green' },
+    { title: 'config reloaded',   sub: 'feature flags',          meta: '3h' }
 ];
 
+// Every data panel below reads its state from here rather than assuming the
+// happy path. The sidebar "feed state" group flips it, so each state is a real
+// reachable surface in the kit, not dead code behind a flag nobody sets.
+const state = { feed: 'ready' };
+const FEED_STATES = ['ready', 'loading', 'empty', 'error'];
+
+// Loading placeholder for the events feed. Reuses the .ds-event-row-skeleton
+// primitive (app-shell/files.css) — the row shape it was cut for is the same
+// icon/title/meta rhythm Row() renders, so no new skeleton CSS is needed.
+function EventsSkeleton() {
+    return h('div', {},
+        ...[0, 1, 2, 3, 4].map((i) => h('div', { key: 'sk' + i, class: 'ds-event-row-skeleton' },
+            h('span', { class: 'ds-skel ds-skel-icon' }),
+            h('span', { class: 'ds-skel ds-skel-title' }),
+            h('span', { class: 'ds-skel ds-skel-meta' })
+        ))
+    );
+}
+
+function EventsEmpty() {
+    return h('div', { class: 'ds-empty-state' },
+        h('div', { class: 'ds-empty-state-glyph' }, '[ ]'),
+        h('p', { class: 'ds-empty-state-msg' }, 'no events in the last 24h'),
+        h('p', { class: 'ds-empty-state-hint' }, 'deploys, cache flushes and cron runs land here as they happen. a quiet feed means production is quiet.')
+    );
+}
+
+function EventsError() {
+    return h('div', { class: 'ds-alert ds-alert-error' },
+        h('span', { class: 'ds-alert-icon' }, '!'),
+        h('div', { class: 'ds-alert-content' },
+            h('div', { class: 'ds-alert-title' }, 'event stream disconnected'),
+            h('div', { class: 'ds-alert-message' }, 'the eu-west-1 collector stopped answering 38s ago, so this feed is stale. metrics above still come from the edge and are current.'),
+            h('div', { class: 'ds-alert-retry' },
+                h('button', { class: 'btn', onclick: () => { state.feed = 'ready'; kit.render(); } }, 'reconnect')
+            )
+        )
+    );
+}
+
+function EventsPanel() {
+    if (state.feed === 'loading') return EventsSkeleton();
+    if (state.feed === 'error') return EventsError();
+    if (state.feed === 'empty') return EventsEmpty();
+    return h('div', {}, ...events.map((e, i) => Row({ key: 'ev' + i, title: e.title, sub: e.sub, meta: e.meta, rail: e.rail })));
+}
+
+const feedCountOf = () => (state.feed === 'ready' ? events.length : 0);
+
 function App() {
+    const feedCount = feedCountOf();
     return AppShell({
-        topbar: Topbar({ brand: '247420', leaf: 'dashboard', items: [['index', '../../'], ['docs', '../docs/'], ['source ↗', 'https://github.com/AnEntrypoint/design']] }),
+        topbar: Topbar({ brand: '247420', leaf: 'dashboard', items: [['index', '../../'], ['docs', '../docs/'], ['source ->', 'https://github.com/AnEntrypoint/design']] }),
         crumb: Crumb({ trail: ['247420', 'kits'], leaf: 'dashboard' }),
         side: Side({
             sections: [
+                // Every entry anchors to the panel it names. These were four
+                // inert rows styled exactly like working nav; the counts were
+                // also invented, so they now read off the data each panel draws.
                 { group: 'views', items: [
-                    { glyph: '◆', label: 'overview', count: '·', key: 'o' },
-                    { glyph: '◇', label: 'requests', count: 5,    key: 'r' },
-                    { glyph: '◇', label: 'errors',   count: 2,    key: 'e' },
-                    { glyph: '◇', label: 'cron',     count: 7,    key: 'c' }
+                    { glyph: '*', label: 'overview',      count: kpis.length,             key: 'o', href: '#p-metrics' },
+                    { glyph: '-', label: 'endpoints',     count: tableRows.length,        key: 'r', href: '#p-endpoints' },
+                    { glyph: '-', label: 'events',        count: feedCountOf(),           key: 'e', href: '#p-events' },
+                    { glyph: '-', label: 'changelog',     count: changelog.length,        key: 'c', href: '#p-changelog' }
                 ] },
+                // Environment is a READOUT, not navigation — there is no
+                // per-environment view in this kit to switch to. It anchors to
+                // the environment receipt, which is the panel that actually
+                // carries this information, rather than promising a filter it
+                // cannot perform.
                 { group: 'env', items: [
-                    { glyph: '●', label: 'production', count: 'eu', key: 'p', color: 'var(--panel-accent)' },
-                    { glyph: '●', label: 'staging',    count: 'us', key: 's', color: 'var(--mascot,#e0a200)' }
-                ] }
+                    { glyph: h('span', { class: 'ds-dot ds-dot-on' }), label: 'production', count: 'eu', key: 'p', color: 'var(--panel-accent)', href: '#p-environment' },
+                    { glyph: h('span', { class: 'ds-dot ds-dot-off' }), label: 'staging',   count: 'us', key: 's', color: 'var(--mascot)', href: '#p-environment' }
+                ] },
+                // Reachable state switcher — the events panel is the kit's
+                // reference data surface, so every state it can be in is one
+                // click away rather than only existing on a real outage.
+                { group: 'feed state', items: FEED_STATES.map((s) => ({
+                    glyph: h('span', { class: state.feed === s ? 'ds-dot ds-dot-on' : 'ds-dot ds-dot-off' }),
+                    label: s, key: 'fs-' + s, active: state.feed === s, href: '#' + s,
+                    onClick: (e) => { e.preventDefault(); state.feed = s; kit.render(); }
+                })) }
             ]
         }),
         main: [
-            h('div', { class: 'ds-section', style: 'padding:8px' },
+            h('div', { class: 'ds-app-surface ds-section-pad' },
                 Heading({ level: 1, children: 'dashboard' }),
                 Lede({ children: 'kpis, tables, receipts, changelog — every content primitive in one operations surface.' }),
-                Panel({ title: 'live metrics', count: kpis.length, style: 'margin:8px 0', children: Kpi({ items: kpis }) }),
-                Panel({ title: 'top endpoints', count: tableRows.length, style: 'margin:8px 0', children: Table({ headers: tableHeaders, rows: tableRows }) }),
-                h('div', { style: 'display:grid;grid-template-columns:1fr 1fr;gap:8px;margin:8px 0' },
-                    Panel({ title: 'environment', children: Receipt({ rows: receipt }) }),
-                    Panel({ title: 'recent events', count: events.length, children: events.map((e, i) =>
-                        Row({ key: 'ev' + i, code: e.code, title: e.title, sub: e.sub, meta: e.meta })
-                    ) })
+                // Reading order: headline counters lead (the glance), then the
+                // paired analysis, then the three reference panels. Each tier is
+                // separated by the .ds-panel-gap/.ds-panel-duo outer rhythm,
+                // which is deliberately wider than any panel's inner gap.
+                Panel({ id: 'p-metrics', title: 'live metrics', count: kpis.length, class: 'ds-panel-gap', children: Kpi({ items: kpis }) }),
+                h('div', { class: 'ds-panel-duo' },
+                    Panel({ title: 'traffic by channel', count: channelBreakdown.length, class: 'ds-panel-flush', children: BarChart({ items: channelBreakdown }) }),
+                    Panel({ id: 'p-endpoints', title: 'top endpoints', count: tableRows.length, class: 'ds-panel-flush', children: h('div', { class: 'ds-scroll-x' }, Table({ headers: tableHeaders, rows: tableRows })) })
+                ),
+                // Three equal reference panels. A real 3-track grid, not
+                // percentage flex-basis: with basis+gap the three tracks
+                // overflow 100% and the last one wraps to its own row.
+                // .ds-panel-flush drops each panel's own bottom margin so the
+                // grid gap is the single source of separation in the row.
+                h('div', { class: 'ds-panel-trio' },
+                    Panel({ id: 'p-environment', title: 'environment', class: 'ds-panel-flush', children: Receipt({ rows: receipt }) }),
+                    Panel({ id: 'p-events', title: 'recent events', count: feedCount, class: 'ds-panel-flush', children: EventsPanel() }),
+                    Panel({ id: 'p-changelog', title: 'changelog', count: changelog.length, class: 'ds-panel-flush', children: Changelog({ entries: changelog }) })
                 ),
-                Panel({ title: 'changelog', count: changelog.length, style: 'margin:8px 0', children: Changelog({ entries: changelog }) }),
-                Panel({ title: 'about this kit', style: 'margin:8px 0', children: h('div', { class: 'ds-pattern-notes' },
-                    h('p', {}, '· ', Chip({ tone: 'accent', children: 'Kpi' }), ' for headline counters with delta + meta.'),
-                    h('p', {}, '· ', Chip({ tone: 'accent', children: 'Table' }), ' for tabular metrics, ', Chip({ tone: 'accent', children: 'Row' }), ' for event lists.'),
-                    h('p', {}, '· ', Chip({ tone: 'accent', children: 'Receipt' }), ' for kv environment manifest, ', Chip({ tone: 'accent', children: 'Changelog' }), ' for release log.')
+                Panel({ title: 'about this kit', class: 'ds-panel-gap', children: h('div', { class: 'ds-pattern-notes' },
+                    h('p', {}, '· ', Chip({ tone: 'accent', children: 'Kpi' }), ' for headline counters with trend delta + sparkline.'),
+                    h('p', {}, '· ', Chip({ tone: 'accent', children: 'BarChart' }), ' for a category breakdown, ', Chip({ tone: 'accent', children: 'Table' }), ' for tabular metrics, ', Chip({ tone: 'accent', children: 'Row' }), ' for event lists.'),
+                    h('p', {}, '· ', Chip({ tone: 'accent', children: 'Receipt' }), ' for kv environment manifest, ', Chip({ tone: 'accent', children: 'Changelog' }), ' for release log.'),
+                    h('p', {}, '· ', Chip({ tone: 'accent', children: 'ds-panel-trio' }), '/', Chip({ tone: 'accent', children: 'ds-panel-duo' }), ' for multi-panel rows — real grid tracks that step down on container width, not the viewport.'),
+                    h('p', {}, '· ', Chip({ tone: 'accent', children: 'ds-panel-flush' }), ' on any panel inside a gap-owning row, so the container is the single source of separation.')
                 ) })
             )
         ],
         status: Status({
-            left: ['dashboard', '• ' + kpis.length + ' kpis', '• ' + tableRows.length + ' endpoints'],
-            right: ['247420 / mmxxvi', '• live']
+            left: ['dashboard', '- ' + kpis.length + ' kpis', '- ' + tableRows.length + ' endpoints', '- feed ' + state.feed],
+            right: ['247420 / mmxxvi', '- live']
         })
     });
 }
 
-mountKit({ root, view: App, screen: '08 Dashboard' });
+const kit = mountKit({ root, view: App, screen: '08 Dashboard' });

package/dist/ui_kits/dashboard/index.html

@@ -11,6 +11,7 @@
   <link rel="icon" type="image/svg+xml" href="../../favicon.svg">
   <link rel="stylesheet" href="../../colors_and_type.css">
   <link rel="stylesheet" href="../../app-shell.css">
+  <link rel="stylesheet" href="../../editor-primitives.css">
 <script type="importmap">
 { "imports": {
   "webjsx": "../../vendor/webjsx/index.js",

package/dist/ui_kits/docs/index.html

@@ -34,13 +34,17 @@
 </head>
 <body data-screen-label="03 Docs">
 <div class="app">
+  <!-- Matches what AppShell() emits for the JS-rendered kits. This page hand-
+       rolls the shell markup statically, so it does not inherit the skip link
+       and had no way past the sidebar nav for a keyboard user. -->
+  <a href="#app-main" class="skip-link">skip to main content</a>
   <header class="app-topbar">
     <span class="brand">247420<span class="slash"> / </span>gm<span class="slash"> / </span>docs</span>
     <nav>
-      <a href="../homepage/">← all projects</a>
-      <a href="#">readme</a>
-      <a href="#" class="active">docs</a>
-      <a href="#">source ↗</a>
+      <a href="../homepage/"><- all projects</a>
+      <a href="https://github.com/AnEntrypoint/gm#readme">readme</a>
+      <a class="active" aria-current="page">docs</a>
+      <a href="https://github.com/AnEntrypoint/gm">source -></a>
     </nav>
   </header>
   <div class="app-crumb">
@@ -50,36 +54,42 @@
     <span class="leaf">introduction</span>
     <span class="crumb-right"><span class="chip dim">v0.4.1</span></span>
   </div>
+  <button class="app-side-toggle" type="button" aria-label="toggle navigation" aria-expanded="false" aria-controls="app-side-shell" onclick="document.querySelector('.app-body').classList.toggle('side-open')">
+    <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="18" x2="21" y2="18"/></svg>
+  </button>
   <div class="app-body">
+    <div class="app-side-scrim" aria-hidden="true" onclick="document.querySelector('.app-body').classList.remove('side-open')"></div>
+    <div class="app-side-shell" id="app-side-shell">
     <aside class="app-side">
       <div class="group">start</div>
-      <a href="#" class="active"><span class="glyph">§</span><span>introduction</span></a>
-      <a href="#"><span class="glyph">§</span><span>install</span></a>
-      <a href="#"><span class="glyph">§</span><span>quickstart</span></a>
+      <a href="#introduction" class="active"><span class="glyph">//</span><span>introduction</span></a>
+      <a href="#install"><span class="glyph">//</span><span>install</span></a>
+      <a href="#quickstart"><span class="glyph">//</span><span>quickstart</span></a>
       <div class="group">concepts</div>
-      <a href="#"><span class="glyph">›</span><span>states & transitions</span></a>
-      <a href="#"><span class="glyph">›</span><span>the loop</span></a>
-      <a href="#"><span class="glyph">›</span><span>tools</span></a>
+      <a class="is-unwritten" title="not written yet"><span class="glyph">&gt;</span><span>states & transitions</span></a>
+      <a class="is-unwritten" title="not written yet"><span class="glyph">&gt;</span><span>the loop</span></a>
+      <a class="is-unwritten" title="not written yet"><span class="glyph">&gt;</span><span>tools</span></a>
       <div class="group">reference</div>
-      <a href="#"><span class="glyph">›</span><span>executenodejs</span></a>
-      <a href="#"><span class="glyph">›</span><span>executedeno</span></a>
-      <a href="#"><span class="glyph">›</span><span>astgrep_*</span></a>
-      <a href="#"><span class="glyph">›</span><span>batch_execute</span></a>
+      <a class="is-unwritten" title="not written yet"><span class="glyph">&gt;</span><span>executenodejs</span></a>
+      <a class="is-unwritten" title="not written yet"><span class="glyph">&gt;</span><span>executedeno</span></a>
+      <a class="is-unwritten" title="not written yet"><span class="glyph">&gt;</span><span>astgrep_*</span></a>
+      <a class="is-unwritten" title="not written yet"><span class="glyph">&gt;</span><span>batch_execute</span></a>
       <div class="group">misc</div>
-      <a href="#"><span class="glyph">§</span><span>philosophy</span></a>
-      <a href="#"><span class="glyph">↗</span><span>changelog</span></a>
-      <a href="#"><span class="glyph">↗</span><span>source</span></a>
+      <a href="#philosophy"><span class="glyph">//</span><span>philosophy</span></a>
+      <a href="https://github.com/AnEntrypoint/gm/blob/main/CHANGELOG.md"><span class="glyph">-&gt;</span><span>changelog</span></a>
+      <a href="https://github.com/AnEntrypoint/gm"><span class="glyph">-&gt;</span><span>source</span></a>
     </aside>
-    <main class="app-main narrow">
+    </div>
+    <main class="app-main narrow" id="app-main" tabindex="0">
       <div class="ds-prose">
-        <h1>introduction</h1>
+        <h1 id="introduction">introduction</h1>
         <p class="lede">a state machine for coding agents. it thinks, so you don't have to (as much).</p>
 
         <p>gm is what happens when you stop trying to make an llm "smart" and start giving it a scaffolding to be useful inside of. it's a small, deterministic runtime that says: <em>here is where you are, here are the transitions available, pick one.</em> that's the whole idea.</p>
 
         <p>the rest of this document explains how to install it, how to wire it up, and how to stay out of its way.</p>
 
-        <h2>install</h2>
+        <h2 id="install">install</h2>
         <p>one command. you've probably seen this kind of thing before.</p>
         <pre><span class="c"># via claude code plugin marketplace</span>
 <span class="k">claude</span> plugin marketplace add AnEntrypoint/gm-cc
@@ -87,37 +97,37 @@
       </div>
 
       <div class="panel panel-inline-wide">
-        <div class="panel-head"><span>※ note</span></div>
+        <div class="panel-head"><span>[!] note</span></div>
         <div class="ds-pattern-notes">
-          if you're running <code>gm</code> without claude code, see <a href="#">reference / executenodejs</a>. you'll want bun 1.1+.
+          if you're running <code>gm</code> without claude code, see the <code>executenodejs</code> reference (not written yet). you'll want bun 1.1+.
         </div>
       </div>
 
       <div class="ds-prose">
-        <h2>quickstart</h2>
+        <h2 id="quickstart">quickstart</h2>
         <h3>the 30-second version</h3>
         <p>start the repl, ask it to do something, watch it work. press <code>Ctrl</code>+<code>C</code> if it goes somewhere you didn't mean.</p>
         <pre><span class="k">gm</span> start
-<span class="c">→ state: idle</span>
-<span class="c">→ tools available: 19</span>
+<span class="c">-> state: idle</span>
+<span class="c">-> tools available: 19</span>
 &gt; fix the failing test in src/router.ts
-<span class="c">→ state: reading</span>
-<span class="c">→ state: editing</span>
-<span class="c">→ state: verifying</span>
-<span class="c">→ state: done</span></pre>
+<span class="c">-> state: reading</span>
+<span class="c">-> state: editing</span>
+<span class="c">-> state: verifying</span>
+<span class="c">-> state: done</span></pre>
 
-        <h2>philosophy</h2>
+        <h2 id="philosophy">philosophy</h2>
         <p>there is no philosophy. read the source.</p>
       </div>
     </main>
   </div>
   <footer class="app-status">
     <span class="item">main</span>
-    <span class="item">• markdown</span>
-    <span class="item">• ln 1</span>
+    <span class="item">- markdown</span>
+    <span class="item">- ln 1</span>
     <span class="spread"></span>
     <span class="item">gm · v0.4.1</span>
-    <span class="item">• docs</span>
+    <span class="item">- docs</span>
   </footer>
 </div>
 </body></html>

package/dist/ui_kits/error_404/app.js

@@ -1,56 +1,111 @@
 import * as webjsx from 'webjsx';
-import { Topbar, Crumb, Status, AppShell, Panel, Heading, Lede, Chip, RowLink } from 'ds/components.js';
+import { Topbar, Crumb, Status, AppShell, Panel, Heading, Lede, RowLink } from 'ds/components.js';
 import { mountKit } from 'ds/bootstrap.js';
 const h = webjsx.createElement;
 
 const root = document.getElementById('root');
 
 const suggestions = [
-    { code: '◆', title: 'index',         sub: 'design system home',                 href: '../../',                meta: 'open ↗' },
-    { code: '◇', title: 'kits',          sub: 'every ui kit in the portfolio',      href: '../../#kits',           meta: 'jump ↗' },
-    { code: '§', title: 'previews',      sub: 'every primitive isolated',           href: '../../preview/buttons.html', meta: 'browse ↗' },
-    { code: 'md',title: 'readme',        sub: 'overview, manifesto, conventions',   href: 'https://github.com/AnEntrypoint/design/blob/main/README.md', meta: 'readme ↗' },
-    { code: '↗', title: 'github',        sub: 'source repo · 247420/anentrypoint',  href: 'https://github.com/AnEntrypoint/design',                     meta: 'source ↗' }
+    { code: '*', title: 'index',         sub: 'design system home',                 href: '../../',                meta: 'open ->' },
+    { code: '-', title: 'kits',          sub: 'every ui kit in the portfolio',      href: '../../#kits',           meta: 'jump ->' },
+    { code: '//', title: 'previews',      sub: 'every primitive isolated',           href: '../../preview/buttons.html', meta: 'browse ->' },
+    { code: 'md',title: 'readme',        sub: 'overview, manifesto, conventions',   href: 'https://github.com/AnEntrypoint/design/blob/main/README.md', meta: 'readme ->' },
+    { code: '->', title: 'github',        sub: 'source repo · 247420/anentrypoint',  href: 'https://github.com/AnEntrypoint/design',                     meta: 'source ->' }
 ];
 
 const path = (typeof location !== 'undefined' && location.search) ? new URLSearchParams(location.search).get('p') : null;
 
+// The suggestions panel is this page's one data surface — on a real site it is
+// fed by a "did you mean" lookup against the sitemap, which can be slow, come
+// back empty, or fail. The page is already the error state for the ROUTE; these
+// are the states of the recovery list itself, which is the part that has to
+// keep working when the rest of the page has already failed.
+const state = { phase: 'ready' };
+const PHASES = ['ready', 'loading', 'empty', 'error'];
+
+// Row shimmer. Reuses .ds-event-row-skeleton + .ds-skel* (app-shell/files.css)
+// — RowLink is the same code / title / meta rhythm.
+function SuggestSkeleton() {
+    return h('div', {},
+        ...Array.from({ length: 5 }, (_, i) => h('div', { key: 'sk' + i, class: 'ds-event-row-skeleton' },
+            h('span', { class: 'ds-skel ds-skel-rank' }),
+            h('span', { class: 'ds-skel ds-skel-title' }),
+            h('span', { class: 'ds-skel ds-skel-meta' })
+        ))
+    );
+}
+
+function SuggestEmpty() {
+    return h('div', { class: 'ds-empty-state' },
+        h('div', { class: 'ds-empty-state-glyph' }, '( )'),
+        h('p', { class: 'ds-empty-state-msg' }, 'nothing on this site looks like that url'),
+        h('p', { class: 'ds-empty-state-hint' }, 'the sitemap has no page with a similar name. the index and search links above still work — search is the better bet when the path was a guess.')
+    );
+}
+
+function SuggestError() {
+    return h('div', { class: 'ds-alert ds-alert-error' },
+        h('span', { class: 'ds-alert-icon' }, '!'),
+        h('div', { class: 'ds-alert-content' },
+            h('div', { class: 'ds-alert-title' }, 'could not look up alternatives'),
+            h('div', { class: 'ds-alert-message' }, 'the sitemap this page checks for near-matches is itself missing, so there is nothing to suggest. the back-to-index link above does not depend on it and still works.'),
+            h('div', { class: 'ds-alert-retry' },
+                h('button', { class: 'btn', onclick: () => { state.phase = 'ready'; kit.render(); } }, 'try lookup again')
+            )
+        )
+    );
+}
+
+function SuggestBody() {
+    if (state.phase === 'loading') return SuggestSkeleton();
+    if (state.phase === 'error') return SuggestError();
+    if (state.phase === 'empty') return SuggestEmpty();
+    return h('div', {}, ...suggestions.map((s, i) => RowLink({ key: 's' + i, code: s.code, title: s.title, sub: s.sub, meta: s.meta, href: s.href })));
+}
+
 function App() {
     return AppShell({
         narrow: true,
         topbar: Topbar({ brand: '247420', leaf: '404', items: [['index', '../../']] }),
         crumb: Crumb({ trail: ['247420', 'kits'], leaf: '404', right: path ? 'requested: ' + path : '' }),
         main: [
-            h('div', { class: 'ds-section', style: 'padding:8px' },
-                Panel({ style: 'margin:8px 0', children: h('div', { style: 'padding:36px 22px;text-align:center;display:flex;flex-direction:column;gap:14px;align-items:center' },
-                    h('div', { style: 'font-family:var(--ff-mono);font-size:120px;line-height:1;color:var(--panel-text-3);letter-spacing:-0.03em' }, '404'),
-                    Heading({ level: 1, style: 'margin:0', children: 'route not found' }),
+            h('div', { class: 'ds-section ds-section-pad' },
+                Panel({ class: 'ds-panel-gap', children: h('div', { class: 'ds-err-hero' },
+                    h('div', { class: 'ds-err-numeral' }, '404'),
+                    Heading({ level: 1, class: 'ds-m0', children: 'route not found' }),
                     Lede({ children: 'we looked. we asked the cat. there is nothing at this url. probably emerging.' }),
-                    path ? h('div', { style: 'display:inline-flex;gap:6px;align-items:center;font-family:var(--ff-mono);font-size:13px;color:var(--panel-text-2);background:var(--panel-1);padding:6px 12px;border-radius:8px' },
-                        h('span', { style: 'color:var(--panel-text-3)' }, 'requested'),
+                    path ? h('div', { class: 'ds-err-path' },
+                        h('span', { class: 'ds-text-3' }, 'requested'),
                         h('span', {}, path)
                     ) : null,
-                    h('div', { style: 'display:flex;gap:8px;flex-wrap:wrap;justify-content:center;margin-top:6px' },
-                        h('a', { href: '../../', class: 'btn btn-primary' }, '← back to index'),
+                    // Three real recoveries only. The suggestions state-cycler
+                    // used to sit here as a fourth peer button, which put a
+                    // demo control in the row a lost user actually reads and
+                    // gave it a label ("suggestions: ready") that names no
+                    // action. It moved to the panel head it governs.
+                    h('div', { class: 'ds-err-actions' },
+                        h('a', { href: '../../', class: 'btn btn-primary' }, '<- back to index'),
                         h('a', { href: '../search/', class: 'btn' }, 'search instead'),
                         h('button', { class: 'btn', onclick: () => history.back() }, 'go back')
-                    ),
-                    h('div', { style: 'display:flex;gap:6px;flex-wrap:wrap;justify-content:center;margin-top:4px' },
-                        Chip({ tone: 'dim', children: '◌ empty' }),
-                        Chip({ tone: 'dim', children: '· status 404' }),
-                        Chip({ tone: 'dim', children: '· no body' })
                     )
                 ) }),
-                Panel({ title: 'try one of these', count: suggestions.length, style: 'margin:8px 0',
-                    children: suggestions.map((s, i) => RowLink({ key: 's' + i, code: s.code, title: s.title, sub: s.sub, meta: s.meta, href: s.href }))
+                Panel({ title: 'try one of these', class: 'ds-panel-gap',
+                    // The cycler lives on the panel it drives, so it reads as
+                    // a demo affordance for this list rather than as a fourth
+                    // recovery action in the hero.
+                    right: h('button', { class: 'btn', onclick: () => {
+                        state.phase = PHASES[(PHASES.indexOf(state.phase) + 1) % PHASES.length];
+                        kit.render();
+                    } }, state.phase === 'ready' ? suggestions.length + ' routes' : state.phase),
+                    children: SuggestBody()
                 })
             )
         ],
         status: Status({
-            left: ['error', '• 404', '• ' + (path || 'unknown')],
+            left: ['error', '- 404', '- ' + (path || 'unknown'), '- suggest ' + state.phase],
             right: ['247420 / mmxxvi']
         })
     });
 }
 
-mountKit({ root, view: App, screen: '13 404' });
+const kit = mountKit({ root, view: App, screen: '13 404' });

package/dist/ui_kits/file_browser/README.md

@@ -22,7 +22,7 @@ each FileRow takes `{ name, type, size, modified, onOpen, onAction }`. `type` is
 
 | type      | rail color | glyph |
 | --------- | ---------- | ----- |
-| dir       | green      | ▣     |
+| dir       | green      | ◫     |
 | image     | sky        | ◰     |
 | video     | purple     | ▰     |
 | audio     | mascot     | ◎     |

package/dist/ui_kits/file_browser/app.js

@@ -1,6 +1,6 @@
 import * as webjsx from 'webjsx';
 import {
-    Topbar, Crumb, AppShell, Status, Btn,
+    Topbar, Crumb, AppShell, Status, Btn, Icon,
     FileGrid, FileToolbar, DropZone, UploadProgress, BreadcrumbPath,
     ConfirmDialog, PromptDialog, FileViewer,
     FilePreviewMedia, FilePreviewCode, FilePreviewText
@@ -41,9 +41,32 @@ const state = {
     viewer: null,
     confirm: null,
     prompt: null,
-    promptValue: ''
+    promptValue: '',
+    // Which state the listing renders in. FileGrid already owns `loading`
+    // (cold-load shimmer) and the empty copy; `error` is a directory-level
+    // failure that has to sit above the grid because there is no listing at
+    // all to decorate. Driven by the toolbar buttons below so every state is
+    // reachable rather than only reproducible against a real broken mount.
+    phase: 'ready'
 };
 
+const PHASES = ['ready', 'loading', 'empty', 'error'];
+
+// Directory-level failure. Names the problem AND the recovery: a bare "could
+// not load" tells the user nothing they can act on.
+function DirError() {
+    return h('div', { class: 'ds-alert ds-alert-error' },
+        h('span', { class: 'ds-alert-icon' }, '!'),
+        h('div', { class: 'ds-alert-content' },
+            h('div', { class: 'ds-alert-title' }, 'cannot read demo/tigers'),
+            h('div', { class: 'ds-alert-message' }, 'the mount answered but refused the listing -- your account has write access to this path and not read. ask an owner for read, or open a folder you created.'),
+            h('div', { class: 'ds-alert-retry' },
+                h('button', { class: 'btn', onclick: () => { state.phase = 'ready'; render(); } }, 'retry listing')
+            )
+        )
+    );
+}
+
 const root = document.getElementById('root');
 
 function previewBody(file) {
@@ -135,7 +158,10 @@ function pickFiles() {
 }
 
 function App() {
-    const main = h('div', { class: 'ds-file-stage' },
+    // ds-files-stack owns the full-height scroll geometry; ds-app-surface adds
+    // the Operate typescale so the page title sits at the app ceiling instead
+    // of the 64px display size, which outweighs the file list it labels.
+    const main = h('div', { class: 'ds-files-stack ds-app-surface' },
         h('h1', {}, 'file browser'),
         h('p', { class: 'lede' },
             'static demo of the 247420 file-browser primitives. drop files to fake-upload, click rows to preview, ',
@@ -148,7 +174,7 @@ function App() {
         }),
         FileToolbar({
             left: [
-                Btn({ onClick: pickFiles, children: '⇪ upload' }),
+                Btn({ onClick: pickFiles, 'aria-label': 'upload', children: [Icon('upload'), ' upload'] }),
                 Btn({ onClick: () => {
                     state.prompt = {
                         title: 'new folder',
@@ -167,8 +193,15 @@ function App() {
                 }, children: '+ folder' })
             ],
             right: [
+                // State switcher — keeps loading/empty/error one click away so
+                // they are living reference surfaces, not dead code.
+                ...PHASES.map((p) => h('button', {
+                    key: 'ph-' + p,
+                    class: state.phase === p ? 'btn btn-primary' : 'btn',
+                    onclick: () => { state.phase = p; render(); }
+                }, p)),
                 h('span', { class: 'meta ds-meta-mono' },
-                    String(state.files.length).padStart(2, '0') + ' items'
+                    String(state.phase === 'ready' ? state.files.length : 0).padStart(2, '0') + ' items'
                 )
             ]
         }),
@@ -181,11 +214,13 @@ function App() {
             onPick: pickFiles
         }),
         UploadProgress({ items: state.uploads }),
-        FileGrid({
-            files: state.files,
+        state.phase === 'error' ? DirError() : FileGrid({
+            files: state.phase === 'ready' ? state.files : [],
+            loading: state.phase === 'loading',
             onOpen: openViewer,
             onAction: rowAction,
-            emptyText: 'nothing to show — upload something or pick a folder.'
+            emptyText: 'this folder is empty — drop files on the zone above, or use + folder to start a tree here.',
+            emptyAction: Btn({ onClick: pickFiles, children: 'upload a file' })
         })
     );
 
@@ -198,12 +233,12 @@ function App() {
                     ['design', '../../'],
                     ['home', '../homepage/'],
                     ['docs', '../docs/'],
-                    ['source ↗', 'https://github.com/AnEntrypoint/Design']
+                    ['source ->', 'https://github.com/AnEntrypoint/Design']
                 ]
             }),
             crumb: Crumb({ trail: ['247420', 'ui kits'], leaf: 'file browser' }),
             main,
-            status: Status({ left: ['main', '• ' + state.files.length + ' items'], right: ['live', 'demo only'] })
+            status: Status({ left: ['main', '- ' + (state.phase === 'ready' ? state.files.length : 0) + ' items', '- ' + state.phase], right: ['live', 'demo only'] })
         }),
         state.viewer ? FileViewer({
             file: state.viewer,

package/dist/ui_kits/file_browser/index.html

@@ -18,6 +18,7 @@
   <meta name="robots" content="index, follow">
   <link rel="stylesheet" href="../../colors_and_type.css">
   <link rel="stylesheet" href="../../app-shell.css">
+  <link rel="stylesheet" href="../../chat.css">
 
 <script type="importmap">
 { "imports": {