zz-meridian 0.31.0 → 0.31.1

package/dist/migrations.js

@@ -556,7 +556,21 @@ export const RELEASE_MIGRATIONS = [
         instructions: 'The release\'s `app/layout.tsx` shows `app.description` as the document\'s description — the line a search engine and a link preview put under the name — where it used to write a sentence of the template\'s own. `src/app.config.ts` is yours and an update does not touch it, so the key is missing there until you add it. Add `description: \'<one sentence about your product>\',` to the `app` object beside `name`. A project that keeps its own `app/layout.tsx` needs the key all the same, because the layout a project brings over from the release reads it.',
         checks: ['gate'],
     },
+    {
+        id: 'live-stream-shutdown',
+        since: '0.31.1',
+        applies: liveStreamKeptOnStop,
+        summary: 'The live stream ends every open stream when the server is told to stop, so tabs reconnect to the server that replaces it.',
+        instructions: '`src/data/live-stream.ts` is yours, so an update does not touch it, and the copy you have never ends a stream. A server told to stop (`next start` on SIGTERM or SIGINT, as a deploy or a restart does) closes its port and waits for its open connections: the old process stays up holding every tab\'s stream while the new one serves the port, so no tab hears a change hint again and every change waits for its next safety poll. Bring the block that begins `Every stream still open` over from `references/live.md` (the `open` set, `endLiveStreams` and `endOnShutdown`), call `open.delete(close)` first in the stream\'s `close`, and `endOnShutdown(close)` after the stream listens for its abort. A project that serves its stream some other way ends its streams on the signal the same way.',
+        checks: ['gate'],
+    },
 ];
