@kitkat-vn/kitcode 0.2.0-staging.10

package/src/companion-electron.mjs

@@ -0,0 +1,85 @@
+import {app, BrowserWindow, ipcMain, nativeTheme, screen, shell} from 'electron';
+import {nameApp, showAppIcon} from './app-identity.mjs';
+import {miniWindowOptions} from './companion-window-options.mjs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {reachableAddress} from './api-access.mjs';
+import {renderCompanionWindow} from './companion-window.mjs';
+import {resolveDashboardUrl} from './open-dashboard.mjs';
+import {keepWindowOnItsPage} from './window-guards.mjs';
+
+const sourceDirectory = path.dirname(fileURLToPath(import.meta.url));
+const host = process.env.KITCODE_HOST ?? '127.0.0.1';
+const port = process.env.KITCODE_PORT ?? '4747';
+// The URL sets the Host header, and the API answers only a loopback Host (api-access.mjs).
+const apiBase = `http://${reachableAddress(host)}:${port}`;
+const companionPreload = path.join(sourceDirectory, 'companion-preload.cjs');
+const miniWidth = 560;
+const miniHeight = 76;
+
+let miniWindow;
+let quitting = false;
+
+function miniPosition() {
+  const {workArea} = screen.getPrimaryDisplay();
+  return {
+    x: workArea.x + workArea.width - miniWidth - 28,
+    y: workArea.y + workArea.height - miniHeight - 72,
+  };
+}
+
+async function trackerReady() {
+  try {
+    const response = await fetch(`${apiBase}/api/health`, {signal: AbortSignal.timeout(1200)});
+    const health = response.ok ? await response.json() : null;
+    return health?.status === 'ok' && health?.app === 'kitcode';
+  } catch {
+    return false;
+  }
+}
+
+function createMiniWindow(url) {
+  const position = miniPosition();
+  miniWindow = new BrowserWindow(miniWindowOptions({width: miniWidth, height: miniHeight, position, preload: companionPreload}));
+  keepWindowOnItsPage(miniWindow);
+  miniWindow.setAlwaysOnTop(true, 'floating');
+  miniWindow.setVisibleOnAllWorkspaces(true, {visibleOnFullScreen: true});
+  miniWindow.on('close', (event) => {
+    if (!quitting) {
+      event.preventDefault();
+      app.quit();
+    }
+  });
+  miniWindow.loadURL(url);
+}
+
+nameApp(app);
+
+app.whenReady().then(async () => {
+  showAppIcon(app);
+  nativeTheme.themeSource = 'dark';
+  const connected = await trackerReady();
+  const miniUrl = connected
+    ? `${apiBase}/companion`
+    : `data:text/html;charset=utf-8,${encodeURIComponent(renderCompanionWindow(apiBase))}`;
+  createMiniWindow(miniUrl);
+  ipcMain.handle('kitcode:companion-hide', (event) => {
+    if (event.sender === miniWindow.webContents) app.quit();
+    return {hidden: true};
+  });
+  ipcMain.handle('kitcode:open-dashboard', (event) => {
+    if (event.sender !== miniWindow.webContents) {
+      return {opened: false};
+    }
+
+    shell.openExternal(resolveDashboardUrl());
+    return {opened: true};
+  });
+  miniWindow.once('ready-to-show', () => miniWindow.showInactive());
+});
+
+app.on('before-quit', () => {
+  quitting = true;
+  ipcMain.removeHandler('kitcode:companion-hide');
+  ipcMain.removeHandler('kitcode:open-dashboard');
+});

package/src/companion-preload.cjs

@@ -0,0 +1,10 @@
+const {contextBridge, ipcRenderer} = require('electron');
+
+contextBridge.exposeInMainWorld('kitcodeCompanion', {
+  hide() {
+    return ipcRenderer.invoke('kitcode:companion-hide');
+  },
+  openDashboard() {
+    return ipcRenderer.invoke('kitcode:open-dashboard');
+  },
+});

