@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/shared/lib/theme/theme.test.ts

@@ -0,0 +1,199 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The theme surface `catalog.test.ts` does not already cover: hex arithmetic,
+ * the exact CSS the SSR shell inlines, and the structural parity of the three
+ * palette sources.
+ *
+ * Why each case is risky:
+ *
+ * - `rgbaToHex` feeds xterm, which rejects anything but literal hex. An
+ *   out-of-range or unrounded channel emits `#ff0-10`, a color no consumer can
+ *   parse, so clamping/rounding is pinned here.
+ * - `mixHex` composites the blend's own alpha. A palette that carries 8-digit
+ *   alpha (vitesse-dark's `#dbd7caee`) would otherwise be blended as if it were
+ *   opaque, darkening every derived shade.
+ * - The stylesheet is generated, so a rename of `--theme-*` in `css.ts` would
+ *   silently leave every panel reading an undefined variable. The exact block
+ *   for `paper` pins both the names and their order.
+ * - The three palette files are hand-ported data. A palette missing one of the
+ *   twelve fields would paint `undefined` into a CSS declaration; the parity
+ *   test fails loudly instead of rendering an invisible swatch.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { mixHex, parseHexColor, relativeLuminance, rgbaToHex } from '@/shared/lib/theme/color';
+import { THEME_STYLE_ELEMENT_ID, themeStyleSheet } from '@/shared/lib/theme/css';
+import { KABMO_PALETTES } from '@/shared/lib/theme/palettes/kabmo';
+import { DARK_PALETTES } from '@/shared/lib/theme/palettes/dark';
+import { LIGHT_PALETTES } from '@/shared/lib/theme/palettes/light';
+import { THEMES } from '@/shared/lib/theme/catalog';
+
+const PALETTE_KEYS = [
+  'canvas',
+  'error',
+  'family',
+  'id',
+  'info',
+  'ink',
+  'meta',
+  'name',
+  'paper',
+  'success',
+  'variant',
+  'warning',
+];
+
+describe('hex color parsing', () => {
+  test('accepts 3, 6 and 8 digit forms with or without the hash', () => {
+    expect(parseHexColor('#abc')).toEqual({ r: 170, g: 187, b: 204, a: 1 });
+    expect(parseHexColor('fff')).toEqual({ r: 255, g: 255, b: 255, a: 1 });
+    expect(parseHexColor('  #AABBCC  ')).toEqual({ r: 170, g: 187, b: 204, a: 1 });
+    expect(parseHexColor('#aabbccdd')).toEqual({ r: 170, g: 187, b: 204, a: 0xdd / 255 });
+  });
+
+  test('splits the 8-digit form as rrggbbaa, not aabbggrr', () => {
+    // `#12345678`: r=0x12, g=0x34, b=0x56, a=0x78. A byte-order slip here
+    // swaps ink and accent in every alpha-carrying palette.
+    const parsed = parseHexColor('#12345678');
+    expect(parsed).not.toBeNull();
+    expect(parsed?.r).toBe(0x12);
+    expect(parsed?.g).toBe(0x34);
+    expect(parsed?.b).toBe(0x56);
+    expect(parsed?.a).toBeCloseTo(0x78 / 255, 10);
+  });
+
+  test('returns null for every notation it does not implement', () => {
+    for (const value of ['#1234', '#12345', '#1234567', '#ggg', 'red', 'rgb(0,0,0)', 'color-mix(in srgb, red, blue)', '']) {
+      expect(parseHexColor(value)).toBeNull();
+    }
+  });
+});
+
+describe('rgbaToHex', () => {
+  test('emits literal lower-case hex', () => {
+    expect(rgbaToHex({ r: 0, g: 255, b: 16, a: 1 })).toBe('#00ff10');
+  });
+
+  test('clamps out-of-range channels instead of emitting an invalid color', () => {
+    // Rounding 127.6 -> 128 -> '80'; the alpha channel is ignored.
+    expect(rgbaToHex({ r: 300, g: -5, b: 127.6, a: 0 })).toBe('#ff0080');
+  });
+});
+
+describe('mixHex', () => {
+  test('interpolates from base at ratio 0 to blend at ratio 1', () => {
+    expect(mixHex('#000000', '#ffffff', 0)).toBe('#000000');
+    expect(mixHex('#000000', '#ffffff', 1)).toBe('#ffffff');
+    expect(mixHex('#000000', '#ffffff', 0.5)).toBe('#808080');
+  });
+
+  test('composites the blend alpha, so a transparent blend changes nothing', () => {
+    expect(mixHex('#123456', '#ffffff00', 1)).toBe('#123456');
+    // Alpha 0x80 over black at ratio 1 lands on 128/255 of the way to white.
+    expect(mixHex('#ffffff', '#00000080', 1)).toBe('#7f7f7f');
+  });
+
+  test('falls back to the base when either color cannot be parsed', () => {
+    expect(mixHex('not-a-color', '#ffffff', 0.5)).toBe('not-a-color');
+    expect(mixHex('#123456', 'not-a-color', 0.5)).toBe('#123456');
+  });
+});
+
+describe('relativeLuminance', () => {
+  test('spans 0 for black to 1 for white', () => {
+    expect(relativeLuminance('#000000')).toBe(0);
+    expect(relativeLuminance('#ffffff')).toBe(1);
+    expect(relativeLuminance('not-a-color')).toBe(0);
+  });
+
+  test('orders a light palette above its dark counterpart', () => {
+    expect(relativeLuminance('#f4f1ea')).toBeGreaterThan(relativeLuminance('#21252b'));
+  });
+
+  test('ignores the alpha byte, which carries no luminance', () => {
+    expect(relativeLuminance('#ffffff00')).toBe(1);
+  });
+});
+
+describe('generated stylesheet', () => {
+  const css = themeStyleSheet();
+
+  test('exports the element id the SSR shell and client both look for', () => {
+    expect(THEME_STYLE_ELEMENT_ID).toBe('omp-theme-palettes');
+  });
+
+  test('emits the exact variable block for the default palette', () => {
+    const paper = KABMO_PALETTES[0];
+    const block = [
+      `html[data-theme="${paper.id}"] {`,
+      `  --theme-paper: ${paper.paper};`,
+      `  --theme-canvas: ${paper.canvas};`,
+      `  --theme-ink: ${paper.ink};`,
+      `  --theme-error: ${paper.error};`,
+      `  --theme-success: ${paper.success};`,
+      `  --theme-info: ${paper.info};`,
+      `  --theme-warning: ${paper.warning};`,
+      `  --theme-meta: ${paper.meta};`,
+      '  --theme-info-hover: color-mix(in srgb, var(--theme-info) 85%, var(--theme-ink));',
+      '  --theme-warning-hover: color-mix(in srgb, var(--theme-warning) 85%, var(--theme-ink));',
+      `  color-scheme: ${paper.variant};`,
+      '}',
+    ].join('\n');
+    expect(css).toContain(block);
+  });
+
+  test('names every slot --theme-* and nothing else', () => {
+    const names = [...css.matchAll(/--theme-[a-z-]+:/g)].map((match) => match[0]);
+    expect(new Set(names).size).toBe(10);
+    expect(names[0]).toBe('--theme-paper:');
+    expect(names[7]).toBe('--theme-meta:');
+  });
+
+  test('is cached for the life of the process', () => {
+    expect(themeStyleSheet()).toBe(css);
+  });
+});
+
+describe('palette sources', () => {
+  const all = [...KABMO_PALETTES, ...LIGHT_PALETTES, ...DARK_PALETTES];
+
+  test('every palette declares the same twelve keys', () => {
+    for (const palette of all) {
+      expect(Object.keys(palette).sort()).toEqual(PALETTE_KEYS);
+    }
+  });
+
+  test('every declared value is a non-empty string', () => {
+    for (const palette of all) {
+      for (const [key, value] of Object.entries(palette)) {
+        expect(typeof value, `${palette.id}.${key}`).toBe('string');
+        expect((value as string).length, `${palette.id}.${key}`).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  test('each source array carries only its own variant and unique ids', () => {
+    const seen = new Set<string>();
+    for (const palette of all) {
+      expect(seen.has(palette.id), `duplicate id ${palette.id}`).toBe(false);
+      seen.add(palette.id);
+    }
+    for (const palette of LIGHT_PALETTES) expect(palette.variant).toBe('light');
+    for (const palette of DARK_PALETTES) expect(palette.variant).toBe('dark');
+    expect(all.length).toBe(THEMES.length);
+  });
+
+  test('the ported families pair up: every light family has a dark twin', () => {
+    const light = new Set(LIGHT_PALETTES.map((palette) => palette.family));
+    const dark = new Set(DARK_PALETTES.map((palette) => palette.family));
+    expect(new Set(LIGHT_PALETTES.map((palette) => palette.family)).size).toBe(LIGHT_PALETTES.length);
+    expect(new Set(DARK_PALETTES.map((palette) => palette.family)).size).toBe(DARK_PALETTES.length);
+    expect([...light].filter((family) => !dark.has(family))).toEqual([]);
+    expect([...dark].filter((family) => !light.has(family))).toEqual([]);
+  });
+});

package/src/shared/lib/ui/key-binding.test.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The chord matcher every shortcut in the app shares.
+ *
+ * Two failures are silent and both are covered here: matching on `event.key`
+ * (which never fires on macOS, where Option produces a different character), and
+ * a label that disagrees with the stroke it describes. The matcher is also
+ * platform-guarded, so a chord from the other platform must not fire.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  bindingFor,
+  describeStroke,
+  matchesStroke,
+  printableKey,
+  resolveBinding,
+  strokeOf,
+  type KeyBinding,
+  type KeyboardEventLike,
+} from '@/shared/lib/ui/key-binding';
+
+type Command = 'open' | 'save' | 'redo';
+
+const BINDINGS: readonly KeyBinding<Command>[] = [
+  { command: 'open', label: 'Open', mac: { code: 'KeyO', meta: true }, other: { code: 'KeyO', ctrl: true } },
+  { command: 'save', label: 'Save', mac: { code: 'KeyS', meta: true, shift: true }, other: { code: 'KeyS', ctrl: true, shift: true } },
+  {
+    command: 'redo',
+    label: 'Redo',
+    mac: { code: 'KeyZ', meta: true, shift: true },
+    other: { code: 'KeyZ', ctrl: true, shift: true },
+    windows: { code: 'KeyY', ctrl: true },
+  },
+];
+
+function key(code: string, keyName: string, modifiers: Partial<KeyboardEventLike> = {}): KeyboardEventLike {
+  return { code, key: keyName, metaKey: false, ctrlKey: false, altKey: false, shiftKey: false, ...modifiers };
+}
+
+describe('matchesStroke', () => {
+  test('requires the exact modifier set', () => {
+    const stroke = { code: 'KeyF', meta: true };
+    expect(matchesStroke(stroke, key('KeyF', 'f', { metaKey: true }))).toBe(true);
+    expect(matchesStroke(stroke, key('KeyF', 'f', { metaKey: true, shiftKey: true }))).toBe(false);
+    expect(matchesStroke(stroke, key('KeyF', 'f', { ctrlKey: true }))).toBe(false);
+  });
+
+  test('reads the physical key, not the character it produces', () => {
+    // macOS reports ⌥⌘C as `Ç`; a `key`-based test would never fire there.
+    expect(matchesStroke({ code: 'KeyC', meta: true, alt: true }, key('KeyC', 'Ç', { metaKey: true, altKey: true }))).toBe(true);
+  });
+});
+
+describe('strokeOf', () => {
+  test('picks the platform’s own chord', () => {
+    expect(strokeOf(BINDINGS[0], true)).toEqual({ code: 'KeyO', meta: true });
+    expect(strokeOf(BINDINGS[0], false)).toEqual({ code: 'KeyO', ctrl: true });
+  });
+
+  test('uses the Windows override only where it exists', () => {
+    // Windows redoes with Ctrl+Y while Linux keeps Ctrl+Shift+Z; one `other`
+    // stroke cannot express both — so `strokeOf` consults the PLATFORM for the
+    // override and the `other` chord for everything else. `isWindowsPlatform()`
+    // reads `navigator.platform`, which is whatever host the suite runs on, so
+    // the override branch has to be selected explicitly rather than assumed: on
+    // a Windows runner this assertion was reading the override's answer.
+    const original = Object.getOwnPropertyDescriptor(globalThis, 'navigator');
+    Object.defineProperty(globalThis, 'navigator', { value: { platform: 'Win32' }, configurable: true });
+    try {
+      expect(strokeOf(BINDINGS[2], false)).toEqual({ code: 'KeyY', ctrl: true });
+    } finally {
+      if (original) Object.defineProperty(globalThis, 'navigator', original);
+      else delete (globalThis as { navigator?: unknown }).navigator;
+    }
+    // Off Windows the Linux chord stands.
+    Object.defineProperty(globalThis, 'navigator', { value: { platform: 'Linux x86_64' }, configurable: true });
+    try {
+      expect(strokeOf(BINDINGS[2], false)).toEqual({ code: 'KeyZ', ctrl: true, shift: true });
+    } finally {
+      if (original) Object.defineProperty(globalThis, 'navigator', original);
+      else delete (globalThis as { navigator?: unknown }).navigator;
+    }
+  });
+});
+
+describe('resolveBinding', () => {
+  test('returns the command a chord names', () => {
+    expect(resolveBinding(BINDINGS, key('KeyO', 'o', { metaKey: true }), true)).toBe('open');
+    expect(resolveBinding(BINDINGS, key('KeyO', 'o', { ctrlKey: true }), false)).toBe('open');
+  });
+
+  test('a chord from the other platform never fires', () => {
+    expect(resolveBinding(BINDINGS, key('KeyO', 'o', { ctrlKey: true }), true)).toBeNull();
+    expect(resolveBinding(BINDINGS, key('KeyO', 'o', { metaKey: true }), false)).toBeNull();
+  });
+
+  test('an unbound chord resolves to nothing', () => {
+    expect(resolveBinding(BINDINGS, key('KeyQ', 'q', { metaKey: true }), true)).toBeNull();
+  });
+});
+
+describe('bindingFor', () => {
+  test('finds the binding a tooltip needs to label', () => {
+    expect(bindingFor(BINDINGS, 'save')?.label).toBe('Save');
+    expect(bindingFor(BINDINGS, 'open')?.mac).toEqual({ code: 'KeyO', meta: true });
+  });
+});
+
+describe('printableKey and describeStroke', () => {
+  test('prints the physical key the way a reader expects', () => {
+    expect(printableKey('KeyC')).toBe('C');
+    expect(printableKey('Digit1')).toBe('1');
+    expect(printableKey('Slash')).toBe('/');
+    expect(printableKey('BracketLeft')).toBe('[');
+    expect(printableKey('ArrowUp')).toBe('ArrowUp');
+    expect(printableKey('F3')).toBe('F3');
+  });
+
+  test('mac chords render without separators, others with plus signs', () => {
+    expect(describeStroke({ code: 'KeyC', meta: true, alt: true }, true)).toBe('⌥⌘C');
+    expect(describeStroke({ code: 'KeyC', alt: true }, false)).toBe('Alt+C');
+    expect(describeStroke({ code: 'Slash', ctrl: true }, false)).toBe('Ctrl+/');
+  });
+
+  test('modifier order is stable, so two labels for one chord cannot differ', () => {
+    expect(describeStroke({ code: 'ArrowDown', meta: true, alt: true, shift: true }, true)).toBe('⌥⇧⌘ArrowDown');
+  });
+});

package/src/shared/lib/ui/key-binding.ts

@@ -0,0 +1,143 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One chord matcher for every shortcut in the app.
+ *
+ * The editor's find bar, the editor's own commands and the panel shortcuts all
+ * have to answer the same question — "is this event this chord?" — and they
+ * must answer it identically or the same physical key means different things
+ * depending on which surface has focus. They also have to *describe* it
+ * identically: a tooltip that reads `⌥⌘C` while the binding listens for
+ * something else is worse than an unlabeled button, and the command palette
+ * lists the very same strings.
+ *
+ * Matching is on `event.code`, not `event.key`: with Option held, macOS reports
+ * the character the combination produces (`⌥⌘C` arrives as `Ç`), so a
+ * `key`-based test silently never fires on the platform most of these
+ * shortcuts are copied from.
+ */
+
+import { isMacPlatform, isWindowsPlatform } from '@/shared/lib/util/platform';
+
+export interface KeyStroke {
+  /** `KeyboardEvent.code`, e.g. `KeyC`, `ArrowUp`, `Slash`, `Digit1`. */
+  code: string;
+  meta?: boolean;
+  ctrl?: boolean;
+  alt?: boolean;
+  shift?: boolean;
+}
+
+/** The subset of a keyboard event the matcher reads, so a test can fake one. */
+export interface KeyboardEventLike {
+  code: string;
+  key: string;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  altKey: boolean;
+  shiftKey: boolean;
+}
+
+export interface KeyBinding<Command extends string> {
+  command: Command;
+  /** What the palette and the tooltips call this command. */
+  label: string;
+  /** Chord on macOS. */
+  mac: KeyStroke;
+  /** Chord on Windows and Linux. */
+  other: KeyStroke;
+  /**
+   * Windows-only override. VS Code redoes with `Ctrl+Y` on Windows while Linux
+   * keeps `Ctrl+Shift+Z`, which one `other` stroke cannot express.
+   */
+  windows?: KeyStroke;
+}
+
+export function matchesStroke(stroke: KeyStroke, event: KeyboardEventLike): boolean {
+  return (
+    stroke.code === event.code &&
+    Boolean(stroke.meta) === event.metaKey &&
+    Boolean(stroke.ctrl) === event.ctrlKey &&
+    Boolean(stroke.alt) === event.altKey &&
+    Boolean(stroke.shift) === event.shiftKey
+  );
+}
+
+/** The chord a binding resolves to on the current platform. */
+export function strokeOf<C extends string>(binding: KeyBinding<C>, isMac: boolean): KeyStroke {
+  if (isMac) return binding.mac;
+  if (binding.windows && isWindowsPlatform()) return binding.windows;
+  return binding.other;
+}
+
+/**
+ * Codes whose printed name is not their `KeyboardEvent.code` suffix. Kept as a
+ * table because the alternative — a chain of `if`s — is what makes a label
+ * drift from the key it names.
+ */
+const KEY_LABEL_BY_CODE: Record<string, string> = {
+  Slash: '/',
+  Backslash: '\\',
+  Comma: ',',
+  Period: '.',
+  Semicolon: ';',
+  Quote: "'",
+  Backquote: '`',
+  Minus: '-',
+  Equal: '=',
+  BracketLeft: '[',
+  BracketRight: ']',
+  Space: 'Space',
+  Enter: 'Enter',
+  Escape: 'Esc',
+  Backspace: 'Backspace',
+  Delete: 'Del',
+  Tab: 'Tab',
+};
+
+/** `⌥⌘C` on macOS, `Alt+C` elsewhere. */
+export function describeStroke(stroke: KeyStroke, isMac: boolean): string {
+  const parts: string[] = [];
+  if (stroke.ctrl) parts.push(isMac ? '⌃' : 'Ctrl');
+  if (stroke.alt) parts.push(isMac ? '⌥' : 'Alt');
+  if (stroke.shift) parts.push(isMac ? '⇧' : 'Shift');
+  if (stroke.meta) parts.push(isMac ? '⌘' : 'Win');
+  parts.push(printableKey(stroke.code));
+  return isMac ? parts.join('') : parts.join('+');
+}
+
+/** The printed name of a physical key: `KeyC` → `C`, `Slash` → `/`, `ArrowUp` → `ArrowUp`. */
+export function printableKey(code: string): string {
+  if (KEY_LABEL_BY_CODE[code]) return KEY_LABEL_BY_CODE[code];
+  if (code.startsWith('Key')) return code.slice(3);
+  if (code.startsWith('Digit')) return code.slice(5);
+  return code;
+}
+
+/** The label a binding's shortcut gets in a tooltip or the palette. */
+export function describeBinding<C extends string>(binding: KeyBinding<C>, isMac: boolean = isMacPlatform()): string {
+  return describeStroke(strokeOf(binding, isMac), isMac);
+}
+
+/** The command `event` invokes, or null when no binding claims it. */
+export function resolveBinding<C extends string>(
+  bindings: readonly KeyBinding<C>[],
+  event: KeyboardEventLike,
+  isMac: boolean = isMacPlatform(),
+): C | null {
+  for (const binding of bindings) {
+    if (matchesStroke(strokeOf(binding, isMac), event)) return binding.command;
+  }
+  return null;
+}
+
+/** The binding for a command, for a call site that knows what it wants to label. */
+export function bindingFor<C extends string>(
+  bindings: readonly KeyBinding<C>[],
+  command: C,
+): KeyBinding<C> | undefined {
+  return bindings.find((binding) => binding.command === command);
+}

package/src/shared/lib/updates/popup-state.test.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The once-per-version announcement latch.
+ *
+ * The popup must appear exactly once per version, so the tests pin the three
+ * states that matter: no marker (first run → announce), a marker for another
+ * version (a newer release arrived → announce), and the same version (→ do not
+ * announce). `readAnnouncedVersion` has to treat a blank or non-string stored
+ * value as "never announced" rather than crashing, and `markAnnounced` must be
+ * readable back immediately — it is called when the popup is actually shown, so
+ * a write that does not reach the in-memory snapshot would re-announce the same
+ * version on the next read within the same session.
+ *
+ * The settings snapshot is primed per test; `markAnnounced` also POSTs through
+ * the shared settings client, whose fire-and-forget failure is irrelevant here.
+ */
+
+import { afterAll, beforeEach, describe, expect, test } from 'bun:test';
+
+import {
+  UPDATE_POPUP_OPEN_EVENT,
+  UPDATE_POPUP_SETTING_KEY,
+  UPDATE_REQUEST_EVENT,
+  markAnnounced,
+  readAnnouncedVersion,
+  shouldAnnounce,
+} from '@/shared/lib/updates/popup-state';
+import { primeKabmoSettings } from '@/shared/lib/settings/client';
+
+describe('popup-state constants', () => {
+  test('names the settings key and the two window events', () => {
+    expect(UPDATE_POPUP_SETTING_KEY).toBe('omp_update_popup_version');
+    expect(UPDATE_POPUP_OPEN_EVENT).toBe('omp:update-popup');
+    expect(UPDATE_REQUEST_EVENT).toBe('omp:update-request');
+  });
+});
+
+describe('readAnnouncedVersion', () => {
+  beforeEach(() => {
+    primeKabmoSettings({});
+  });
+
+  test('is null when nothing was ever announced', () => {
+    expect(readAnnouncedVersion()).toBeNull();
+  });
+
+  test('returns a stored version, trimmed', () => {
+    primeKabmoSettings({ [UPDATE_POPUP_SETTING_KEY]: '  3.8.0  ' });
+    expect(readAnnouncedVersion()).toBe('3.8.0');
+  });
+
+  test('treats a blank or non-string marker as never announced', () => {
+    primeKabmoSettings({ [UPDATE_POPUP_SETTING_KEY]: '' });
+    expect(readAnnouncedVersion()).toBeNull();
+    primeKabmoSettings({ [UPDATE_POPUP_SETTING_KEY]: '   ' });
+    expect(readAnnouncedVersion()).toBeNull();
+    primeKabmoSettings({ [UPDATE_POPUP_SETTING_KEY]: 42 });
+    expect(readAnnouncedVersion()).toBeNull();
+  });
+});
+
+describe('shouldAnnounce', () => {
+  test('announces an unseen version and stays quiet on the seen one', () => {
+    expect(shouldAnnounce('3.8.0', null)).toBe(true);
+    expect(shouldAnnounce('3.8.0', '3.8.0')).toBe(false);
+    expect(shouldAnnounce('3.9.0', '3.8.0')).toBe(true);
+  });
+
+  test('never announces without a version to name', () => {
+    expect(shouldAnnounce(null, null)).toBe(false);
+    expect(shouldAnnounce(null, '3.8.0')).toBe(false);
+    expect(shouldAnnounce('', '3.8.0')).toBe(false);
+  });
+
+  test('defaults the marker to the stored setting', () => {
+    primeKabmoSettings({ [UPDATE_POPUP_SETTING_KEY]: '3.8.0' });
+    expect(shouldAnnounce('3.8.0')).toBe(false);
+    expect(shouldAnnounce('3.9.0')).toBe(true);
+  });
+});
+
+describe('markAnnounced', () => {
+  test('records the version so the next read sees it', () => {
+    primeKabmoSettings({});
+    markAnnounced('3.9.0');
+    expect(readAnnouncedVersion()).toBe('3.9.0');
+    expect(shouldAnnounce('3.9.0')).toBe(false);
+  });
+});
+
+/** The snapshot is module state shared across the whole `bun test` process. */
+afterAll(() => {
+  primeKabmoSettings({});
+});

package/src/shared/lib/updates/popup-state.ts

@@ -0,0 +1,67 @@
+/**
+ * The "already shown" latch for the update popup.
+ *
+ * The popup may appear ONCE PER VERSION, not once per installation: the marker
+ * holds the newest version that has already been announced, so the next release
+ * announces itself while the current one never interrupts a second time. A
+ * permanent boolean would make the feature self-destruct after the first update
+ * it ever offered, and a per-page-load flag would re-announce the same version
+ * on every reload — which is what the user sees, so the durable copy is what
+ * matters.
+ *
+ * The store is `app_settings` through the shared settings client, deliberately:
+ * this repository has no localStorage (SQLite is the single source of truth, see
+ * `@/shared/lib/settings/client`), and the marker is per INSTALL, not per session
+ * — so it does not belong in `session_ui_state` beside a session's layout.
+ */
+
+import { readKabmoSetting, writeSetting } from '@/shared/lib/settings/client';
+
+/** Top-level `app_settings` key holding the announced version. */
+export const UPDATE_POPUP_SETTING_KEY = 'omp_update_popup_version';
+
+/**
+ * Window event that opens the popup on demand.
+ *
+ * The automatic announcement is once per version; the About modal's "What's
+ * new" is the way back to the same notes afterwards, and it reaches the popup
+ * through this event rather than through a second copy of its state. The event
+ * is named for what it does, not for the component that listens.
+ */
+export const UPDATE_POPUP_OPEN_EVENT = 'omp:update-popup';
+
+/**
+ * Window event that opens the About modal and starts Kabmo update.
+ *
+ * The popup's "Update now" does not run the update itself: the About modal is
+ * where an update is driven from, and it owns the live output and the per-target
+ * rows. So the popup announces, then hands the run over — one dialog owns the
+ * run, and the popup cannot leave a second copy of it behind.
+ */
+export const UPDATE_REQUEST_EVENT = 'omp:update-request';
+
+/**
+ * The version already announced on this install, or null.
+ *
+ * Read from the boot snapshot, so the gate costs no request: the popup's whole
+ * purpose is to be decided before any network call is made for it.
+ */
+export function readAnnouncedVersion(): string | null {
+  const stored = readKabmoSetting<string>(UPDATE_POPUP_SETTING_KEY);
+  return typeof stored === 'string' && stored.trim().length > 0 ? stored.trim() : null;
+}
+
+/**
+ * Whether this version still owes the user an announcement. An absent marker
+ * shows (the common first run), a marker for another version shows (a newer
+ * release arrived), and the same version does not.
+ */
+export function shouldAnnounce(version: string | null, announced = readAnnouncedVersion()): boolean {
+  if (!version) return false;
+  return version !== announced;
+}
+
+/** Record the version as announced. Called when the popup is actually SHOWN. */
+export function markAnnounced(version: string): void {
+  writeSetting(UPDATE_POPUP_SETTING_KEY, version);
+}

package/src/shared/lib/updates/popup.test.ts

@@ -0,0 +1,30 @@
+/**
+ * The once-per-version latch for the update popup.
+ *
+ * It decides something the user sees: whether the dialog interrupts at all. The
+ * range math it used to pin lives beside the parser it belongs to — see
+ * `@/server/lib/updates/changelog.test.ts`.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { shouldAnnounce } from '@/shared/lib/updates/popup-state';
+
+describe('shouldAnnounce', () => {
+  test('announces a version that has never been shown', () => {
+    expect(shouldAnnounce('3.8.0', null)).toBe(true);
+  });
+
+  test('does not re-announce the version already shown', () => {
+    expect(shouldAnnounce('3.8.0', '3.8.0')).toBe(false);
+  });
+
+  test('announces the next release after one was shown', () => {
+    expect(shouldAnnounce('3.9.0', '3.8.0')).toBe(true);
+  });
+
+  test('never announces without a version to name', () => {
+    expect(shouldAnnounce(null, null)).toBe(false);
+    expect(shouldAnnounce('', '3.8.0')).toBe(false);
+  });
+});