bridgerator 1.0.7 → 1.1.0

package/src/photos-tool.mjs

@@ -0,0 +1,187 @@
+// LOGIC: see critical-logic/bridge.md ("Extra tools" / photos). Photo details (EXIF), smaller / converted
+// copies and renaming by the date taken — with the imaging built into Windows (photos.ps1, WIC).
+// Never overwrites: a converted photo is always a NEW file; renaming goes through the engine's
+// move_file (ctx.engine), so the folder rules, confirmations and snapshots / Undo apply as for any move.
+// GPS position is returned only when the call asks for it (gps: true).
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { psJson, guard, visiblePath, fail, json, needAction, str, int, freeName } from './tool-lib.mjs';
+
+const PS = fileURLToPath(new URL('./photos.ps1', import.meta.url));
+const ACTIONS = ['info', 'convert', 'rename_by_date'];
+export const IMAGE_EXT = new Set(['.jpg', '.jpeg', '.jpe', '.png', '.tif', '.tiff', '.heic', '.heif', '.bmp', '.gif', '.webp', '.jxr', '.wdp']);
+const MAX_FILES = 500, MAX_DEPTH = 6, MAX_DIRS = 2000;   // folders visited: a huge tree must not freeze the bridge
+
+export const defs = [{
+  name: 'photos',
+  title: 'Photos',
+  description: 'Photos on this PC. action "info": date taken, camera, size, orientation (GPS position only with gps: true); "convert": smaller or converted copies (max_size, quality, format jpg/png) saved as new files, originals untouched; "rename_by_date": names like "2026-07-14 10.22.33.jpg" from the date taken — a preview by default, dry_run: false renames (undoable). path = a photo or a folder.',
+  inputSchema: {
+    type: 'object', additionalProperties: false, required: ['action', 'path'],
+    properties: {
+      action: { type: 'string', enum: ACTIONS },
+      path: { type: 'string', description: 'A photo or a folder (full path)' },
+      recursive: { type: 'boolean', description: 'Include subfolders' },
+      limit: { type: 'integer', minimum: 1, maximum: MAX_FILES, description: 'At most this many photos (default 200)' },
+      gps: { type: 'boolean', description: 'info: include the GPS position' },
+      max_size: { type: 'integer', minimum: 16, maximum: 20000, description: 'convert: longest side in pixels (default 1920)' },
+      quality: { type: 'integer', minimum: 1, maximum: 100, description: 'convert: JPEG quality (default 85)' },
+      format: { type: 'string', enum: ['jpg', 'png'], description: 'convert: default jpg' },
+      output: { type: 'string', description: 'convert: folder (or file for one photo) for the new copies; default: next to each photo as "name (small).jpg"' },
+      dry_run: { type: 'boolean', description: 'rename_by_date: true (default) only shows the plan' },
+    },
+  },
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+}];
+
+const b64 = (o) => Buffer.from(JSON.stringify(o), 'utf8').toString('base64');
+const isImage = (p) => IMAGE_EXT.has(path.extname(p).toLowerCase());
+
+/** The photos at `p` (a file or a folder), each under the folder rules; → { files, truncated, hidden }. */
+export function listPhotos(ctx, p, { recursive = false, limit = 200 } = {}) {
+  const root = guard(ctx, p);
+  let st;
+  try { st = fs.statSync(root); } catch { fail('NOT_FOUND', `"${root}" was not found.`, 'Check the path.'); }
+  if (st.isFile()) { if (!isImage(root)) fail('NOT_PHOTO', `"${path.basename(root)}" is not a photo this tool reads (${[...IMAGE_EXT].join(' ')}).`); return { files: [root], truncated: false, hidden: 0 }; }
+  const files = [];
+  let hidden = 0, truncated = false;
+  const stack = [[root, 0]];
+  let dirs = 0;
+  while (stack.length && !truncated) {
+    if (++dirs > MAX_DIRS) { truncated = true; break; }
+    const [dir, depth] = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    const subdirs = [];
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (recursive && depth < MAX_DEPTH) subdirs.push(full); continue; }
+      if (!e.isFile() || !isImage(full)) continue;
+      if (!visiblePath(ctx, full)) { hidden++; continue; }
+      if (files.length >= limit) { truncated = true; break; }
+      files.push(full);
+    }
+    for (const d of subdirs.reverse()) stack.push([d, depth + 1]);
+  }
+  return { files, truncated, hidden };
+}
+
+const runPs = (ctx, mode, req, n, per) => psJson(ctx, { files: [PS], env: { BRX_MODE: mode }, input: b64(req), timeout: 30000 + n * per });
+
+/** "2026:07:14 10:22:33" → { iso: '2026-07-14 10:22:33', name: '2026-07-14 10.22.33' } or null. */
+export function takenOf(s) {
+  const m = /^(\d{4})[:-](\d{2})[:-](\d{2})[ T](\d{2}):(\d{2}):(\d{2})/.exec(String(s || '').trim());
+  if (!m || m[1] === '0000' || +m[2] < 1 || +m[2] > 12 || +m[3] < 1 || +m[3] > 31 || +m[4] > 23 || +m[5] > 59 || +m[6] > 59) return null;
+  return { iso: `${m[1]}-${m[2]}-${m[3]} ${m[4]}:${m[5]}:${m[6]}`, name: `${m[1]}-${m[2]}-${m[3]} ${m[4]}.${m[5]}.${m[6]}` };
+}
+const ERR = { NO_CODEC: 'Windows has no decoder for this format (for HEIC: install "HEIF Image Extensions" from the Microsoft Store)', DECODE_FAILED: 'not a readable image', NOT_FOUND: 'file not found', NO_ACCESS: 'Windows denied access', IO: 'the file is in use or unreadable', EXISTS: 'a file with the new name already exists' };
+const why = (code) => ERR[code] || String(code || 'unknown problem');
+
+async function info(ctx, files, gps) {
+  const r = await runPs(ctx, 'info', { files, gps }, files.length, 1000);
+  return (r.items || []).map((x) => {
+    if (x.error) return { path: x.path, problem: why(x.error) };
+    const t = takenOf(x.taken);
+    const camera = [x.make, x.model].filter(Boolean).join(' ').replace(/^(\S+) \1 /i, '$1 ');
+    return {
+      path: x.path, ...(t ? { taken: t.iso } : {}), ...(camera ? { camera } : {}), width: x.width, height: x.height,
+      ...(x.orientation && x.orientation !== 1 ? { orientation: x.orientation } : {}), ...(x.format ? { format: x.format } : {}),
+      // GPS: only when asked for (also enforced here, whatever the script returned).
+      ...(gps && x.gps ? { gps: x.gps } : x.hasGps ? { location: 'stored in the photo (not shown; ask with gps: true)' } : {}),
+    };
+  });
+}
+
+function convertPlan(ctx, files, { output, format }) {
+  const ext = format === 'png' ? '.png' : '.jpg';
+  let outDir = null, outFile = null;
+  if (output !== undefined) {
+    const o = guard(ctx, output, { write: true });
+    const isDir = (() => { try { return fs.statSync(o).isDirectory(); } catch { return false; } })();
+    if (isDir || /[\\/]$/.test(output) || files.length > 1 || !path.extname(o)) outDir = o;
+    else outFile = o;
+    if (outDir && !fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
+  }
+  const taken = new Set();
+  const free = (p) => { let c = freeName(p); const { dir, name, ext: e } = path.parse(p); for (let i = 2; taken.has(c.toLowerCase()); i++) c = freeName(path.join(dir, `${name} (${i})${e}`)); taken.add(c.toLowerCase()); return c; };
+  return files.map((src) => {
+    const base = path.parse(src).name;
+    const dst = outFile ? outFile : outDir ? path.join(outDir, `${base}${ext}`) : path.join(path.dirname(src), `${base} (small)${ext}`);
+    return { src, dst: free(guard(ctx, dst, { write: true })) };
+  });
+}
+
+function renamePlan(ctx, infos) {
+  const taken = new Set();
+  const plan = [], skipped = [];
+  for (const x of infos) {
+    if (x.problem) { skipped.push({ path: x.path, reason: x.problem }); continue; }
+    const t = takenOf(x.taken ? x.taken.replace(/^(\d{4})-(\d{2})-(\d{2})/, '$1:$2:$3') : '');
+    if (!t) { skipped.push({ path: x.path, reason: 'no date taken in the photo' }); continue; }
+    const { dir, name, ext } = path.parse(x.path);
+    if (name === t.name || new RegExp(`^${t.name.replace(/\./g, '\\.')} \\(\\d+\\)$`).test(name)) { skipped.push({ path: x.path, reason: 'already named by date' }); continue; }
+    try { guard(ctx, x.path, { write: true }); } catch (e) { skipped.push({ path: x.path, reason: e.message }); continue; }
+    let to = path.join(dir, `${t.name}${ext}`);
+    for (let i = 2; fs.existsSync(to) || taken.has(to.toLowerCase()); i++) to = path.join(dir, `${t.name} (${i})${ext}`);
+    taken.add(to.toLowerCase());
+    plan.push({ from: x.path, to });
+  }
+  return { plan, skipped };
+}
+
+const textOf = (r) => (r?.content || []).filter((c) => c?.type === 'text').map((c) => c.text).join(' ').slice(0, 300);
+
+export async function handle(name, args, ctx) {
+  const action = needAction(args, ACTIONS);
+  const p = str(args, 'path', { required: true, max: 1000 });
+  const limit = int(args, 'limit', { min: 1, max: MAX_FILES, def: 200 });
+  const { files, truncated, hidden } = listPhotos(ctx, p, { recursive: args.recursive === true, limit });
+  const extra = { ...(truncated ? { truncated: `only the first ${limit} photos` } : {}), ...(hidden ? { hidden: `${hidden} photo(s) hidden by this PC's folder rules` } : {}) };
+  if (!files.length) return json({ count: 0, note: 'No photos found here.', ...extra });
+
+  if (action === 'info') {
+    const items = await info(ctx, files, args.gps === true);
+    return json({ count: items.length, photos: items, ...extra });
+  }
+
+  if (action === 'convert') {
+    const format = args.format === undefined ? 'jpg' : args.format;
+    if (!['jpg', 'png'].includes(format)) fail('BAD_ARGS', 'format must be jpg or png.');
+    // max_size (snake_case like dry_run); the older spelling maxSize is still read.
+    const maxSize = int(args, args.max_size !== undefined ? 'max_size' : 'maxSize', { min: 16, max: 20000, def: 1920 });
+    const quality = int(args, 'quality', { min: 1, max: 100, def: 85 });
+    const output = str(args, 'output', { max: 1000 });
+    // Copies made earlier ("name (small).jpg") are not converted again.
+    const fresh = files.length > 1 ? files.filter((f) => !/ \(small\)( \(\d+\))?$/i.test(path.parse(f).name)) : files;
+    if (!fresh.length) return json({ converted: 0, note: 'Only copies made earlier ("… (small)") are here.', ...extra });
+    const items = convertPlan(ctx, fresh, { output, format });
+    const r = await runPs(ctx, 'convert', { items, maxSize, quality, format }, items.length, 3000);
+    const done = [], failed = [];
+    for (const x of r.items || []) {
+      if (x.ok) done.push({ from: x.src, saved: x.dst, width: x.width, height: x.height, bytes: x.bytes });
+      else failed.push({ path: x.src, problem: why(x.error) });
+    }
+    return json({ converted: done.length, files: done, ...(failed.length ? { failed } : {}), note: 'Originals were not changed. The new files carry no metadata (no GPS); photos are turned upright.', ...extra });
+  }
+
+  // rename_by_date
+  const infos = await info(ctx, files, false);
+  const { plan, skipped } = renamePlan(ctx, infos);
+  if (args.dry_run !== false) return json({ preview: true, rename: plan, ...(skipped.length ? { skipped } : {}), note: plan.length ? 'Nothing renamed yet. Call again with dry_run: false to rename.' : 'Nothing to rename.', ...extra });
+  if (!ctx.engine) fail('NO_ENGINE', 'Renaming is not available here.');
+  const renamed = [], failed = [];
+  for (const it of plan) {
+    // The plan was made before the awaits: a file may have appeared under the chosen name meanwhile.
+    if (fs.existsSync(it.to)) {
+      const { dir, ext } = path.parse(it.to), stem = path.parse(it.to).name.replace(/ \(\d+\)$/, '');
+      let i = 2;
+      while (fs.existsSync(path.join(dir, `${stem} (${i})${ext}`)) || plan.some((o) => o !== it && o.to.toLowerCase() === path.join(dir, `${stem} (${i})${ext}`).toLowerCase())) i++;
+      it.to = path.join(dir, `${stem} (${i})${ext}`);
+    }
+    const r = await ctx.engine('move_file', { source: it.from, destination: it.to });
+    if (r?.isError) { failed.push({ path: it.from, problem: textOf(r) || 'not renamed' }); if (r.notConfirmed || r.paused) break; } else renamed.push(it);
+  }
+  return json({ renamed: renamed.length, files: renamed, ...(failed.length ? { failed } : {}), ...(skipped.length ? { skipped } : {}), ...(renamed.length ? { undo: 'Renames can be undone with bridgerator_undo.' } : {}), ...extra });
+}

package/src/photos.ps1

@@ -0,0 +1,145 @@
+# LOGIC: see critical-logic/bridge.md ("Extra tools" / photos). Photo metadata and conversion with the
+# imaging built into Windows (WIC through PresentationCore) - no extra programs.
+# In: BRX_MODE = info | convert; stdin = base64 of UTF-8 JSON:
+#   info:    { files: [path...], gps: bool }
+#   convert: { items: [{ src, dst }], maxSize: int (0 = keep), quality: 1-100, format: 'jpg' | 'png' }
+# Tags are read by numeric id (EXIF 36867 DateTimeOriginal, 271 Make, 272 Model, 274 Orientation,
+# GPS 1-4), never by localized names. A new file is created with CreateNew: nothing is overwritten.
+# Out: ONE JSON line { items: [...] }; per-file problems are codes (NO_CODEC, DECODE_FAILED, EXISTS...).
+Add-Type -AssemblyName PresentationCore, WindowsBase
+function Out-Json($o) { [Console]::Out.WriteLine(($o | ConvertTo-Json -Compress -Depth 6)) }
+$req = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String(([Console]::In.ReadToEnd()).Trim())) | ConvertFrom-Json
+
+function Q($md, $q) { try { return $md.GetQuery($q) } catch { return $null } }
+function Get-Prefix($md) {
+  if (-not $md) { return $null }
+  foreach ($p in @('/app1/ifd', '/ifd')) { if ((Q $md "$p/{ushort=271}") -ne $null -or (Q $md "$p/exif") -ne $null -or (Q $md "$p/{ushort=274}") -ne $null) { return $p } }
+  return $null
+}
+function Err-Code($e) {
+  $h = $e.Exception.HResult
+  if ($e.Exception.InnerException) { $h = $e.Exception.InnerException.HResult }
+  if ($h -eq -2003292336) { return 'NO_CODEC' }          # 0x88982F50 WINCODEC_ERR_COMPONENTNOTFOUND
+  if ($e.Exception -is [System.IO.FileNotFoundException]) { return 'NOT_FOUND' }
+  if ($e.Exception -is [System.UnauthorizedAccessException]) { return 'NO_ACCESS' }
+  if ($e.Exception -is [System.IO.IOException]) { return 'IO' }
+  return 'DECODE_FAILED'
+}
+function Open-Frame($path, $cache) {
+  $fs = [IO.File]::Open($path, [IO.FileMode]::Open, [IO.FileAccess]::Read, [IO.FileShare]::ReadWrite)
+  try {
+    $dec = [Windows.Media.Imaging.BitmapDecoder]::Create($fs, [Windows.Media.Imaging.BitmapCreateOptions]::PreservePixelFormat -bor [Windows.Media.Imaging.BitmapCreateOptions]::IgnoreColorProfile, $cache)
+    return @{ fs = $fs; dec = $dec; frame = $dec.Frames[0] }
+  } catch { $fs.Dispose(); throw }
+}
+function Rationals($v) {
+  if ($v -eq $null) { return $null }
+  $out = @()
+  foreach ($x in @($v)) {
+    $u = [uint64]$x
+    $num = [double]($u -band [uint64]4294967295); $den = [double]($u -shr 32)
+    $out += $(if ($den -eq 0) { 0 } else { $num / $den })
+  }
+  return $out
+}
+function Deg($v, $ref) {
+  $r = Rationals $v
+  if (-not $r -or $r.Count -lt 1) { return $null }
+  $d = $r[0]; if ($r.Count -gt 1) { $d += $r[1] / 60 }; if ($r.Count -gt 2) { $d += $r[2] / 3600 }
+  if ("$ref" -match '^[SW]') { $d = -$d }
+  return [math]::Round($d, 6)
+}
+
+if ($env:BRX_MODE -eq 'info') {
+  $items = New-Object System.Collections.ArrayList
+  foreach ($p in @($req.files)) {
+    $o = @{ path = [string]$p }
+    $h = $null
+    try {
+      $h = Open-Frame $p ([Windows.Media.Imaging.BitmapCacheOption]::None)
+      $f = $h.frame
+      $o.width = $f.PixelWidth; $o.height = $f.PixelHeight
+      $md = $f.Metadata -as [Windows.Media.Imaging.BitmapMetadata]
+      if ($md) { try { $o.format = [string]$md.Format } catch { } }
+      $pre = Get-Prefix $md
+      if ($pre) {
+        $dt = Q $md "$pre/exif/{ushort=36867}"
+        if (-not $dt) { $dt = Q $md "$pre/exif/{ushort=36868}" }
+        if (-not $dt) { $dt = Q $md "$pre/{ushort=306}" }
+        if ($dt) { $o.taken = ([string]$dt).Trim([char]0, ' ') }
+        $mk = Q $md "$pre/{ushort=271}"; if ($mk) { $o.make = ([string]$mk).Trim([char]0, ' ') }
+        $ml = Q $md "$pre/{ushort=272}"; if ($ml) { $o.model = ([string]$ml).Trim([char]0, ' ') }
+        $or = Q $md "$pre/{ushort=274}"; if ($or -ne $null) { $o.orientation = [int]$or }
+        $gl = Q $md "$pre/gps/{ushort=2}"
+        if ($gl -ne $null) {
+          $o.hasGps = $true
+          if ($req.gps -eq $true) {
+            $o.gps = @{ lat = (Deg $gl (Q $md "$pre/gps/{ushort=1}")); lon = (Deg (Q $md "$pre/gps/{ushort=4}") (Q $md "$pre/gps/{ushort=3}")) }
+          }
+        }
+      }
+    } catch { $o.error = Err-Code $_ } finally { if ($h) { $h.fs.Dispose() } }
+    [void]$items.Add($o)
+  }
+  Out-Json @{ items = @($items) }
+  exit 0
+}
+
+if ($env:BRX_MODE -eq 'convert') {
+  $max = [int]$req.maxSize; $q = [int]$req.quality; if ($q -lt 1 -or $q -gt 100) { $q = 85 }
+  $items = New-Object System.Collections.ArrayList
+  foreach ($it in @($req.items)) {
+    $o = @{ src = [string]$it.src; dst = [string]$it.dst }
+    $h = $null; $out = $null
+    try {
+      $h = Open-Frame $it.src ([Windows.Media.Imaging.BitmapCacheOption]::OnLoad)
+      $f = $h.frame
+      $md = $f.Metadata -as [Windows.Media.Imaging.BitmapMetadata]
+      $pre = Get-Prefix $md
+      $orient = 1; if ($pre) { $v = Q $md "$pre/{ushort=274}"; if ($v -ne $null) { $orient = [int]$v } }
+      $w = $f.PixelWidth; $hgt = $f.PixelHeight
+      $s = 1.0; $big = [math]::Max($w, $hgt)
+      if ($max -gt 0 -and $big -gt $max) { $s = $max / $big }
+      $tg = New-Object Windows.Media.TransformGroup
+      if ($s -ne 1.0) { $tg.Children.Add((New-Object Windows.Media.ScaleTransform $s, $s)) }
+      # EXIF orientation applied to the pixels (the new file carries no metadata, so it stays upright).
+      switch ($orient) {
+        2 { $tg.Children.Add((New-Object Windows.Media.ScaleTransform -1, 1)) }
+        3 { $tg.Children.Add((New-Object Windows.Media.RotateTransform 180)) }
+        4 { $tg.Children.Add((New-Object Windows.Media.ScaleTransform 1, -1)) }
+        5 { $tg.Children.Add((New-Object Windows.Media.RotateTransform 90)); $tg.Children.Add((New-Object Windows.Media.ScaleTransform -1, 1)) }
+        6 { $tg.Children.Add((New-Object Windows.Media.RotateTransform 90)) }
+        7 { $tg.Children.Add((New-Object Windows.Media.RotateTransform 270)); $tg.Children.Add((New-Object Windows.Media.ScaleTransform -1, 1)) }
+        8 { $tg.Children.Add((New-Object Windows.Media.RotateTransform 270)) }
+      }
+      $img = [Windows.Media.Imaging.BitmapSource]$f
+      if ($tg.Children.Count -gt 0) { $img = New-Object Windows.Media.Imaging.TransformedBitmap $img, $tg }
+      if ($req.format -eq 'png') { $enc = New-Object Windows.Media.Imaging.PngBitmapEncoder }
+      else {
+        $enc = New-Object Windows.Media.Imaging.JpegBitmapEncoder; $enc.QualityLevel = $q
+        # JPEG has no transparency: flatten onto white (else transparent parts turn black). Formats with
+        # alpha: Bgra32 / Pbgra32 / Rgba64 / Prgba64 / Rgba128Float...; Indexed* may carry a transparent colour.
+        if ([string]$img.Format -cmatch '^(Bgra|Pbgra|Rgba|Prgba|Indexed)') {
+          $pw = $img.PixelWidth; $ph = $img.PixelHeight
+          $dv = New-Object Windows.Media.DrawingVisual; $dc = $dv.RenderOpen()
+          $rect = New-Object Windows.Rect 0, 0, $pw, $ph
+          $dc.DrawRectangle([Windows.Media.Brushes]::White, $null, $rect); $dc.DrawImage($img, $rect); $dc.Close()
+          $rtb = New-Object Windows.Media.Imaging.RenderTargetBitmap $pw, $ph, 96, 96, ([Windows.Media.PixelFormats]::Pbgra32)
+          $rtb.Render($dv)
+          $img = New-Object Windows.Media.Imaging.FormatConvertedBitmap $rtb, ([Windows.Media.PixelFormats]::Bgr24), $null, 0
+        }
+      }
+      $enc.Frames.Add([Windows.Media.Imaging.BitmapFrame]::Create($img))
+      $out = [IO.File]::Open($it.dst, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
+      $enc.Save($out); $out.Dispose(); $out = $null
+      $o.ok = $true; $o.width = $img.PixelWidth; $o.height = $img.PixelHeight; $o.bytes = (Get-Item -LiteralPath $it.dst).Length
+    } catch {
+      $o.error = $(if ($_.Exception -is [System.IO.IOException] -and (Test-Path -LiteralPath $it.dst) -and -not $out) { 'EXISTS' } else { Err-Code $_ })
+      if ($out) { $out.Dispose(); Remove-Item -LiteralPath $it.dst -Force -ErrorAction SilentlyContinue }
+    } finally { if ($h) { $h.fs.Dispose() } }
+    [void]$items.Add($o)
+  }
+  Out-Json @{ items = @($items) }
+  exit 0
+}
+Out-Json @{ error = 'BAD_MODE' }

package/src/plan.mjs

@@ -0,0 +1,90 @@
+// The plan as the relay reports it ({type:'plan', plan, until?, calls, limit, month, renewUrl}) →
+// what the Bridgerator window, the tray and our notifications show. Paying is offered only here on
+// the PC (never inside ChatGPT). Links: only our own site.
+export const ACCOUNT_URL = 'https://bridgerator.recondeck.com/app';
+const DAY = 86400000;
+// Our site = the one this PC is linked to (derived from the relay address: staging stays on staging).
+const PROD = 'https://bridgerator.recondeck.com';
+let site = PROD;
+/** Sets the site (https origin only; anything else keeps the previous one). */
+export function setSite(s) {
+  try { const x = new URL(String(s)); if (x.protocol === 'https:' && !x.username && !x.password) site = x.origin; } catch { /* keep */ }
+}
+export const siteUrl = () => site;
+export const accountUrl = () => `${site}/app`;
+
+/** Only https://<our site>/… — anything else falls back to the account page. */
+export function safeUrl(u) {
+  try { const x = new URL(String(u)); if (x.protocol === 'https:' && (x.origin === site || x.origin === PROD) && !x.username && !x.password) return x.href; } catch { /* bad */ }
+  return accountUrl();
+}
+
+const int = (x) => (Number.isSafeInteger(x) && x >= 0 ? x : null);
+
+/** Cleans the relay message → { plan:'free'|'pro', until?, calls?, limit?, month?, renewUrl }. */
+export function readPlan(m = {}) {
+  const until = typeof m.until === 'string' && !Number.isNaN(Date.parse(m.until)) ? new Date(m.until).toISOString() : undefined;
+  return {
+    plan: m.plan === 'pro' ? 'pro' : 'free',
+    ...(until ? { until } : {}),
+    ...(int(m.calls) !== null ? { calls: m.calls } : {}),
+    ...(int(m.limit) ? { limit: m.limit } : {}),
+    ...(typeof m.month === 'string' && /^\d{4}-\d{2}$/.test(m.month) ? { month: m.month } : {}),
+    renewUrl: safeUrl(m.renewUrl),
+  };
+}
+
+/** First day of the month after `month` (YYYY-MM) or after `now`, as YYYY-MM-DD. */
+export function resetDay(month, now = Date.now()) {
+  const [y, mo] = month ? month.split('-').map(Number) : [new Date(now).getUTCFullYear(), new Date(now).getUTCMonth() + 1];
+  return new Date(Date.UTC(y, mo, 1)).toISOString().slice(0, 10);
+}
+
+/**
+ * → { kind, tone, dismissible, days?, calls?, limit?, reset?, action:'renew'|'upgrade', url } or
+ * { kind:'none' }. Kinds: pro_ending (≤3 days left), pro_ended (ended within 30 days), limit (Free
+ * limit reached), free_high (Free ≥ 80 %).
+ */
+export function planBanner(p, now = Date.now()) {
+  if (!p) return { kind: 'none' };
+  const url = p.renewUrl || accountUrl();
+  const left = p.until ? Date.parse(p.until) - now : null;
+  if (p.plan === 'pro' && left !== null) {
+    if (left <= 0) return { kind: 'pro_ended', tone: 'red', dismissible: true, action: 'renew', url };
+    const days = Math.ceil(left / DAY);
+    if (days <= 3) return { kind: 'pro_ending', tone: 'yellow', dismissible: true, days, action: 'renew', url };
+    return { kind: 'none' };
+  }
+  if (p.plan === 'free' && left !== null && left <= 0 && -left < 30 * DAY) return { kind: 'pro_ended', tone: 'red', dismissible: true, action: 'renew', url };
+  if (p.plan === 'free' && p.limit && p.calls !== undefined) {
+    if (p.calls >= p.limit) return { kind: 'limit', tone: 'red', dismissible: false, calls: p.calls, limit: p.limit, reset: resetDay(p.month, now), action: 'upgrade', url };
+    if (p.calls >= 0.8 * p.limit) return { kind: 'free_high', tone: 'yellow', dismissible: true, calls: p.calls, limit: p.limit, action: 'upgrade', url };
+  }
+  return { kind: 'none' };
+}
+
+/**
+ * Usage this month and a simple forecast for the Status page (never shown in ChatGPT): the average
+ * pace of the days gone this month (at least one day) × the days of the month. → null (no numbers) or
+ * { calls, limit?, state: 'unlimited' | 'enough' | 'runs_out' | 'out', projected?, date? (YYYY-MM-DD) }.
+ */
+export function forecast(p, now = Date.now()) {
+  if (!p || p.calls === undefined) return null;
+  if (p.plan === 'pro' || !p.limit) return { calls: p.calls, state: 'unlimited' };
+  if (p.calls >= p.limit) return { calls: p.calls, limit: p.limit, state: 'out' };
+  const [y, mo] = p.month ? p.month.split('-').map(Number) : [new Date(now).getUTCFullYear(), new Date(now).getUTCMonth() + 1];
+  const start = Date.UTC(y, mo - 1, 1), end = Date.UTC(y, mo, 1), days = (end - start) / DAY;
+  const gone = Math.max(1, (Math.min(Math.max(now, start), end) - start) / DAY);
+  const perDay = p.calls / gone, projected = Math.round(perDay * days);
+  if (projected <= p.limit) return { calls: p.calls, limit: p.limit, state: 'enough', projected };
+  const date = new Date(Math.min(end - DAY, start + (p.limit / perDay) * DAY)).toISOString().slice(0, 10);
+  return { calls: p.calls, limit: p.limit, state: 'runs_out', projected, date };
+}
+
+/** A dismissed banner stays hidden 24 h (same kind only); the limit banner can't be dismissed. */
+export function bannerVisible(b, dismissed, now = Date.now()) {
+  if (b.kind === 'none') return false;
+  if (!b.dismissible) return true;
+  return !(dismissed && dismissed.kind === b.kind && now < dismissed.until);
+}
+export const dismissFor = (b, now = Date.now()) => ({ kind: b.kind, until: now + DAY });