package/src/companion-window-options.mjs

@@ -0,0 +1,16 @@
+import {ICON_PATH} from './app-identity.mjs';
+
+// The Mini's window options for Electron (src/companion-electron.mjs), kept apart from Electron so a test can read them.
+// `roundedCorners: false`: macOS rounds a frameless window's corners itself, over whatever the page draws, so the Mini's
+// square red frame (companion-window.mjs) needs it too (the operator, 2026-10-03). Other platforms ignore it.
+export function miniWindowOptions({width, height, position, preload}) {
+  return {
+    icon: ICON_PATH,
+    width, height,
+    minWidth: width, minHeight: height, maxWidth: width, maxHeight: height,
+    x: position.x, y: position.y, frame: false, transparent: true, hasShadow: false, roundedCorners: false,
+    backgroundColor: '#00000000', resizable: false,
+    movable: true, alwaysOnTop: true, skipTaskbar: true, show: false,
+    webPreferences: {preload, contextIsolation: true, nodeIntegration: false, sandbox: true},
+  };
+}

package/src/companion-window.mjs

@@ -0,0 +1,59 @@
+import {COMPANION_HIDE_CSS, renderCompanionTitleBar} from './companion-controls.mjs';
+import {DASHBOARD_URL} from './integration-spec.mjs';
+import {contentSecurityPolicy, fontFaces} from './window-page.mjs';
+
+export function renderCompanionWindow(apiBase = '') {
+  // The page's one stylesheet and one script, kept apart so that its policy allows exactly them. Served
+  // by the tracker (apiBase ''), the page reads the API from its own origin; the offline copy, from apiBase.
+  const style = `
+${fontFaces(['vt323', 'fira-code'])}
+:root{color-scheme:dark;--bg-color:#0c0c0c;--red-color:#f03030;--white-text:#e0e0e0;--font-mono:'Fira Code',monospace;--font-pixel:'VT323',monospace}
+*{box-sizing:border-box;margin:0;padding:0}
+html,body{position:relative;width:100%;height:100%;margin:0;overflow:hidden;background:transparent;color:var(--white-text);font-family:var(--font-mono)}
+button{cursor:pointer}
+.widget-window{position:relative;width:100%;height:100%;display:flex;flex-direction:column;background:var(--bg-color);border:2px solid var(--red-color);border-radius:0;overflow:hidden;-webkit-app-region:drag}
+.title-bar{padding:6px 10px 4px;display:flex;align-items:center;gap:7px;border-bottom:1px solid var(--red-color)}
+.dot{width:12px;height:12px;border-radius:50%;border:1px solid var(--red-color);background:transparent}
+.dot.filled{background-color:var(--red-color)}
+.widget-body{flex:1;min-height:0;padding:8px 16px;display:flex;align-items:center;justify-content:space-between;gap:10px;min-width:0;-webkit-app-region:drag}
+.brand-label{color:var(--red-color);font-family:var(--font-mono);font-size:10px;font-weight:700;line-height:1.15;letter-spacing:.6px;text-transform:uppercase;white-space:nowrap}
+.percentage{font-family:var(--font-pixel),var(--font-mono);font-size:30px;letter-spacing:1px;line-height:1;color:var(--white-text);white-space:nowrap}
+.progress-box{border-top:2px solid var(--white-text);border-bottom:2px solid var(--white-text);border-left:1px dashed var(--white-text);border-right:1px dashed var(--white-text);padding:3px 6px;width:120px;height:32px;display:flex;align-items:center;flex:0 0 120px;overflow:hidden}
+.progress-fill{width:0;height:100%;display:flex;flex-direction:column;justify-content:center;gap:1px;overflow:hidden;transition:width .2s ease}
+.progress-row{width:max-content;color:var(--white-text);font:700 9px/1 var(--font-mono);letter-spacing:1px;white-space:nowrap}
+.metrics-group{display:flex;align-items:flex-end;gap:14px;min-width:0}
+.metric-item{display:flex;flex-direction:column;align-items:center;min-width:0}
+.metric-value{color:var(--white-text);font-family:var(--font-pixel),var(--font-mono);font-size:24px;line-height:1;margin-bottom:2px;letter-spacing:.5px;white-space:nowrap}
+.metric-label{color:var(--red-color);font-family:var(--font-mono);font-size:7px;font-weight:500;letter-spacing:.3px;text-transform:uppercase;white-space:nowrap}
+.claim-btn{-webkit-app-region:no-drag;background:transparent;color:var(--white-text);font-family:var(--font-mono);font-size:10px;font-weight:500;letter-spacing:1px;padding:3px 12px;cursor:pointer;text-transform:uppercase;border-top:2px solid var(--red-color);border-bottom:2px solid var(--red-color);border-left:1px dashed var(--red-color);border-right:1px dashed var(--red-color);white-space:normal;width:min-content;line-height:1.15;transition:background-color .2s ease}
+.claim-btn:hover,.claim-btn:focus-visible{background:rgba(240,48,48,.15);outline:none}
+.offline .percentage,.offline .metric-value{color:#6f6f6f}
+.offline .progress-row{color:#6f6f6f}
+${COMPANION_HIDE_CSS}
+`;
+  const script = `
+const API_BASE=${JSON.stringify(apiBase)};const percent=document.getElementById('percent'),countValue=document.getElementById('countValue'),workedValue=document.getElementById('workedValue'),idleValue=document.getElementById('idleValue'),progressFill=document.getElementById('progressFill'),main=document.getElementById('main'),dashboardButton=document.getElementById('dashboardButton');
+function formatDuration(seconds){const totalSeconds=Math.max(0,Math.floor(Number(seconds)||0));if(totalSeconds<60)return totalSeconds+'s';const hours=Math.floor(totalSeconds/3600),minutes=Math.floor((totalSeconds%3600)/60);if(hours>0)return minutes>0?hours+'h '+minutes+'m':hours+'h';return minutes+'m'}
+function updateProgress(value){progressFill.style.width=Math.max(0,Math.min(100,Number(value)||0))+'%'}
+function render(summary){const reward=summary?.reward||{},global=summary?.global||{},value=Math.max(0,Math.min(100,Math.floor(Number(reward.progressPercent)||0)));percent.textContent=value+'%';countValue.textContent=String(Math.max(0,Math.floor(Number(reward.totalEquals)||0)));workedValue.textContent=formatDuration(global.totalActiveSeconds);idleValue.textContent=formatDuration(global.totalIdleSeconds);updateProgress(value);main.classList.remove('offline')}
+function offline(){percent.textContent='--';countValue.textContent='--';workedValue.textContent='--';idleValue.textContent='--';updateProgress(0);main.classList.add('offline')}
+async function sync(){try{const response=await fetch(API_BASE+'/api/summary');if(!response.ok)throw new Error();render(await response.json())}catch{offline()}}
+const hideButton=document.getElementById('hideButton');function hideCompanion(){try{const result=window.kitcodeCompanion?.hide?.();if(result&&typeof result.catch==='function')result.catch(()=>window.close());if(!result)window.close()}catch{window.close()}}
+hideButton.addEventListener('pointerdown',(event)=>event.stopPropagation());hideButton.addEventListener('click',(event)=>{event.stopPropagation();hideCompanion()});
+dashboardButton.addEventListener('pointerdown',(event)=>event.stopPropagation());
+dashboardButton.addEventListener('click',()=>{if(window.kitcodeCompanion?.openDashboard){window.kitcodeCompanion.openDashboard();return}window.open(${JSON.stringify(DASHBOARD_URL)},'_blank','noopener')});
+sync();const events=new EventSource(API_BASE+'/api/events');events.addEventListener('summary',(event)=>{try{render(JSON.parse(event.data))}catch{offline()}});events.onerror=offline;
+`;
+
+  // The button opens the dashboard, where each milestone reached shows its message: "See more". Until 2026-10-01 it was
+  // "Show code", and lit while a 10–30 % code was ready to show there; the break codes are gone (the operator's decision
+  // 6), and a milestone reached stays reached, so nothing lights it now. The Mini cannot show a message itself: the
+  // messages are the claim backend's, and the tracker, which serves this page, never talks to it. Two short words, which
+  // wrap onto two lines, as KITCODE COUNTER does on the left: "Dashboard" or "Messages" took 28 to 35 px more, and the
+  // counters then ran into each other at long-campaign values (measured in the 560 x 76 window with 2500 = and
+  // 11h 48m, 2026-09-24 and 2026-10-01).
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="${contentSecurityPolicy({script, style, connect: [apiBase || "'self'"]})}"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>KitCode Counter</title><style>${style}</style></head>
+<body><main class="widget-window" id="main" data-testid="companion-counter-bar">${renderCompanionTitleBar()}<div class="widget-body"><div class="brand-label" aria-label="KitCode Counter">KITCODE<br>COUNTER</div><strong class="percentage" id="percent" data-testid="mini-percent">--</strong><div class="progress-box" aria-hidden="true"><div class="progress-fill" id="progressFill"><div class="progress-row">========================</div><div class="progress-row">========================</div></div></div><div class="metrics-group" aria-label="KitCode counters"><div class="metric-item"><div class="metric-value" id="countValue" data-testid="mini-count">--</div><div class="metric-label">= COUNT</div></div><div class="metric-item"><div class="metric-value" id="workedValue" data-testid="mini-worked">--</div><div class="metric-label">WORKED</div></div><div class="metric-item"><div class="metric-value" id="idleValue" data-testid="mini-idle">--</div><div class="metric-label">IDLE</div></div></div><button class="claim-btn" id="dashboardButton" data-testid="companion-dashboard" type="button" title="Open the dashboard, where each milestone reached shows its message">See more</button></div></main><script>${script}</script></body></html>`;
+}

package/src/cors.mjs

@@ -0,0 +1,51 @@
+// The origins a tracker allows with nothing configured: the hosted dashboard's and the local development
+// servers'. Pinned by local-api.test.mjs.
+export const DEFAULT_ALLOWED_ORIGINS = new Set([
+  // The staging dashboard this tester build is for (scripts/tester-build.mjs in the repository).
+  "https://staging.kitcode.vn",
+  'http://localhost:8686',
+  'http://127.0.0.1:8686',
+  'http://localhost:3000',
+  'http://127.0.0.1:3000',
+  'http://localhost:5173',
+  'http://127.0.0.1:5173',
+]);
+
+function configuredOrigins() {
+  if (!process.env.KITCODE_ALLOWED_ORIGINS) {
+    return [];
+  }
+
+  return process.env.KITCODE_ALLOWED_ORIGINS.split(',')
+    .map((origin) => origin.trim())
+    .filter(Boolean);
+}
+
+export function isAllowedOrigin(origin) {
+  return Boolean(origin) && (DEFAULT_ALLOWED_ORIGINS.has(origin) || configuredOrigins().includes(origin));
+}
+
+// Only an allow-listed origin is told anything: whether it may read, and whether it may reach this
+// private-network address at all. Any other origin gets none of these headers. The one thing any page
+// may read is a refusal, which carries fixed words only (api-access.mjs).
+export function corsMiddleware(req, res, next) {
+  const origin = req.headers.origin;
+
+  res.setHeader('Vary', 'Origin');
+
+  if (isAllowedOrigin(origin)) {
+    res.setHeader('Access-Control-Allow-Origin', origin);
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+    res.setHeader('Access-Control-Allow-Private-Network', 'true');
+    res.setHeader('Private-Network-Access-ID', '4b:69:74:43:6f:64');
+    res.setHeader('Private-Network-Access-Name', 'kitcode-local');
+  }
+
+  if (req.method === 'OPTIONS') {
+    res.status(204).end();
+    return;
+  }
+
+  next();
+}