+/** 0.31.1: a live stream starter that does not end its streams when the server is told to stop. */
+function liveStreamKeptOnStop(root) {
+    const rel = 'src/data/live-stream.ts';
+    const body = text(root, rel);
+    return body !== null && /export function liveStream\b/.test(body) && !/endLiveStreamsOnSignal/.test(body) ? [rel] : null;
+}
 /** The `app` object of a project's configuration, as `src/app.config.ts` writes it. */
 const APP_OBJECT = /^export const app = \{[\s\S]*?^\} as const;$/m;
 /** 0.30.0: the release's layout reads `app.description`, and a project's own configuration has no such key. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "description": "Bring ZZ Meridian, a dashboard design system, into a Next.js project, or start a new dashboard on it. Copies the files in; nothing depends on this package at runtime.",
   "license": "MIT",
   "type": "module",

package/payload/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 Every release of ZZ Meridian, newest first. Versions follow semver: a removed or renamed token, prop or card is major; a new card, token or variant is minor; a corrected value is a patch. Each entry says what breaks and what to do instead.
 
+## [0.31.1] · 2026-10-27
+
+### Fixed
+
+- **A server that is stopped lets go of its live streams.** `next start` told to stop (SIGTERM or SIGINT, as a deploy or a restart does) closes its port and then waits for its open connections, and a live stream never ended of itself. So the old process stayed up holding every tab's stream while the new one served the port: no tab heard a change hint again, and every change waited for the tab's next safety poll (the weekly live check: `a server restart: B did not show a write made after the restart within 5000 ms`). `liveStream` now ends every open stream when the process is told to stop; each tab reconnects to the new server within about a second and hears hints again (a write after a restart reached the other tab in 540 ms, where it took 2.9 s). Where nothing else listens for the signal, the process still stops as it did.
+  - **What a team does.** `src/data/live-stream.ts` is yours, so an update does not replace it: run `update`, which reports `migration:live-stream-shutdown` for a copy that never ends its streams, and bring the block that begins `Every stream still open` over from `references/live.md`.
+  - **Doing nothing.** Nothing fails; a deploy or restart keeps the old server up while a tab is open, and changes reach other tabs only at their next poll until they reload.
+- **A live tab tries its stream again as soon as the server answers after it did not.** A tab that had given its stream up for polling tried it again only on every fifth poll. A poll that answers after one that failed (the server is back) now opens the stream at once, so hints resume; a stream a proxy blocks, whose polls never fail, is still tried on every fifth poll.
+
 ## [0.31.0] · 2026-10-26
 
 ### New

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "private": true,
   "license": "MIT",
   "description": "ZZ Meridian: a dashboard design system and starter. Six layers, from DTCG tokens through four layers of React components to product workspaces, and a Design Atlas, in a light and a dark theme.",

package/payload/skills/zz-meridian/references/live.md

@@ -115,6 +115,33 @@ const MAX_QUEUED = 100;
 
 let noted = false;
 
+/**
+ * Every stream still open. A server told to stop (`next start` on SIGTERM or SIGINT) closes its port and then waits for
+ * its open connections, and a stream never ends of itself: the old process kept every tab's stream while the new one
+ * served the port, so no tab heard a hint again until its next poll. Ending them lets the old process go and each tab
+ * connect to the new one.
+ */
+const open = new Set<() => void>();
+let watching = false;
+
+/** Ends every open stream; each tab reconnects (the stream's `retry`), to whichever server then holds the port. */
+function endLiveStreams() {
+  for (const close of [...open]) close();
+}
+
+function endOnShutdown(close: () => void) {
+  open.add(close);
+  if (watching || typeof process === 'undefined' || typeof process.once !== 'function') return;
+  watching = true;
+  for (const sig of ['SIGTERM', 'SIGINT'] as const) {
+    process.once(sig, function endLiveStreamsOnSignal() {
+      endLiveStreams();
+      // A listener takes the place of the signal's default: where nothing else listens, the process stops as it would have.
+      if (process.listenerCount(sig) === 0) process.kill(process.pid, sig);
+    });
+  }
+}
+
 type LiveStreamOptions = {
   /** The requested names, already authorized once; the first frame greets with what moved. */
   names: string[];
@@ -141,6 +168,7 @@ export function liveStream({ names, collections, signal, heartbeatMs = 15000, au
   function close() {
     if (closed) return;
     closed = true;
+    open.delete(close);
     clearInterval(timer);
     for (const off of unsubscribe) off();
     unsubscribe.length = 0;
@@ -195,6 +223,7 @@ export function liveStream({ names, collections, signal, heartbeatMs = 15000, au
       controller = c;
       if (signal.aborted) return close();
       signal.addEventListener('abort', close);
+      endOnShutdown(close);
       // Subscribe first, then compare: a write after the page's read either moves a revision the greeting names or
       // arrives as a hint.
       collections.forEach((collection, i) => {

package/payload/skills/zz-meridian/references/update.md

@@ -191,6 +191,7 @@ Moving a project to 0.9.0 can report two more `migration:<id>` items, to 0.10.0
 | `no-data-mark` (0.19.0) | a test of the team's importing the Column chart and expecting a `.bg-fill-track` in a period with no data, such as `optional:tests/column-chart-no-data.test.tsx` as the template wrote it | a `null` period draws a dashed hairline on the baseline since 0.19.0, not a track the height of the scale, which was the tallest mark on the chart: bring `optional:tests/column-chart-no-data.test.tsx` over from the release as it has it, and find `[data-no-data-mark]` where a test of your own found `.bg-fill-track` or `[data-track]`; checked by the gate |
 | `table-grid` (0.26.0) | a file of the team's importing the Table or the DataTable that expects a `grow` column's `@min-[672px]:min-w-64`, such as `optional:tests/table-cut-cell.test.tsx` as the template wrote it, or passes a `colSpan` to a `TableCell` | a table is a grid since 0.26.0, its spare shared equally between the gaps, and a `grow` column's floor is `min-w-40` at every width: bring `optional:tests/table-cut-cell.test.tsx` over from the release as it has it, expect `min-w-40` alone where a test of your own expected the wider floor, and draw a row that spans the table, such as an empty state, outside it or as a `DataTable` `empty`, since a cell takes one track; checked by the gate |
 | `four-layers` (0.28.0) | a file of the team's importing a module that has left `optional:src/views/` or `optional:src/data/` for `src/logic/` — the migration names the file and, in its instruction, every path the module left — or importing `afterStart` from `src/components/patterns/incident-card` or `summarise` from `src/components/patterns/status-list`, which no longer export them | thirty-eight modules are in `src/logic/` since 0.28.0, thirty-six of them from `optional:src/views/`, and each import is rewritten to the path the module has: `afterStart` is `src/logic/after-start.ts` and `summarise` is `src/logic/summarise.ts`, and those two must move because the cards are Meridian's and the update replaces them, while every path under `optional:src/views/` and `optional:src/data/` is the team's and stays as it is; a created project brings the release's `src/logic/` over with the pages that import it; the standard the layers come from is `data-layers.md`; checked by the gate and a build |
+| `live-stream-shutdown` (0.31.1) | `optional:src/data/live-stream.ts` that never ends its streams when the server is told to stop | a stopped `next start` closes its port and waits for its open connections, so the old process kept every tab's stream while the new one served the port and no tab heard a hint again until its next poll: bring the block that begins `Every stream still open` over from `live.md`, delete the stream from the open set first in its `close`, and register it after it listens for its abort; checked by the gate |
 
 A created project that never changed the template's pages brings the release's version of each affected file over, with
 the files that arrived with them: the view contexts `optional:src/logic/home-context.ts` and its siblings, the view

package/payload/src/data/live-stream.ts

@@ -10,6 +10,33 @@ const MAX_QUEUED = 100;
 
 let noted = false;
 
+/**
+ * Every stream still open. A server told to stop (`next start` on SIGTERM or SIGINT) closes its port and then waits for
+ * its open connections, and a stream never ends of itself: the old process kept every tab's stream while the new one
+ * served the port, so no tab heard a hint again until its next poll. Ending them lets the old process go and each tab
+ * connect to the new one.
+ */
+const open = new Set<() => void>();
+let watching = false;
+
+/** Ends every open stream; each tab reconnects (the stream's `retry`), to whichever server then holds the port. */
+function endLiveStreams() {
+  for (const close of [...open]) close();
+}
+
+function endOnShutdown(close: () => void) {
+  open.add(close);
+  if (watching || typeof process === 'undefined' || typeof process.once !== 'function') return;
+  watching = true;
+  for (const sig of ['SIGTERM', 'SIGINT'] as const) {
+    process.once(sig, function endLiveStreamsOnSignal() {
+      endLiveStreams();
+      // A listener takes the place of the signal's default: where nothing else listens, the process stops as it would have.
+      if (process.listenerCount(sig) === 0) process.kill(process.pid, sig);
+    });
+  }
+}
+
 type LiveStreamOptions = {
   /** The requested names, already authorized once; the first frame greets with what moved. */
   names: string[];
@@ -36,6 +63,7 @@ export function liveStream({ names, collections, signal, heartbeatMs = 15000, au
   function close() {
     if (closed) return;
     closed = true;
+    open.delete(close);
     clearInterval(timer);
     for (const off of unsubscribe) off();
     unsubscribe.length = 0;
@@ -90,6 +118,7 @@ export function liveStream({ names, collections, signal, heartbeatMs = 15000, au
       controller = c;
       if (signal.aborted) return close();
       signal.addEventListener('abort', close);
+      endOnShutdown(close);
       // Subscribe first, then compare: a write after the page's read either moves a revision the greeting names or
       // arrives as a hint.
       collections.forEach((collection, i) => {

package/payload/src/lib/live.ts

@@ -56,6 +56,8 @@ export function createLiveClient({ refresh, endpoint = '/api/live', pollMs = 300
   let disposed = false;
   let paused = false;
   let polling = false;
+  /** The last refresh failed for a reason other than access: the server did not answer. */
+  let unreachable = false;
   let state: LiveState | null = null;
   /** Bumped whenever results in flight must stop counting: the page hid, or the client ended. */
   let epoch = 0;
@@ -122,9 +124,18 @@ export function createLiveClient({ refresh, endpoint = '/api/live', pollMs = 300
         if (full) synced = true;
         if (synced && opened) emit('live');
         else if (polling) emit('polling');
+        // A server that answers again after it did not (a restart, a deploy) is tried for its stream at once, not on the
+        // fifth poll: until then its hints are lost and every change waits for a poll. A refresh that never failed does
+        // not count, so a stream a proxy blocks is still tried only on every fifth poll.
+        if (unreachable && polling) {
+          attempts = MAX_ATTEMPTS - 1;
+          connect();
+        }
+        unreachable = false;
       }
     } catch (e) {
       if (mine === epoch && !disposed) {
+        if (!isAuthError(e)) unreachable = true;
         if (isAuthError(e)) {
           paused = true;
           closeSource();

package/payload/tests/live-client.test.tsx

@@ -158,6 +158,25 @@ describe('the live client', () => {
     expect(FakeSource.all.length).toBe(opened + 1);
     c.dispose();
   });
+  it('tries the stream at once when a poll answers after one that did not, as a restarted server does', async () => {
+    let down = false;
+    const refresh = vi.fn(async () => { if (down) throw new Error('network'); });
+    const { c, states } = client(refresh, 1000);
+    c.setNames(['members']);
+    for (let i = 0; i < 3; i++) { live().at(-1)!.fail(); await flush(1100); }
+    expect(states.at(-1)).toBe('polling');
+    down = true;
+    await flush(1000);
+    const opened = FakeSource.all.length;
+    down = false;
+    await flush(1000);
+    // The poll that answered opened a stream; without the rule the next try would wait for the fifth poll.
+    expect(FakeSource.all.length).toBe(opened + 1);
+    live().at(-1)!.open();
+    await flush(600);
+    expect(states.at(-1)).toBe('live');
+    c.dispose();
+  });
   it('pauses on an authorization failure and goes stale on any other', async () => {
     const denied = client(async () => { throw Object.assign(new Error('no'), { status: 403 }); });
     denied.c.setNames(['members']);