synabun 1.3.0 → 2.0.0

package/neural-interface/lib/style-guide/tokens.js

@@ -0,0 +1,170 @@
+// ═══════════════════════════════════════════
+// SynaBun — Style Guide token helpers
+// ═══════════════════════════════════════════
+//
+// What the DESIGN.md renderer and the three exporters share, so one token has one
+// name everywhere: `primary-500`, `on-primary`, `--color-on-primary`. Pure, no I/O.
+
+import { parseColor } from './color.js';
+import { THEMES, isAlias, parseAlias, resolveAlias, resolveColor, resolveText } from './schema.js';
+
+/** onPrimary → on-primary, surfaceRaised → surface-raised. */
+export function roleName(role) {
+  return String(role).replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+/** on-primary → onPrimary (the importer's way back). */
+export function roleFromName(name) {
+  return String(name).replace(/-([a-z0-9])/g, (_, ch) => ch.toUpperCase());
+}
+
+/** The themes a guide ships, default first. */
+export function themesOf(config) {
+  const supports = (config.colors?.themes?.supports || ['light']).filter((theme) => THEMES.includes(theme));
+  const first = supports.includes(config.colors?.themes?.default) ? config.colors.themes.default : supports[0] || 'light';
+  return [first, ...supports.filter((theme) => theme !== first)];
+}
+
+/** A font-family value: `"Space Grotesk", system-ui, sans-serif`. */
+export function fontStack(font) {
+  if (!font) return '';
+  const family = String(font.family || '').trim();
+  const quoted = /^[a-zA-Z][a-zA-Z0-9-]*$/.test(family) ? family : `"${family.replace(/["\\]/g, '')}"`;
+  const fallback = String(font.fallback || '').trim();
+  return fallback ? `${quoted}, ${fallback}` : quoted;
+}
+
+/** The same stack as a list (DTCG fontFamily). */
+export function fontList(font) {
+  if (!font) return [];
+  return [String(font.family || '').trim(), ...String(font.fallback || '').split(',').map((part) => part.trim().replace(/^["']|["']$/g, ''))].filter(Boolean);
+}
+
+/** The font a text style uses (a style naming a missing `display` falls back to heading, then body). */
+export function fontOf(config, style) {
+  const fonts = config.typography.fonts;
+  return fonts[style.font] || (style.font === 'display' ? fonts.heading : null) || fonts.body;
+}
+
+/** The key of that font in `typography.fonts` (heading | body | mono | display). */
+export function fontKeyOf(config, style) {
+  if (config.typography.fonts[style.font]) return style.font;
+  return style.font === 'display' ? 'heading' : 'body';
+}
+
+/** [{ role, name, raw, value (hex or null), alias ({group, key} or null) }] for one theme. */
+export function semanticEntries(config, theme) {
+  return Object.entries(config.colors.semantic[theme] || {}).map(([role, raw]) => ({
+    role, name: roleName(role), raw, value: resolveColor(config, raw, { theme }), alias: isAlias(raw) ? parseAlias(raw) : null,
+  }));
+}
+
+/** px → rem at 16px, trimmed: 24 → "1.5rem". */
+export function rem(px) {
+  return `${Math.round((Number(px) / 16) * 10000) / 10000}rem`;
+}
+
+export function px(value) {
+  return Number(value) === 0 ? '0' : `${value}px`;
+}
+
+/** A number without float noise. */
+export function tidy(value, digits = 4) {
+  const f = 10 ** digits;
+  return Math.round(Number(value) * f) / f;
+}
+
+/**
+ * A CSS box-shadow value → [{ inset, offsetX, offsetY, blur, spread, color }] (px numbers, any CSS color),
+ * [] for "none", null when it cannot be read.
+ */
+export function parseShadow(css) {
+  const text = String(css ?? '').trim();
+  if (!text || text === 'none') return [];
+  const layers = [];
+  let depth = 0; let start = 0;
+  for (let i = 0; i <= text.length; i++) {
+    const ch = text[i];
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    else if ((ch === ',' && depth === 0) || i === text.length) { layers.push(text.slice(start, i).trim()); start = i + 1; }
+  }
+  const out = [];
+  for (const layer of layers) {
+    if (!layer) continue;
+    let rest = layer;
+    let color = null;
+    const fn = /(rgba?|hsla?|oklch)\([^)]*\)/i.exec(rest);
+    if (fn) { color = fn[0]; rest = rest.replace(fn[0], ' '); }
+    const parts = rest.split(/\s+/).filter(Boolean);
+    let inset = false;
+    const lengths = [];
+    for (const part of parts) {
+      if (part === 'inset') { inset = true; continue; }
+      if (/^-?(\d+\.?\d*|\.\d+)(px)?$/.test(part)) { lengths.push(parseFloat(part)); continue; }
+      if (!color && parseColor(part)) { color = part; continue; }
+      return null;
+    }
+    if (lengths.length < 2 || lengths.length > 4 || (lengths[2] ?? 0) < 0 || (color && !parseColor(color))) return null;
+    out.push({ inset, offsetX: lengths[0], offsetY: lengths[1], blur: lengths[2] ?? 0, spread: lengths[3] ?? 0, color: color || '#000000' });
+  }
+  return out;
+}
+
+const EASING_KEYWORDS = Object.freeze({
+  linear: [0, 0, 1, 1], ease: [0.25, 0.1, 0.25, 1], 'ease-in': [0.42, 0, 1, 1], 'ease-out': [0, 0, 0.58, 1], 'ease-in-out': [0.42, 0, 0.58, 1],
+});
+
+/** A CSS easing → [x1, y1, x2, y2], or null (steps(), linear(), anything else). */
+export function parseEasing(css) {
+  const text = String(css ?? '').trim().toLowerCase();
+  if (EASING_KEYWORDS[text]) return [...EASING_KEYWORDS[text]];
+  const match = /^cubic-bezier\(([^)]+)\)$/.exec(text);
+  if (!match) return null;
+  const values = match[1].split(',').map((part) => Number(part.trim()));
+  return values.length === 4 && values.every(Number.isFinite) && values[0] >= 0 && values[0] <= 1 && values[2] >= 0 && values[2] <= 1 ? values : null;
+}
+
+/** Where a component token's alias points, for readers that want the name and the value. */
+export function describeAlias(config, value, { theme = null } = {}) {
+  if (!isAlias(value)) return null;
+  const hit = resolveAlias(config, value, { theme });
+  return hit.ok ? hit : null;
+}
+
+/**
+ * Every token of one theme with its final value, no aliases left: what an agent or a script reads when it
+ * wants numbers, not a file format. { theme, colors (roles), palettes, status, gradients, fonts, text,
+ * spacing, radius, radiusRoles, borders, shadows, durations, easings, breakpoints, zIndex, container, grid }
+ */
+export function resolvedTokens(config, theme = null) {
+  const themes = themesOf(config);
+  const name = themes.includes(theme) ? theme : themes[0];
+  const colors = {};
+  for (const entry of semanticEntries(config, name)) colors[entry.role] = entry.value;
+  const text = {};
+  for (const [id, style] of Object.entries(config.typography.styles)) {
+    text[id] = { fontFamily: fontStack(fontOf(config, style)), size: style.size, mobileSize: style.mobileSize, weight: style.weight, lineHeight: style.lineHeight, letterSpacing: style.letterSpacing, transform: style.transform };
+  }
+  return {
+    theme: name,
+    themes,
+    colors,
+    palettes: Object.fromEntries(Object.entries(config.colors.palettes).map(([key, palette]) => [key, { ...palette.steps }])),
+    status: { ...config.colors.status },
+    gradients: Object.fromEntries(config.colors.gradients.map((gradient) => [gradient.name, resolveText(config, gradient.css, { theme: name }).text])),
+    fonts: Object.fromEntries(Object.entries(config.typography.fonts).filter(([, font]) => font).map(([key, font]) => [key, fontStack(font)])),
+    text,
+    spacing: { ...config.layout.spacing.scale },
+    radius: { ...config.shape.radius },
+    radiusRoles: Object.fromEntries(Object.entries(config.shape.radiusRoles).map(([role, key]) => [role, config.shape.radius[key]])),
+    borders: { ...config.shape.borders },
+    shadows: Object.fromEntries(Object.entries(config.shape.elevation).map(([key, level]) => [key, level.shadow])),
+    durations: { ...config.motion.durations },
+    easings: { ...config.motion.easings },
+    breakpoints: { ...config.layout.breakpoints },
+    zIndex: { ...config.layout.zIndex },
+    container: { ...config.layout.container },
+    grid: { ...config.layout.grid },
+  };
+}

package/neural-interface/lib/synabun-update-plan.js

@@ -0,0 +1,324 @@
+// What SynaBun's own update check found, and what click-to-update does about
+// it. Pure: the server fetches the npm registry document and the GitHub
+// releases and detects how SynaBun was installed; this module decides
+// (tests/synabun-update-plan.test.mjs). Version ordering comes from
+// synabun-version.js and is not repeated here.
+//
+// One rule ties the two halves together: the version the check selected and
+// showed is the version the plan installs. The plan pins it (`synabun@2.0.1`)
+// and never names a dist-tag, so a tag that moves between the check and the
+// click, a `latest` that points at an older or date-style release, or a beta
+// channel cannot make npm install anything else. A version npm does not have is
+// never auto-installed: that plan is a manual one and says why.
+
+import {
+  parseSemver, compareSynabunVersion, synabunVersionNewer, synabunReleaseChannel, formatSynabunVersion,
+  isDateStyleSynabunVersion,
+} from './synabun-version.js';
+
+/** npm dist-tags read as the prerelease channel, in order of preference. */
+export const SYNABUN_NPM_PRERELEASE_TAGS = Object.freeze(['beta', 'next', 'rc', 'alpha']);
+
+const stripTagPrefix = tag => String(tag).replace(/^v\.?/, '');
+
+/**
+ * True when the npm registry document lists `version` as a published version
+ * (its `versions` map, or a dist-tag pointing at it).
+ */
+export function npmHasSynabunVersion(npmDocument, version) {
+  const wanted = formatSynabunVersion(version);
+  if (!wanted || !npmDocument || typeof npmDocument !== 'object') return false;
+  const versions = npmDocument.versions;
+  if (versions && typeof versions === 'object' && Object.hasOwn(versions, wanted)) return true;
+  const tags = npmDocument['dist-tags'];
+  if (tags && typeof tags === 'object') {
+    for (const value of Object.values(tags)) if (formatSynabunVersion(value) === wanted) return true;
+  }
+  return false;
+}
+
+/** The dist-tag that points at `version`, `latest` first, or null. */
+function npmTagFor(npmDocument, version) {
+  const wanted = formatSynabunVersion(version);
+  const tags = npmDocument?.['dist-tags'];
+  if (!wanted || !tags || typeof tags !== 'object') return null;
+  for (const name of ['latest', ...SYNABUN_NPM_PRERELEASE_TAGS]) {
+    if (tags[name] && formatSynabunVersion(tags[name]) === wanted) return name;
+  }
+  return null;
+}
+
+/**
+ * The stable release npm offers. That is `latest`, unless `latest` cannot be
+ * one: it is a prerelease, it is not a version, or it is a date-style release
+ * while a semver-era stable release is published (a tag left behind by the
+ * scheme change). Then it is the newest stable release in `versions`, which
+ * no dist-tag names.
+ * @returns {{version: string|null, tag: 'latest'|null}}
+ */
+function npmStableOffer(npmDocument) {
+  const doc = npmDocument && typeof npmDocument === 'object' ? npmDocument : {};
+  const latest = doc['dist-tags']?.latest || null;
+  let newestPublished = null;
+  const versions = doc.versions && typeof doc.versions === 'object' ? Object.keys(doc.versions) : [];
+  for (const candidate of versions) {
+    if (!parseSemver(candidate) || synabunReleaseChannel(candidate) !== 'stable') continue;
+    if (!newestPublished || compareSynabunVersion(candidate, newestPublished) > 0) newestPublished = candidate;
+  }
+  const leftBehind = isDateStyleSynabunVersion(latest) && !!newestPublished && !isDateStyleSynabunVersion(newestPublished);
+  if (parseSemver(latest) && synabunReleaseChannel(latest) === 'stable' && !leftBehind) return { version: latest, tag: 'latest' };
+  return { version: newestPublished, tag: null };
+}
+
+/**
+ * Reads the two responses of the update check.
+ *
+ * @param {object} input
+ * @param {string|null} input.current         installed version (package.json)
+ * @param {object|null} [input.npmDocument]   the full registry document, or null when the fetch failed
+ * @param {object|object[]|null} [input.githubReleases]  `/releases/latest` (one object) or `/releases` (a list), or null
+ * @returns the fields of the update cache: channel, what each source offers,
+ *   whether either is newer, and `latest`, the one version the UI shows and the
+ *   plan installs (`targetOnNpm` says whether npm can install it).
+ *   `npmLatestStable` / `npmLatestBeta` are the dist-tags as published;
+ *   `npmLatest` is the version npm offers this install's channel.
+ */
+export function selectSynabunUpdate({ current = null, npmDocument = null, githubReleases = null } = {}) {
+  // Any suffix on a semver-era version is a prerelease (`2.0.0-1`,
+  // `2.0.0-beta.1`). Only the old date-style iterations (`2026.4.26-1`) were
+  // stable releases with a suffix.
+  const installedChannel = synabunReleaseChannel(current);
+
+  const tags = (npmDocument && typeof npmDocument === 'object' && npmDocument['dist-tags']) || {};
+  const npmLatestStable = tags.latest || null;
+  let npmLatestBeta = null;
+  let npmLatestBetaTag = null;
+  for (const tagName of SYNABUN_NPM_PRERELEASE_TAGS) {
+    if (tags[tagName]) {
+      npmLatestBeta = tags[tagName];
+      npmLatestBetaTag = tagName;
+      break;
+    }
+  }
+
+  let gitLatestRaw = null;
+  if (Array.isArray(githubReleases)) {
+    // /releases: the newest non-draft entry whose tag is a version. Only a
+    // prerelease install asks for the list, so prereleases are included.
+    let best = null;
+    for (const release of githubReleases) {
+      if (release?.draft) continue;
+      const tag = release?.tag_name || release?.name || '';
+      const parsed = parseSemver(tag);
+      if (!parsed) continue;
+      if (!best || compareSynabunVersion(parsed, best.parsed) > 0) best = { tag, parsed };
+    }
+    gitLatestRaw = best?.tag || null;
+  } else if (githubReleases && typeof githubReleases === 'object') {
+    // /releases/latest: a single object.
+    gitLatestRaw = githubReleases.tag_name || githubReleases.name || null;
+  }
+  const gitLatest = gitLatestRaw ? stripTagPrefix(gitLatestRaw) : null;
+  // The channel rule holds for both sources: a stable install is only offered
+  // a stable release. `/releases/latest` skips prereleases, so this only
+  // matters for a release that was published without the prerelease flag.
+  const gitOffer = gitLatest && !(installedChannel === 'stable' && synabunReleaseChannel(gitLatest) === 'prerelease')
+    ? gitLatest
+    : null;
+
+  // Channel-aware npm target:
+  //  - prerelease install: whichever of (stable, beta) is newest. Either is
+  //    newer than the installed version; a stable release that supersedes the
+  //    beta is offered on purpose.
+  //  - stable install: only stable. A beta would look like a downgrade, so
+  //    the stable offer is never a prerelease, whatever `latest` points at.
+  const stableOffer = npmStableOffer(npmDocument);
+  const betaOffer = parseSemver(npmLatestBeta) ? npmLatestBeta : null;
+  let npmLatest = null;
+  let npmLatestTag = null;
+  if (installedChannel === 'prerelease') {
+    if (stableOffer.version && betaOffer) {
+      if (compareSynabunVersion(betaOffer, stableOffer.version) > 0) {
+        npmLatest = betaOffer;
+        npmLatestTag = npmLatestBetaTag;
+      } else {
+        npmLatest = stableOffer.version;
+        npmLatestTag = stableOffer.tag;
+      }
+    } else {
+      npmLatest = stableOffer.version || betaOffer;
+      npmLatestTag = stableOffer.version ? stableOffer.tag : (betaOffer ? npmLatestBetaTag : null);
+    }
+  } else {
+    npmLatest = stableOffer.version;
+    npmLatestTag = stableOffer.tag;
+  }
+
+  // synabunVersionNewer, not semverNewer: a date-style release (2026.9.5) is
+  // never an update for a semver-era install (2.0.0), whatever a registry tag
+  // or a GitHub release still points at.
+  const npmUpdateAvailable = !!(npmLatest && synabunVersionNewer(current, npmLatest));
+  const gitUpdateAvailable = !!(gitOffer && synabunVersionNewer(current, gitOffer));
+  const updateAvailable = npmUpdateAvailable || gitUpdateAvailable;
+
+  // The newer of the two sources, in npm's spelling. This is the one version
+  // the UI shows as the target and the install plan pins.
+  let newest = null;
+  if (npmLatest && gitOffer) {
+    newest = compareSynabunVersion(npmLatest, gitOffer) >= 0 ? npmLatest : gitOffer;
+  } else {
+    newest = npmLatest || gitOffer;
+  }
+  const latest = formatSynabunVersion(newest) || newest;
+
+  let source = null;
+  if (npmUpdateAvailable && gitUpdateAvailable) source = 'both';
+  else if (npmUpdateAvailable)                   source = 'npm';
+  else if (gitUpdateAvailable)                   source = 'github';
+
+  return {
+    installedChannel,
+    npmLatestStable,
+    npmLatestBeta,
+    npmLatestTag,
+    npmLatest,
+    gitLatest,
+    gitLatestRaw,
+    latest,
+    npmUpdateAvailable,
+    gitUpdateAvailable,
+    updateAvailable,
+    source,
+    npmChecked: !!npmDocument && typeof npmDocument === 'object',
+    targetOnNpm: updateAvailable ? npmHasSynabunVersion(npmDocument, latest) : false,
+    targetNpmTag: updateAvailable ? npmTagFor(npmDocument, latest) : null,
+  };
+}
+
+/**
+ * The click names the version its page showed. The server's plan can be newer
+ * than that page (another tab, or the hourly refresh, re-ran the check), and
+ * running it would install a version the user never saw. Returns the refusal
+ * to send (HTTP 409), or null when the click may proceed. A page that sends no
+ * target (an older one) is let through.
+ * @returns {{code: 'target-changed', error: string} | null}
+ */
+export function refuseStaleUpdateClick(installPlan, shownTarget) {
+  const shown = typeof shownTarget === 'string' ? formatSynabunVersion(shownTarget) : null;
+  if (!shown || !installPlan || shown === installPlan.target) return null;
+  return {
+    code: 'target-changed',
+    error: `The update on screen (v${shown}) is out of date: SynaBun now offers v${installPlan.target}. Nothing was installed. Review the new version and run the update again.`,
+  };
+}
+
+/**
+ * The server-owned action for click-to-update, or null when there is no update.
+ *
+ * - An npm install whose target npm has: `canAutoUpdate: true` with
+ *   `installSpec` pinned to that exact version.
+ * - An npm install whose target is only a GitHub release: a manual plan
+ *   (`reason: 'not-on-npm'`, or `'npm-unreachable'` when the registry could not
+ *   be asked). Nothing else is installed in its place.
+ * - Any other kind of install (a checkout): a manual plan
+ *   (`reason: 'not-npm-install'`), as before.
+ *
+ * @param {object} input the fields of selectSynabunUpdate() plus:
+ * @param {string|null} input.current
+ * @param {{kind: string, remote?: string|null}|null} input.installSource  how SynaBun was installed
+ * @param {string} input.repoUrl  the GitHub repository URL
+ */
+export function buildSynabunInstallPlan({
+  current = null,
+  installedChannel = 'stable',
+  latest = null,
+  updateAvailable = false,
+  npmChecked = true,
+  targetOnNpm = false,
+  targetNpmTag = null,
+  gitLatestRaw = null,
+  installSource = null,
+  repoUrl,
+} = {}) {
+  if (!updateAvailable) return null;
+
+  const kind = installSource?.kind || 'local';
+  const version = formatSynabunVersion(latest);
+  const target = version || latest;
+
+  if (kind === 'packaged-app') {
+    // A packaged application carries its own runtime and dependencies: npm and
+    // git never write inside it. A newer build is installed over it instead.
+    const releasesUrl = `${repoUrl}/releases`;
+    return {
+      source: 'github',
+      installSource: kind,
+      canAutoUpdate: false,
+      reason: 'packaged-app',
+      current,
+      target,
+      channel: installedChannel,
+      displayCommand: releasesUrl,
+      openUrl: releasesUrl,
+      manualCommand: null,
+      manualHint: `This copy of SynaBun is a packaged application, so v${target} is installed by replacing it with the newer build, not from inside the app. Nothing was installed. Get the build for your system from the releases page and install it over this one; your data stays where it is.`,
+    };
+  }
+
+  if (kind !== 'npm-global') {
+    const clonedHint = kind === 'github-clone'
+      ? 'This SynaBun install is a GitHub checkout. Open the repository to pull or reinstall from the correct source.'
+      : 'This SynaBun install was not detected as npm. Open the repository for the correct update path.';
+    return {
+      source: 'github',
+      installSource: kind,
+      canAutoUpdate: false,
+      reason: 'not-npm-install',
+      current,
+      target,
+      channel: installedChannel,
+      displayCommand: repoUrl,
+      openUrl: repoUrl,
+      manualCommand: kind === 'github-clone' ? 'git pull --ff-only' : null,
+      manualHint: clonedHint,
+      remote: installSource?.remote,
+    };
+  }
+
+  if (!version || !targetOnNpm) {
+    // Newer on GitHub only. Installing whatever npm's `latest` points at would
+    // reinstall the current version, or an older one, under the new version's
+    // name, so this is a manual update until npm has the release.
+    const releaseUrl = gitLatestRaw && version && formatSynabunVersion(gitLatestRaw) === version
+      ? `${repoUrl}/releases/tag/${encodeURIComponent(gitLatestRaw)}`
+      : `${repoUrl}/releases`;
+    return {
+      source: 'github',
+      installSource: kind,
+      canAutoUpdate: false,
+      reason: npmChecked ? 'not-on-npm' : 'npm-unreachable',
+      current,
+      target,
+      channel: installedChannel,
+      displayCommand: releaseUrl,
+      openUrl: releaseUrl,
+      manualCommand: null,
+      manualHint: npmChecked
+        ? `SynaBun v${target} is published on GitHub but is not on npm yet, so it cannot be installed automatically. Nothing was installed. Check for updates again later, or open the release on GitHub.`
+        : `SynaBun could not reach npm to confirm that v${target} is published there, so it cannot be installed automatically. Nothing was installed. Check for updates again, or open the release on GitHub.`,
+    };
+  }
+
+  const installSpec = `synabun@${version}`;
+  return {
+    source: 'npm',
+    installSource: kind,
+    canAutoUpdate: true,
+    current,
+    target: version,
+    channel: installedChannel,
+    installSpec,
+    displayCommand: `npm i -g ${installSpec}`,
+    npmTag: targetNpmTag,
+  };
+}

package/neural-interface/lib/synabun-version.js

@@ -0,0 +1,179 @@
+// Version parsing and ordering for SynaBun's update check and the CLI tool
+// version checks. Pure: no I/O, so the rules below are unit-tested directly
+// (tests/synabun-version.test.mjs).
+//
+// Two schemes exist. Every SynaBun release before 2.0.0 was date-style
+// (2026.4.26, 2026.9.5), and a numeric-only suffix on one of those was a
+// POST-release iteration: 2026.4.26-1 is the first patch published after
+// 2026.4.26, shipped as `latest` on npm. From 2.0.0 on, versions are plain
+// semver, where any suffix after `-` is a PRE-release (2.0.0-1 and
+// 2.0.0-beta.1 both come before 2.0.0). The date-style rule applies only to a
+// version whose major is a year.
+
+/** First major of the date-style scheme. No semver-era release will reach it. */
+export const SYNABUN_DATE_VERSION_MIN_MAJOR = 2000;
+
+// The whole string, after the optional `v` / `v.` prefix: three numbers, an
+// optional prerelease (dot-separated identifiers of letters, digits and
+// hyphens, none empty), optional build metadata, and nothing else. Anchored at
+// both ends, so "2.0.1junk", "2.0.1-" and "2.0.1-beta..1" are not versions.
+const VERSION_RE = /^(\d{1,15})\.(\d{1,15})\.(\d{1,15})(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+
+// Structured parse of one whole version string, or null:
+//   "2.0.0"              -> { major:2, minor:0, patch:0, pre:null, iter:null, build:null }
+//   "v2.0.0-beta.1"      -> { major:2, minor:0, patch:0, pre:"beta.1", iter:null, build:null }
+//   "2.0.0-1"            -> { major:2, minor:0, patch:0, pre:"1", iter:null, build:null }  (a prerelease)
+//   "2.0.1+build.7"      -> { major:2, minor:0, patch:1, pre:null, iter:null, build:"build.7" }
+//   "v.2026.09.05"       -> { major:2026, minor:9, patch:5, pre:null, iter:null, build:null }
+//   "2026.4.20-2"        -> { major:2026, minor:4, patch:20, pre:"2", iter:2, build:null }   (a post-release iteration)
+//   "2026.4.26-beta.3"   -> { major:2026, minor:4, patch:26, pre:"beta.3", iter:null, build:null }
+//
+// `iter` is set only for a date-style version with a numeric-only suffix.
+// A zero-padded part is read as its number (git tags such as v.2026.09.05).
+// Callers hand over a version and nothing around it: CLI output such as
+// "2.1.224 (Claude Code)" goes through the server's parseVersion() first.
+export function parseSemver(raw) {
+  if (raw == null) return null;
+  const s = String(raw).trim().replace(/^v\.?/, '');
+  const m = VERSION_RE.exec(s);
+  if (!m) return null;
+  const major = +m[1];
+  const dateStyle = major >= SYNABUN_DATE_VERSION_MIN_MAJOR;
+  const pre = m[4] || null;
+  const iter = dateStyle && pre && /^\d+$/.test(pre) ? Number(pre) : null;
+  return {
+    major,
+    minor: +m[2],
+    patch: +m[3],
+    pre,
+    iter,
+    build: m[5] || null,
+  };
+}
+
+// Precedence, semver §11:
+//   1.0.0-1 < 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0
+// plus the date-style iteration (`iter`, see parseSemver), which is newer than
+// its release:
+//   2026.4.26-beta.3 < 2026.4.26 < 2026.4.26-1 < 2026.4.26-2
+// Build metadata never takes part. Returns negative if a<b, positive if a>b,
+// 0 if equal. Accepts strings or parsed objects.
+export function compareSemver(a, b) {
+  const pa = (a && typeof a === 'object' && 'major' in a) ? a : parseSemver(a);
+  const pb = (b && typeof b === 'object' && 'major' in b) ? b : parseSemver(b);
+  if (!pa && !pb) return 0;
+  if (!pa) return -1;
+  if (!pb) return 1;
+  if (pa.major !== pb.major) return pa.major - pb.major;
+  if (pa.minor !== pb.minor) return pa.minor - pb.minor;
+  if (pa.patch !== pb.patch) return pa.patch - pb.patch;
+  // Equal x.y.z. Order from oldest → newest:
+  //   prerelease  <  no-suffix release  <  date-style numeric iteration
+  if (!pa.pre && !pb.pre) return 0;
+  // Date-style iterations are POST-release: always newer than no-suffix and
+  // newer than prereleases.
+  if (pa.iter != null && pb.iter == null) return  1;
+  if (pa.iter == null && pb.iter != null) return -1;
+  if (pa.iter != null && pb.iter != null) return pa.iter - pb.iter;
+  // Neither side is an iteration. Semver §11.3: a release is greater than its
+  // prereleases.
+  if (!pa.pre &&  pb.pre) return  1;
+  if ( pa.pre && !pb.pre) return -1;
+  // Both are prereleases — compare identifiers per semver §11.4.
+  const ia = pa.pre.split('.');
+  const ib = pb.pre.split('.');
+  const len = Math.max(ia.length, ib.length);
+  for (let i = 0; i < len; i++) {
+    if (i >= ia.length) return -1; // shorter set has lower precedence
+    if (i >= ib.length) return  1;
+    const xa = ia[i], xb = ib[i];
+    const na = /^\d+$/.test(xa), nb = /^\d+$/.test(xb);
+    if (na && nb) {
+      const da = +xa, db = +xb;
+      if (da !== db) return da - db;
+    } else if (na && !nb) {
+      return -1; // numeric < alphanumeric
+    } else if (!na && nb) {
+      return  1;
+    } else {
+      if (xa !== xb) return xa < xb ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+export function semverNewer(a, b) {
+  // True iff b is strictly newer than a. Falls back to false if either side
+  // can't be parsed — same defensive contract as the prior implementation.
+  if (a == null || b == null) return false;
+  const pa = parseSemver(a), pb = parseSemver(b);
+  if (!pa || !pb) return false;
+  return compareSemver(pa, pb) < 0;
+}
+
+// ── SynaBun's own release scheme ──
+//
+// Plain semver ordering puts every date-style release ABOVE 2.x (2026 > 2).
+// Without the rule below a 2.x install would be offered the last date-style
+// release as an "update", and the click-to-update flow would act on it.
+//
+// The rule: a date-style version is always older than a semver-era one. Two
+// versions of the same scheme compare by compareSemver.
+//
+// Only SynaBun's own versions go through these functions. The CLI tools
+// SynaBun watches (Claude Code, Codex, Gemini, OpenCode) keep plain
+// compareSemver / semverNewer.
+
+/** True for a date-style SynaBun version (`2026.9.5`, `v.2026.07.34`, `2026.4.26-1`). */
+export function isDateStyleSynabunVersion(version) {
+  const parsed = (version && typeof version === 'object' && 'major' in version) ? version : parseSemver(version);
+  return !!parsed && parsed.major >= SYNABUN_DATE_VERSION_MIN_MAJOR;
+}
+
+/**
+ * The canonical spelling of a version, which is how npm names a published one:
+ * no `v` / `v.` prefix, no zero padding, no build metadata
+ * (`v.2026.09.05` -> `2026.9.5`, `v2.0.1+build.7` -> `2.0.1`). Null when the
+ * input is not a version.
+ * @returns {string | null}
+ */
+export function formatSynabunVersion(version) {
+  const parsed = (version && typeof version === 'object' && 'major' in version) ? version : parseSemver(version);
+  if (!parsed) return null;
+  return `${parsed.major}.${parsed.minor}.${parsed.patch}${parsed.pre ? `-${parsed.pre}` : ''}`;
+}
+
+/**
+ * The channel a SynaBun version belongs to. Semver era: any suffix is a
+ * prerelease (`2.0.0-1`, `2.0.0-beta.1`). Date-style: a numeric iteration
+ * (`2026.4.26-1`) was a stable release, only an alpha / beta / rc suffix was a
+ * prerelease. A string that is not a version counts as stable.
+ * @returns {'stable' | 'prerelease'}
+ */
+export function synabunReleaseChannel(version) {
+  const parsed = (version && typeof version === 'object' && 'major' in version) ? version : parseSemver(version);
+  return parsed && parsed.pre && parsed.iter == null ? 'prerelease' : 'stable';
+}
+
+/**
+ * compareSemver for SynaBun's own versions: a date-style version sorts below
+ * every semver-era version. Negative if a<b, positive if a>b, 0 if equal.
+ */
+export function compareSynabunVersion(a, b) {
+  const pa = (a && typeof a === 'object' && 'major' in a) ? a : parseSemver(a);
+  const pb = (b && typeof b === 'object' && 'major' in b) ? b : parseSemver(b);
+  if (pa && pb) {
+    const da = isDateStyleSynabunVersion(pa);
+    const db = isDateStyleSynabunVersion(pb);
+    if (da !== db) return da ? -1 : 1;
+  }
+  return compareSemver(pa, pb);
+}
+
+/** True iff SynaBun version b is strictly newer than a; false when either does not parse. */
+export function synabunVersionNewer(a, b) {
+  if (a == null || b == null) return false;
+  const pa = parseSemver(a), pb = parseSemver(b);
+  if (!pa || !pb) return false;
+  return compareSynabunVersion(pa, pb) < 0;
+}