copyhub-cli 1.0.1 → 1.0.3

package/.env.example

@@ -10,6 +10,7 @@
 # copyhub start opens the Electron overlay by default; set to 1 for clipboard + Sheet only:
 # COPYHUB_START_NO_OVERLAY=1
 
+# OAuth Client ID / Secret: optional here — running copyhub login opens a browser wizard that saves them to ~/.copyhub/config.json instead.
 COPYHUB_GOOGLE_CLIENT_ID=
 COPYHUB_GOOGLE_CLIENT_SECRET=
 COPYHUB_OAUTH_REDIRECT_PORT=19999

package/README.md

@@ -45,6 +45,68 @@ Or run without linking:
 node src/cli.js <command>
 ```
 
+## Updating
+
+Your settings (`~/.copyhub/config.json`, tokens, history) are kept when you upgrade the CLI.
+
+**Recommended:** stop the background daemon before upgrading so Electron can reinstall cleanly; after upgrading start again:
+
+```bash
+copyhub stop
+```
+
+*(Skip `stop` if you only run `--foreground` or `overlay` and nothing is in the background.)*
+
+### Global install (`npm install -g copyhub-cli`)
+
+Check what npm considers latest vs what you have:
+
+```bash
+npm view copyhub-cli version
+```
+
+Upgrade to the latest published release:
+
+```bash
+npm install -g copyhub-cli@latest
+```
+
+Alternatively:
+
+```bash
+npm update -g copyhub-cli
+```
+
+Restart CopyHub:
+
+```bash
+copyhub start
+```
+
+To see the installed package version: `npm list -g copyhub-cli --depth=0`.
+
+### From source
+
+Pull latest commits and reinstall modules:
+
+```bash
+copyhub stop
+git pull
+npm install
+```
+
+If you previously ran **`npm link`**, linking stays tied to this folder — after `npm install` you usually **do not** need to link again unless npm warns otherwise:
+
+```bash
+npm link
+```
+
+Then:
+
+```bash
+copyhub start
+```
+
 ## Google Cloud setup
 
 1. Enable **[Google Sheets API](https://console.cloud.google.com/apis/library/sheets.googleapis.com)** on your OAuth project.
@@ -54,13 +116,13 @@ node src/cli.js <command>
    http://127.0.0.1:19999/oauth2callback
    ```
 
-3. Copy `.env.example` to `.env` and set:
+3. Provide OAuth credentials in **any one** of these ways:
 
-   - `COPYHUB_GOOGLE_CLIENT_ID`
-   - `COPYHUB_GOOGLE_CLIENT_SECRET`
-   - Optionally `COPYHUB_OAUTH_REDIRECT_PORT` (default **19999**)
+   - **Recommended for first setup:** run **`copyhub login`** with no secrets configured — your browser opens a **localhost wizard** where you paste **Client ID** and **Client secret** (the same values as `COPYHUB_GOOGLE_CLIENT_ID` / `COPYHUB_GOOGLE_CLIENT_SECRET`); they are stored in `~/.copyhub/config.json`.
 
-Alternatively, store credentials in `~/.copyhub/config.json` via:
+   - Copy `.env.example` to `.env` and set `COPYHUB_GOOGLE_CLIENT_ID`, `COPYHUB_GOOGLE_CLIENT_SECRET`, and optionally `COPYHUB_OAUTH_REDIRECT_PORT` (default **19999**).
+
+   - Or run **`copyhub config`**:
 
 ```bash
 copyhub config --client-id "<ID>" --client-secret "<SECRET>" [--sheet-id "<SPREADSHEET_ID>"] [--redirect-port 19999]
@@ -68,13 +130,16 @@ copyhub config --client-id "<ID>" --client-secret "<SECRET>" [--sheet-id "<SPREA
 
 ## First run
 
-1. **Login** (opens the browser for OAuth, then a setup page):
+1. **Login** — opens the browser:
 
    ```bash
    copyhub login
    ```
 
-2. On the setup page, enter your **Spreadsheet ID** (from the URL `…/d/<SPREADSHEET_ID>/edit`), choose **platform** (Windows / macOS / Linux) for shortcut hints, set the **overlay accelerator** if you want, and save.
+   - If Client ID / Secret are **not** already in `.env` or `~/.copyhub/config.json`, the first screen collects them (**Google OAuth credentials** page). Submit it to save into config.
+   - After Google sign-in, another setup page asks for **Spreadsheet ID**, **platform**, and optional **overlay shortcut**.
+
+2. On that spreadsheet/setup page, enter your **Spreadsheet ID** (from the URL `…/d/<SPREADSHEET_ID>/edit`), choose **platform** (Windows / macOS / Linux) for shortcut hints, set the **overlay accelerator** if you want, and save.
 
 3. **Start** the background watcher (clipboard + Sheets + overlay by default):
 
@@ -116,7 +181,7 @@ copyhub --help
 | Command | What it does |
 |---------|----------------|
 | `copyhub config` | Writes OAuth client ID/secret (and optional Sheet ID, redirect port) to `~/.copyhub/config.json`. `--client-id` and `--client-secret` are required. |
-| `copyhub login` | Opens browser for Google OAuth, then the setup page (spreadsheet ID, platform, overlay shortcut). |
+| `copyhub login` | Opens browser: localhost wizard for Client ID/secret if missing, then Google OAuth, then spreadsheet/platform setup. |
 | `copyhub logout` | Deletes saved OAuth tokens (`~/.copyhub/tokens.json`). |
 | `copyhub status` | Prints OAuth config source, sheet target, tokens, overlay settings, and whether the background daemon is running. |
 | `copyhub start` | Starts clipboard watcher + optional Sheets sync + Electron overlay in the **background** (closing the terminal does not stop it). Only one instance at a time. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copyhub-cli",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "CopyHub — clipboard, local history, Google Sheets sync (OAuth). Windows, macOS, Linux.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -31,6 +31,7 @@ import {
 import { killDaemonTree } from './stop-process.js';
 import { ensureDir } from './storage.js';
 import { runCopyhubDaemon } from './start-daemon-logic.js';
+import { wipeCopyhubDirectory } from './wipe-data.js';
 
 const CLI_JS = fileURLToPath(new URL('./cli.js', import.meta.url));
 
@@ -72,7 +73,7 @@ program
 program
   .command('login')
   .description(
-    `Google sign-in (OAuth Sheets), then Spreadsheet ID setup page — port ${DEFAULT_OAUTH_REDIRECT_PORT} or ${ENV_OAUTH_REDIRECT_PORT}`,
+    `OAuth Sheets flow (opens browser). If Client ID/Secret are missing, a localhost wizard saves them first — callback port ${DEFAULT_OAUTH_REDIRECT_PORT} or ${ENV_OAUTH_REDIRECT_PORT}`,
   )
   .action(async () => {
     await runLoginFlow();
@@ -86,6 +87,35 @@ program
     console.log(`Removed tokens: ${TOKENS_PATH}`);
   });
 
+program
+  .command('reset')
+  .description(
+    'Stop background daemon if running; delete ~/.copyhub entirely (config, tokens, history, run state). Requires --yes',
+  )
+  .option('--yes', 'Required confirmation flag (destructive)')
+  .action(async (opts) => {
+    if (!opts.yes) {
+      console.error(
+        'Refusing to wipe without --yes. Deletes ~/.copyhub (Windows: %USERPROFILE%\\.copyhub). Example: copyhub reset --yes',
+      );
+      process.exit(1);
+    }
+    pruneStaleRunState();
+    const s = readRunState();
+    if (s?.pid && isPidAlive(s.pid)) {
+      killDaemonTree(s.pid);
+    }
+    try {
+      await wipeCopyhubDirectory();
+    } catch (e) {
+      console.error((/** @type {Error} */ (e)).message || String(e));
+      process.exit(1);
+    }
+    console.log(`Removed CopyHub data directory: ${DIR}`);
+    console.log('.env is not changed — remove OAuth vars there if you want.');
+    console.log('If an overlay window was open separately, close it manually.');
+  });
+
 program
   .command('overlay')
   .description(
@@ -163,7 +193,7 @@ program
     if (!cfg) {
       console.log('OAuth config: missing');
       console.log(
-        `  Set ${ENV_GOOGLE_CLIENT_ID} and ${ENV_GOOGLE_CLIENT_SECRET} in .env (see .env.example), or run: copyhub config`,
+        `  Set ${ENV_GOOGLE_CLIENT_ID} and ${ENV_GOOGLE_CLIENT_SECRET} in .env (see .env.example), run copyhub config, or copyhub login (browser wizard)`,
       );
     } else {
       const srcLabel =
@@ -333,6 +363,7 @@ program
   .action(() => {
     console.log(`copyhub config [--client-id ID] [--client-secret SEC] [--redirect-port P] [--sheet-id ID]
 copyhub login     | copyhub logout | copyhub status
+copyhub reset --yes   (delete ~/.copyhub — stop daemon first is recommended)
 copyhub start [--no-sheet] [--no-overlay] [--foreground]
       Default runs in background (terminal can close). Single instance — second start is blocked.
 copyhub list (ls) | copyhub stop

package/src/config.js

@@ -22,6 +22,26 @@ function parseRedirectPortFromEnv() {
   return n;
 }
 
+/**
+ * Port for the OAuth HTTP listener (env wins, then saved config, then default).
+ * Does not require Client ID / Secret (used before credential bootstrap).
+ */
+export function resolveOAuthListenPort() {
+  const envPort = parseRedirectPortFromEnv();
+  if (envPort != null) return envPort;
+  if (existsSync(CONFIG_PATH)) {
+    try {
+      const j = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+      if (typeof j.redirectPort === 'number' && Number.isFinite(j.redirectPort)) {
+        return j.redirectPort;
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  return DEFAULT_OAUTH_REDIRECT_PORT;
+}
+
 /** Both Client ID and Secret come from environment (or .env). */
 export function hasOAuthCredentialsInEnv() {
   const id = process.env[ENV_GOOGLE_CLIENT_ID]?.trim();

package/src/oauth.js

@@ -8,7 +8,9 @@ import {
   DEFAULT_OAUTH_REDIRECT_PORT,
   ENV_GOOGLE_CLIENT_ID,
   ENV_GOOGLE_CLIENT_SECRET,
+  ENV_OAUTH_REDIRECT_PORT,
   mergeConfigPartial,
+  resolveOAuthListenPort,
   loadSheetSyncTarget,
   loadOverlayAcceleratorFromConfigSync,
   loadOverlayPlatformFromConfigSync,
@@ -34,7 +36,7 @@ export async function getAuthorizedClient() {
   const cfg = await loadConfig();
   if (!cfg) {
     throw new Error(
-      `OAuth is not configured. Set ${ENV_GOOGLE_CLIENT_ID} and ${ENV_GOOGLE_CLIENT_SECRET} (.env or environment), or run: copyhub config --client-id ID --client-secret SECRET`,
+      `OAuth is not configured. Set ${ENV_GOOGLE_CLIENT_ID} and ${ENV_GOOGLE_CLIENT_SECRET} (.env or environment), run copyhub config, or copyhub login (browser wizard).`,
     );
   }
   const client = createOAuthClient(cfg);
@@ -75,6 +77,256 @@ function escapeHtml(s) {
     .replace(/'/g, ''');
 }
 
+/**
+ * @param {string} bootstrapToken
+ * @param {number} listenPort
+ */
+function credentialSetupPageHtml(bootstrapToken, listenPort) {
+  const tVal = escapeHtml(bootstrapToken);
+  const callbackUri = `http://127.0.0.1:${listenPort}/oauth2callback`;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>CopyHub — Google OAuth credentials</title>
+  <style>
+    :root {
+      --text: #141824;
+      --muted: #5a6272;
+      --line: #e2e8f1;
+      --accent: #2563eb;
+      --accent-soft: #eff6ff;
+      --radius: 14px;
+      --shadow: 0 4px 24px rgba(20, 24, 36, 0.08), 0 1px 3px rgba(20, 24, 36, 0.04);
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+      background: linear-gradient(160deg, #e8eef9 0%, #f5f7fb 45%, #eef2f8 100%);
+      color: var(--text);
+      padding: 32px 16px 48px;
+      line-height: 1.55;
+    }
+    .wrap { max-width: 520px; margin: 0 auto; }
+    .brand {
+      font-size: 13px;
+      font-weight: 600;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      color: var(--accent);
+      margin-bottom: 8px;
+    }
+    h1 { font-size: 1.55rem; font-weight: 700; margin: 0 0 8px; letter-spacing: -0.02em; }
+    .sub { color: var(--muted); font-size: 15px; margin-bottom: 24px; }
+    .card {
+      background: #fff;
+      border-radius: var(--radius);
+      box-shadow: var(--shadow);
+      border: 1px solid rgba(255,255,255,0.8);
+      padding: 26px 24px;
+      margin-bottom: 18px;
+    }
+    label.field-label { display: block; font-weight: 600; font-size: 14px; margin-bottom: 8px; }
+    input[type="password"], input[type="text"] {
+      width: 100%;
+      padding: 12px 14px;
+      font-size: 15px;
+      border: 1px solid var(--line);
+      border-radius: 10px;
+      background: #fafbfd;
+    }
+    input:focus {
+      outline: none;
+      border-color: var(--accent);
+      box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.15);
+      background: #fff;
+    }
+    .hint { font-size: 13px; color: var(--muted); margin-top: 10px; line-height: 1.5; }
+    .hint code {
+      font-size: 12px;
+      background: var(--accent-soft);
+      color: #1d4ed8;
+      padding: 2px 7px;
+      border-radius: 6px;
+      font-weight: 500;
+    }
+    button.submit {
+      width: 100%;
+      margin-top: 20px;
+      padding: 14px 20px;
+      font-size: 16px;
+      font-weight: 600;
+      color: #fff;
+      background: linear-gradient(180deg, #3b82f6 0%, #2563eb 100%);
+      border: none;
+      border-radius: 12px;
+      cursor: pointer;
+      box-shadow: 0 2px 8px rgba(37, 99, 235, 0.35);
+    }
+    button.submit:hover { filter: brightness(1.05); }
+    .callback-box {
+      font-size: 13px;
+      padding: 12px 14px;
+      background: linear-gradient(135deg, #f8fafc 0%, #f1f5f9 100%);
+      border-radius: 10px;
+      border: 1px solid var(--line);
+      word-break: break-all;
+    }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <div class="brand">CopyHub</div>
+    <h1>Google Cloud OAuth</h1>
+    <p class="sub">Paste your OAuth 2.0 Client ID and Client Secret (same as <code>${ENV_GOOGLE_CLIENT_ID}</code> / <code>${ENV_GOOGLE_CLIENT_SECRET}</code> in <code>.env</code>). Stored in <code>~/.copyhub/config.json</code>.</p>
+
+    <div class="card">
+      <p class="hint" style="margin-top:0;"><strong>Authorized redirect URI</strong> in Google Cloud Console must include:</p>
+      <div class="callback-box"><code>${escapeHtml(callbackUri)}</code></div>
+      <p class="hint">Port comes from <code>${ENV_OAUTH_REDIRECT_PORT}</code> (currently <strong>${listenPort}</strong>) or your saved config.</p>
+    </div>
+
+    <form method="POST" action="/credentials">
+      <input type="hidden" name="t" value="${tVal}" />
+      <div class="card">
+        <label class="field-label" for="cid">Client ID</label>
+        <input id="cid" type="text" name="clientId" autocomplete="off" spellcheck="false" required />
+        <label class="field-label" for="csec" style="margin-top:16px;">Client secret</label>
+        <input id="csec" type="password" name="clientSecret" autocomplete="new-password" spellcheck="false" required />
+      </div>
+      <button type="submit" class="submit">Save and continue to Google sign-in</button>
+    </form>
+  </div>
+</body>
+</html>`;
+}
+
+const credentialSavedHtml = `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/><title>CopyHub</title>
+<style>
+body{font-family:system-ui,sans-serif;min-height:100vh;margin:0;display:flex;align-items:center;justify-content:center;background:linear-gradient(160deg,#e8eef9,#f5f7fb);padding:24px;}
+.box{background:#fff;padding:32px 36px;border-radius:16px;box-shadow:0 8px 32px rgba(20,24,36,.1);max-width:420px;text-align:center;line-height:1.65;color:#141824;}
+.box h2{margin:0 0 12px;font-size:1.25rem;}
+.box p{margin:.6rem 0;color:#5a6272;font-size:15px;}
+.box code{background:#eff6ff;color:#1d4ed8;padding:2px 8px;border-radius:6px;font-size:13px;}
+</style></head>
+<body><div class="box"><h2>Credentials saved</h2>
+<p>The login flow will open Google next (this tab can stay open).</p></div></body></html>`;
+
+/**
+ * Localhost wizard when Client ID / Secret are missing from env and config file.
+ * @returns {Promise<void>}
+ */
+async function runCredentialBootstrap() {
+  const listenPort = resolveOAuthListenPort();
+  await new Promise((resolve, reject) => {
+    /** @type {string | null} */
+    let bootstrapToken = randomBytes(24).toString('hex');
+    let settled = false;
+
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      server.close(() => resolve(undefined));
+    };
+
+    const server = createServer(async (req, res) => {
+      try {
+        if (!req.url) {
+          res.writeHead(400);
+          res.end('Bad request');
+          return;
+        }
+        const u = new URL(req.url, `http://127.0.0.1:${listenPort}`);
+
+        if (u.pathname === '/credentials' && req.method === 'GET') {
+          const t = u.searchParams.get('t');
+          if (!bootstrapToken || t !== bootstrapToken) {
+            res.writeHead(403, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end('<p>Invalid session. Run <code>copyhub login</code> again.</p>');
+            return;
+          }
+          res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+          res.end(credentialSetupPageHtml(bootstrapToken, listenPort));
+          return;
+        }
+
+        if (u.pathname === '/credentials' && req.method === 'POST') {
+          let body = '';
+          try {
+            body = await readRequestBody(req);
+          } catch {
+            res.writeHead(413);
+            res.end('Payload too large');
+            return;
+          }
+          const params = new URLSearchParams(body);
+          const t = params.get('t');
+          if (!bootstrapToken || t !== bootstrapToken) {
+            res.writeHead(403);
+            res.end('Forbidden');
+            return;
+          }
+          const clientId = (params.get('clientId') || '').trim();
+          const clientSecret = (params.get('clientSecret') || '').trim();
+          if (!clientId || !clientSecret) {
+            res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end('<p>Client ID and Client secret are required.</p>');
+            return;
+          }
+          try {
+            await mergeConfigPartial({ clientId, clientSecret });
+          } catch {
+            res.writeHead(500, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end('<p>Could not write config. Check write permissions on ~/.copyhub/</p>');
+            return;
+          }
+          bootstrapToken = null;
+          res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+          res.end(credentialSavedHtml);
+          setTimeout(finish, 400);
+          return;
+        }
+
+        res.writeHead(404);
+        res.end('Not found');
+      } catch (e) {
+        res.writeHead(500);
+        res.end('Server error');
+        server.close(() => reject(/** @type {Error} */ (e)));
+      }
+    });
+
+    const idleMs = 20 * 60 * 1000;
+    const idleTimer = setTimeout(() => {
+      if (!settled) {
+        console.warn('Credential setup idle timeout (20 minutes).');
+        finish();
+      }
+    }, idleMs);
+    server.on('close', () => clearTimeout(idleTimer));
+
+    server.on('error', (err) => {
+      if (!settled) reject(err);
+    });
+
+    server.listen(listenPort, '127.0.0.1', async () => {
+      const credUrl = `http://127.0.0.1:${listenPort}/credentials?t=${encodeURIComponent(bootstrapToken)}`;
+      console.log('Opening browser for Google OAuth credentials (localhost wizard)...');
+      console.log(`If it does not open: ${credUrl}`);
+      try {
+        await open(credUrl);
+      } catch {
+        console.log('Open this URL manually:');
+        console.log(credUrl);
+      }
+    });
+  });
+}
+
 /** Shortcut presets (Electron Accelerator) per platform — embedded as JSON in the setup page. */
 const PLATFORM_PRESETS = {
   win: [
@@ -423,10 +675,25 @@ body{font-family:system-ui,sans-serif;min-height:100vh;margin:0;display:flex;ali
  * @returns {Promise<void>}
  */
 export async function runLoginFlow() {
-  const cfg = await loadConfig();
+  let cfg = await loadConfig();
+  if (!cfg) {
+    const listenPort = resolveOAuthListenPort();
+    try {
+      await runCredentialBootstrap();
+    } catch (e) {
+      const code = /** @type {NodeJS.ErrnoException} */ (e)?.code;
+      if (code === 'EADDRINUSE') {
+        throw new Error(
+          `Port ${listenPort} is already in use. Stop the other process or set ${ENV_OAUTH_REDIRECT_PORT} to a free port.`,
+        );
+      }
+      throw /** @type {Error} */ (e);
+    }
+    cfg = await loadConfig();
+  }
   if (!cfg) {
     throw new Error(
-      `Not configured. Set ${ENV_GOOGLE_CLIENT_ID} and ${ENV_GOOGLE_CLIENT_SECRET} in .env, or run: copyhub config --client-id ... --client-secret ...`,
+      `OAuth is not configured. Set ${ENV_GOOGLE_CLIENT_ID} and ${ENV_GOOGLE_CLIENT_SECRET} in .env, run copyhub config, or complete the browser credential wizard.`,
     );
   }
   const port = cfg.redirectPort ?? DEFAULT_OAUTH_REDIRECT_PORT;

package/src/sheet-overlay-history.js

@@ -0,0 +1,79 @@
+import { google } from 'googleapis';
+import { getAuthorizedClient } from './oauth.js';
+import { loadSheetSyncTarget } from './config.js';
+import { formatGoogleSheetUserMessage } from './sheet-api-errors.js';
+
+/** @param {unknown} v */
+function cellToString(v) {
+  if (v == null) return '';
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  if (v instanceof Date) return v.toISOString();
+  return String(v);
+}
+
+/** @param {string} tabName */
+function escapeTabName(tabName) {
+  return /[^A-Za-z0-9_]/.test(tabName)
+    ? `'${tabName.replace(/'/g, "''")}'`
+    : tabName;
+}
+
+/** @param {number} daysAgo */
+function overlayDailyTabNameDaysAgo(daysAgo) {
+  const d = new Date();
+  d.setDate(d.getDate() - daysAgo);
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `COPYHUB-${y}-${m}-${day}`;
+}
+
+/**
+ * Clipboard rows from one COPYHUB-YYYY-MM-DD tab (newest timestamps first).
+ * Reads used cells in A:B from row 2 onward (append puts newer rows at the bottom).
+ * @param {number} daysAgo 0 = today
+ * @param {number} [maxRowsCap] Keep only this many newest rows (after sort).
+ */
+export async function fetchOverlayDailyTabRows(daysAgo, maxRowsCap = 500) {
+  const day = Math.min(Math.max(Number(daysAgo), 0), 90);
+  const cap = Math.min(Math.max(Number(maxRowsCap), 1), 2000);
+
+  const target = await loadSheetSyncTarget();
+  if (!target) return [];
+
+  const auth = await getAuthorizedClient();
+  if (!auth.credentials.refresh_token && !auth.credentials.access_token) {
+    return [];
+  }
+
+  const sheets = google.sheets({ version: 'v4', auth });
+  const tab = overlayDailyTabNameDaysAgo(day);
+  const range = `${escapeTabName(tab)}!A2:B`;
+
+  try {
+    const res = await sheets.spreadsheets.values.get({
+      spreadsheetId: target.spreadsheetId,
+      range,
+      valueRenderOption: 'FORMATTED_VALUE',
+    });
+
+    const values = res.data.values ?? [];
+
+    /** @type {Array<{ ts: string, text: string, synced: boolean }>} */
+    const items = [];
+    for (const row of values) {
+      if (!Array.isArray(row) || row.length < 2) continue;
+      const ts = cellToString(row[0]).trim();
+      const text = cellToString(row[1]).trim();
+      if (!text) continue;
+      if (/^(time|thời gian)$/i.test(ts)) continue;
+      items.push({ ts: ts || '', text, synced: true });
+    }
+
+    items.sort((a, b) => (Date.parse(b.ts) || 0) - (Date.parse(a.ts) || 0));
+    return items.slice(0, cap);
+  } catch (e) {
+    throw new Error(formatGoogleSheetUserMessage(e));
+  }
+}

package/src/sheets.js

@@ -7,7 +7,7 @@ import { formatGoogleSheetUserMessage } from './sheet-api-errors.js';
 /**
  * @param {string} tabName
  */
-function a1RangeForTab(tabName) {
+export function a1RangeForTab(tabName) {
   const escaped = /[^A-Za-z0-9_]/.test(tabName)
     ? `'${tabName.replace(/'/g, "''")}'`
     : tabName;

package/src/start-daemon-logic.js

@@ -1,4 +1,4 @@
-import { appendHistory } from './storage.js';
+import { appendHistory, isDuplicateOfLatestHistory } from './storage.js';
 import { startClipboardWatcher } from './clipboard-watcher.js';
 import { appendClipboardToSheet } from './sheets.js';
 import { loadTokens } from './tokens.js';
@@ -73,6 +73,9 @@ export async function runCopyhubDaemon(opts, io = console) {
   let lastSheetLogAt = 0;
 
   const watcher = startClipboardWatcher(async (text) => {
+    if (isDuplicateOfLatestHistory(text)) {
+      return;
+    }
     let synced = false;
     if (useSheet && sheetTarget && (tokens?.refresh_token || tokens?.access_token)) {
       try {

package/src/storage.js

@@ -57,3 +57,14 @@ export function readRecentHistorySync(maxLines = 200) {
   }
   return out.reverse();
 }
+
+/**
+ * True when `text` equals the latest saved history row (skip consecutive identical copies).
+ * @param {string} text
+ */
+export function isDuplicateOfLatestHistory(text) {
+  if (typeof text !== 'string' || text.length === 0) return false;
+  const recent = readRecentHistorySync(1);
+  const last = recent[0];
+  return typeof last?.text === 'string' && last.text === text;
+}

package/src/wipe-data.js

@@ -0,0 +1,10 @@
+import { rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { DIR } from './paths.js';
+
+/** Delete the entire ~/.copyhub directory (all local CopyHub data). */
+export async function wipeCopyhubDirectory() {
+  if (existsSync(DIR)) {
+    await rm(DIR, { recursive: true, force: true });
+  }
+}

package/ui/main.mjs

@@ -13,7 +13,12 @@ import {
   nativeImage,
 } from 'electron';
 import { readRecentHistorySync } from '../src/storage.js';
-import { loadOverlayAcceleratorFromConfigSync } from '../src/config.js';
+import {
+  loadOverlayAcceleratorFromConfigSync,
+  loadSheetSyncTarget,
+} from '../src/config.js';
+import { loadTokens } from '../src/tokens.js';
+import { fetchOverlayDailyTabRows } from '../src/sheet-overlay-history.js';
 
 const gotLock = app.requestSingleInstanceLock();
 if (!gotLock) {
@@ -38,8 +43,9 @@ function normalizeAccelerator(raw) {
 const DEFAULT_ACCEL = 'CommandOrControl+Shift+H';
 const HIDE_ON_START = process.env.COPYHUB_OVERLAY_HIDE_ON_START === '1';
 
-/** Overlay width (~70% of 460px baseline). */
-const OVERLAY_WIDTH = Math.round(460 * 0.7);
+/** Overlay size (slightly larger than earlier ~70% width). */
+const OVERLAY_WIDTH = Math.round(460 * 0.84);
+const OVERLAY_HEIGHT = 590;
 
 /** For UI / IPC: registered shortcut and raw value from .env */
 let overlayHotkeyMeta = {
@@ -53,6 +59,27 @@ let tray = null;
 /** Avoid hiding immediately after show (WM quirks). */
 let blurHideEnabled = false;
 
+/**
+ * After showing the overlay, enable blur→hide after a short grace period so clicks outside close it reliably.
+ * @param {BrowserWindow} w
+ */
+function armBlurHideEnable(w) {
+  if (STICKY_NO_BLUR || !w || w.isDestroyed()) return;
+  blurHideEnabled = false;
+  let armed = false;
+  const arm = () => {
+    if (armed || !w || w.isDestroyed()) return;
+    armed = true;
+    setTimeout(() => {
+      if (!STICKY_NO_BLUR && w && !w.isDestroyed()) {
+        blurHideEnabled = true;
+      }
+    }, 320);
+  };
+  w.once('focus', arm);
+  setTimeout(arm, 420);
+}
+
 /**
  * Stay above other apps: screen-saver level (highest in Electron), moveTop, all workspaces.
  * @param {BrowserWindow} w
@@ -85,7 +112,7 @@ function applyAlwaysOnTopStack(w) {
 function createWindow() {
   win = new BrowserWindow({
     width: OVERLAY_WIDTH,
-    height: 540,
+    height: OVERLAY_HEIGHT,
     alwaysOnTop: true,
     show: false,
     /** Frameless: no title bar + menu (Windows/macOS). */
@@ -138,10 +165,8 @@ function createWindow() {
     applyAlwaysOnTopStack(win);
     win.focus();
     win.webContents.send('overlay:open');
-    setTimeout(() => {
-      applyAlwaysOnTopStack(win);
-      blurHideEnabled = true;
-    }, 800);
+    setTimeout(() => applyAlwaysOnTopStack(win), 120);
+    armBlurHideEnable(win);
   });
 }
 
@@ -180,10 +205,8 @@ function toggleOverlay() {
     applyAlwaysOnTopStack(win);
     win.focus();
     win.webContents.send('overlay:open');
-    setTimeout(() => {
-      applyAlwaysOnTopStack(win);
-      blurHideEnabled = true;
-    }, 800);
+    setTimeout(() => applyAlwaysOnTopStack(win), 120);
+    armBlurHideEnable(win);
   }
 }
 
@@ -222,6 +245,169 @@ function registerHotkeys() {
   return { accelerator: '', usedFallback: false };
 }
 
+function mergeHistoryForOverlay(localItems, sheetItems, cap) {
+  const seen = new Set();
+  /** @type {typeof localItems} */
+  const out = [];
+  /** Sheet rows first so duplicates dedupe keeps sheet metadata when timestamps tie. */
+  const combined = [...sheetItems, ...localItems];
+  combined.sort((a, b) => (Date.parse(b.ts) || 0) - (Date.parse(a.ts) || 0));
+  for (const it of combined) {
+    const key = `${it.ts}\u0000${it.text}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(it);
+  }
+  return out.slice(0, cap);
+}
+
+/** @type {{ merged: Array<{ ts: string, text: string, synced: boolean }> }} */
+const historyMergedCache = {
+  merged: [],
+};
+
+/** Recent local lines only — Sheet supplies older / cross-device rows so they are not crowded out. */
+const HISTORY_LOCAL_LINES = 700;
+/** Max merged entries after dedupe (pagination slices this list). */
+const HISTORY_MERGE_CAP = 4000;
+
+/** @type {{ sheetFetched: number, sheetHint: string }} */
+let lastHistorySheetMeta = { sheetFetched: 0, sheetHint: '' };
+
+/** Sequential Sheet fetch: one daily tab per step until overlay has enough merged rows. */
+let sheetIncrementalState = {
+  accumulatedItems: [],
+  nextDaysAgo: 0,
+  daysBackLimit: 30,
+  exhausted: false,
+  maxRowsPerTab: 500,
+};
+
+function resetSheetIncrementalState() {
+  sheetIncrementalState = {
+    accumulatedItems: [],
+    nextDaysAgo: 0,
+    daysBackLimit: 30,
+    exhausted: false,
+    maxRowsPerTab: 500,
+  };
+}
+
+async function fetchNextDailyTabIntoState() {
+  if (sheetIncrementalState.exhausted) return;
+  if (sheetIncrementalState.nextDaysAgo > sheetIncrementalState.daysBackLimit) {
+    sheetIncrementalState.exhausted = true;
+    return;
+  }
+  try {
+    const items = await fetchOverlayDailyTabRows(
+      sheetIncrementalState.nextDaysAgo,
+      sheetIncrementalState.maxRowsPerTab,
+    );
+    sheetIncrementalState.accumulatedItems.push(...items);
+    sheetIncrementalState.accumulatedItems.sort(
+      (a, b) => (Date.parse(b.ts) || 0) - (Date.parse(a.ts) || 0),
+    );
+    if (sheetIncrementalState.accumulatedItems.length > HISTORY_MERGE_CAP) {
+      sheetIncrementalState.accumulatedItems =
+        sheetIncrementalState.accumulatedItems.slice(0, HISTORY_MERGE_CAP);
+    }
+  } catch (e) {
+    const msg = /** @type {Error} */ (e).message || String(e);
+    lastHistorySheetMeta.sheetHint = `Google Sheet error: ${msg.slice(0, 140)}`;
+    console.warn('[CopyHub overlay]', lastHistorySheetMeta.sheetHint);
+    sheetIncrementalState.exhausted = true;
+    return;
+  }
+  sheetIncrementalState.nextDaysAgo += 1;
+}
+
+/**
+ * Ensure merged history covers at least `page * pageSize` items (capped), fetching extra Sheet tabs only if needed.
+ */
+async function ensureMergedHistoryCoversPage(page, pageSize) {
+  const localItems = buildLocalHistoryItems();
+  const sheetTarget = await loadSheetSyncTarget();
+  const tok = await loadTokens();
+  const sheetOk =
+    Boolean(sheetTarget) && Boolean(tok?.refresh_token || tok?.access_token);
+
+  if (!sheetOk) {
+    if (!sheetTarget) {
+      lastHistorySheetMeta = {
+        sheetFetched: 0,
+        sheetHint: 'Google Sheet: not configured — run copyhub login',
+      };
+    } else {
+      lastHistorySheetMeta = {
+        sheetFetched: 0,
+        sheetHint: 'Google Sheet: not signed in — run copyhub login',
+      };
+    }
+    sheetIncrementalState.exhausted = true;
+    historyMergedCache.merged = mergeHistoryForOverlay(localItems, [], HISTORY_MERGE_CAP);
+    return;
+  }
+
+  const targetMin = Math.min(page * pageSize, HISTORY_MERGE_CAP);
+
+  while (true) {
+    const merged = mergeHistoryForOverlay(
+      localItems,
+      sheetIncrementalState.accumulatedItems,
+      HISTORY_MERGE_CAP,
+    );
+    historyMergedCache.merged = merged;
+
+    if (merged.length >= HISTORY_MERGE_CAP) break;
+    if (sheetIncrementalState.exhausted) break;
+    /** Merge Sheet at least once when configured so dedupe / synced flags match Sheet. */
+    if (merged.length >= targetMin && sheetIncrementalState.nextDaysAgo > 0) break;
+
+    await fetchNextDailyTabIntoState();
+  }
+
+  const preservedErr =
+    typeof lastHistorySheetMeta.sheetHint === 'string' &&
+    lastHistorySheetMeta.sheetHint.startsWith('Google Sheet error:');
+
+  lastHistorySheetMeta.sheetFetched = sheetIncrementalState.accumulatedItems.length;
+
+  if (!preservedErr) {
+    if (!sheetIncrementalState.exhausted) {
+      lastHistorySheetMeta.sheetHint = `Google Sheet: ${sheetIncrementalState.accumulatedItems.length} rows · more when you page`;
+    } else if (sheetIncrementalState.accumulatedItems.length === 0) {
+      lastHistorySheetMeta.sheetHint =
+        'Google Sheet: 0 rows in last 31 days (check COPYHUB-YYYY-MM-DD tabs / timezone)';
+    } else {
+      lastHistorySheetMeta.sheetHint = `Google Sheet: ${sheetIncrementalState.accumulatedItems.length} rows loaded`;
+    }
+  }
+}
+
+function buildLocalHistoryItems() {
+  return readRecentHistorySync(HISTORY_LOCAL_LINES).map((row) => ({
+    ts: row.ts || '',
+    text: typeof row.text === 'string' ? row.text : '',
+    synced: Boolean(row.syncedToSheet || row.syncedToGmail),
+  }));
+}
+
+/** @param {ReturnType<typeof buildLocalHistoryItems>} items */
+function paginateHistoryItems(items, page, pageSize) {
+  const total = items.length;
+  const totalPages = Math.max(1, Math.ceil(total / pageSize));
+  const safePage = Math.min(Math.max(page, 1), totalPages);
+  const start = (safePage - 1) * pageSize;
+  return {
+    items: items.slice(start, start + pageSize),
+    page: safePage,
+    pageSize,
+    total,
+    totalPages,
+  };
+}
+
 function registerIpc() {
   ipcMain.handle('overlay:meta', () => ({
     ...overlayHotkeyMeta,
@@ -230,17 +416,81 @@ function registerIpc() {
     sticky: STICKY_NO_BLUR,
   }));
 
-  ipcMain.handle('history:get', () => {
+  /** Fast path: local history.jsonl only (overlay shows this while Sheet loads). */
+  ipcMain.handle('history:getLocal', (_e, opts = {}) => {
+    try {
+      const pageSize = Math.min(Math.max(Number(opts.pageSize) || 10, 1), 50);
+      let page = Math.max(Number(opts.page) || 1, 1);
+      const localItems = buildLocalHistoryItems();
+      const paginated = paginateHistoryItems(localItems, page, pageSize);
+      return {
+        ...paginated,
+        provisional: true,
+        sheetHint:
+          localItems.length > 0
+            ? 'Showing local copies · loading Google Sheet…'
+            : 'Loading Google Sheet…',
+        sheetFetched: 0,
+        sheetHasMore: false,
+      };
+    } catch (e) {
+      return {
+        error: /** @type {Error} */ (e).message,
+        items: [],
+        page: 1,
+        pageSize: 10,
+        total: 0,
+        totalPages: 1,
+        provisional: true,
+        sheetHint: '',
+        sheetFetched: 0,
+        sheetHasMore: false,
+      };
+    }
+  });
+
+  ipcMain.handle('history:get', async (_e, opts = {}) => {
     try {
+      const pageSize = Math.min(Math.max(Number(opts.pageSize) || 10, 1), 50);
+      let page = Math.max(Number(opts.page) || 1, 1);
+      const refresh = Boolean(opts.refresh);
+
+      if (refresh) {
+        resetSheetIncrementalState();
+        lastHistorySheetMeta = { sheetFetched: 0, sheetHint: '' };
+        historyMergedCache.merged = [];
+      }
+
+      await ensureMergedHistoryCoversPage(page, pageSize);
+
+      const total = historyMergedCache.merged.length;
+      const totalPages = Math.max(1, Math.ceil(total / pageSize));
+      page = Math.min(page, totalPages);
+      const start = (page - 1) * pageSize;
+      const items = historyMergedCache.merged.slice(start, start + pageSize);
+
       return {
-        items: readRecentHistorySync(200).map((row) => ({
-          ts: row.ts || '',
-          text: typeof row.text === 'string' ? row.text : '',
-          synced: Boolean(row.syncedToSheet || row.syncedToGmail),
-        })),
+        items,
+        page,
+        pageSize,
+        total,
+        totalPages,
+        sheetHint: lastHistorySheetMeta.sheetHint,
+        sheetFetched: lastHistorySheetMeta.sheetFetched,
+        sheetHasMore: !sheetIncrementalState.exhausted,
       };
     } catch (e) {
-      return { error: /** @type {Error} */ (e).message, items: [] };
+      return {
+        error: /** @type {Error} */ (e).message,
+        items: [],
+        page: 1,
+        pageSize: 10,
+        total: 0,
+        totalPages: 1,
+        sheetHint: '',
+        sheetFetched: 0,
+        sheetHasMore: false,
+      };
     }
   });
 

package/ui/preload.cjs

@@ -2,7 +2,10 @@ const { contextBridge, ipcRenderer } = require('electron');
 
 contextBridge.exposeInMainWorld('copyhub', {
   getMeta: () => ipcRenderer.invoke('overlay:meta'),
-  getHistory: () => ipcRenderer.invoke('history:get'),
+  /** @param {{ page?: number, pageSize?: number, refresh?: boolean }} [opts] */
+  getHistory: (opts) => ipcRenderer.invoke('history:get', opts ?? {}),
+  /** Local history only — instant; used while Sheet sync runs. */
+  getHistoryLocal: (opts) => ipcRenderer.invoke('history:getLocal', opts ?? {}),
   copyPick: (text) => ipcRenderer.invoke('history:copy', text),
   onOpen: (fn) => {
     ipcRenderer.on('overlay:open', (_e) => {

package/ui/renderer/index.html

@@ -58,6 +58,53 @@
       cursor: grabbing;
     }
 
+    #list-wrap {
+      flex: 1;
+      min-height: 0;
+      display: flex;
+      flex-direction: column;
+      position: relative;
+    }
+
+    #list-loading {
+      flex-shrink: 0;
+      display: none;
+      align-items: center;
+      gap: 10px;
+      padding: 8px 14px;
+      font-size: 12px;
+      font-weight: 600;
+      color: var(--accent);
+      background: linear-gradient(90deg, var(--accent-soft), rgba(61, 90, 254, 0.02));
+      border-bottom: 1px solid var(--border);
+      -webkit-app-region: no-drag;
+      app-region: no-drag;
+      animation: hint-pulse 1.4s ease-in-out infinite;
+    }
+
+    #list-loading.visible {
+      display: flex;
+    }
+
+    #list-loading .spinner {
+      width: 16px;
+      height: 16px;
+      flex-shrink: 0;
+      border: 2px solid rgba(61, 90, 254, 0.35);
+      border-top-color: var(--accent);
+      border-radius: 50%;
+      animation: spin 0.65s linear infinite;
+    }
+
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+
+    @keyframes hint-pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.82; }
+    }
+
     #list {
       flex: 1;
       min-height: 0;
@@ -173,33 +220,173 @@
       border-radius: var(--radius);
       font-size: 13px;
     }
+
+    #pager {
+      flex-shrink: 0;
+      display: none;
+      align-items: center;
+      justify-content: center;
+      gap: 12px;
+      padding: 8px 12px 12px;
+      border-top: 1px solid var(--border);
+      background: linear-gradient(180deg, var(--bg) 0%, #fafbfc 100%);
+      -webkit-app-region: no-drag;
+      app-region: no-drag;
+    }
+
+    #pager.visible {
+      display: flex;
+    }
+
+    #pager button {
+      font: inherit;
+      font-size: 13px;
+      font-weight: 600;
+      padding: 6px 14px;
+      border-radius: 8px;
+      border: 1px solid var(--border);
+      background: var(--surface);
+      color: var(--text);
+      cursor: pointer;
+      transition: background 0.15s, border-color 0.15s;
+    }
+
+    #pager button:hover:not(:disabled) {
+      background: var(--surface-hover);
+      border-color: rgba(61, 90, 254, 0.35);
+    }
+
+    #pager button:disabled {
+      opacity: 0.45;
+      cursor: default;
+    }
+
+    #pg-info {
+      font-size: 12px;
+      color: var(--text-muted);
+      min-width: 0;
+      text-align: center;
+      flex: 1;
+    }
+
+    .sheet-hint {
+      flex-shrink: 0;
+      font-size: 11px;
+      line-height: 1.45;
+      color: var(--text-muted);
+      padding: 6px 14px 4px;
+      text-align: center;
+      border-top: 1px solid var(--border);
+      background: var(--bg);
+      -webkit-app-region: no-drag;
+      app-region: no-drag;
+    }
+
+    .sheet-hint[hidden] {
+      display: none !important;
+    }
   </style>
 </head>
 <body>
   <div id="drag-strip" title="Drag to move window"></div>
-  <div id="list"></div>
+  <div id="list-wrap">
+    <div id="list-loading" aria-live="polite">
+      <div class="spinner" aria-hidden="true"></div>
+      <span>Syncing Google Sheet…</span>
+    </div>
+    <div id="list"></div>
+  </div>
+  <div id="sheet-hint" class="sheet-hint" hidden></div>
+  <div id="pager" aria-label="Pagination">
+    <button type="button" id="pg-prev">Previous</button>
+    <span id="pg-info"></span>
+    <button type="button" id="pg-next">Next</button>
+  </div>
   <script>
     const listEl = document.getElementById('list');
+    const listLoadingEl = document.getElementById('list-loading');
+    const pagerEl = document.getElementById('pager');
+    const pgPrev = document.getElementById('pg-prev');
+    const pgNext = document.getElementById('pg-next');
+    const pgInfo = document.getElementById('pg-info');
+    const sheetHintEl = document.getElementById('sheet-hint');
+
+    const pageSize = 10;
+    let currentPage = 1;
+    /** @type {{ total: number, totalPages: number }} */
+    let lastPaging = { total: 0, totalPages: 1 };
+    let lastSheetHasMore = false;
+    let sheetSyncInFlight = false;
 
-    async function refresh() {
+    function setLoadingUi(on) {
+      listLoadingEl.classList.toggle('visible', on);
+    }
+
+    function syncPagerBar() {
+      const { total, totalPages } = lastPaging;
+      if (!total) return;
+      pgPrev.disabled = sheetSyncInFlight || currentPage <= 1;
+      pgNext.disabled =
+        sheetSyncInFlight ||
+        (currentPage * pageSize >= total && !lastSheetHasMore);
+      const from = (currentPage - 1) * pageSize + 1;
+      const to = Math.min(currentPage * pageSize, total);
+      const moreMark = lastSheetHasMore && currentPage * pageSize >= total ? '+' : '';
+      const pagesShown =
+        lastSheetHasMore && currentPage * pageSize >= total
+          ? Math.max(totalPages, currentPage + 1)
+          : totalPages;
+      pgInfo.textContent = `Page ${currentPage} / ${pagesShown} · ${from}–${to} of ${total}${moreMark}`;
+    }
+
+    function renderHistoryResponse(res) {
       listEl.innerHTML = '';
-      const res = await window.copyhub.getHistory();
+
       if (res && res.error) {
+        pagerEl.classList.remove('visible');
+        sheetHintEl.hidden = true;
         const e = document.createElement('div');
         e.id = 'err';
         e.textContent = res.error;
         listEl.appendChild(e);
+        lastPaging = { total: 0, totalPages: 1 };
+        lastSheetHasMore = false;
         return;
       }
+
+      lastSheetHasMore = Boolean(res.sheetHasMore);
+      currentPage = res.page ?? currentPage;
       const rows = res && Array.isArray(res.items) ? res.items : [];
-      if (!rows.length) {
+      const total = res.total ?? 0;
+      const totalPages = res.totalPages ?? 1;
+      lastPaging = { total, totalPages };
+
+      if (!total) {
+        pagerEl.classList.remove('visible');
+        if (res.sheetHint) {
+          sheetHintEl.hidden = false;
+          sheetHintEl.textContent = res.sheetHint;
+        } else {
+          sheetHintEl.hidden = true;
+        }
         const d = document.createElement('div');
         d.id = 'empty';
         d.textContent =
-          'No history yet — run copyhub start and copy something. Click a row to copy again; click outside or Esc to close.';
+          'No local history yet — run copyhub start and copy something. Click a row to copy again; click outside or Esc to close.';
         listEl.appendChild(d);
         return;
       }
+
+      if (res.sheetHint) {
+        sheetHintEl.hidden = false;
+        sheetHintEl.textContent = res.sheetHint;
+      } else {
+        sheetHintEl.hidden = true;
+      }
+
+      pagerEl.classList.add('visible');
+      syncPagerBar();
+
       for (const r of rows) {
         const div = document.createElement('div');
         div.className = 'row' + (r.synced ? ' synced' : '');
@@ -215,10 +402,72 @@
       }
     }
 
+    async function loadHistory(opt = {}) {
+      const refreshCache = Boolean(opt.refreshCache);
+      if (refreshCache) currentPage = 1;
+      if (typeof opt.page === 'number' && opt.page >= 1) {
+        currentPage = opt.page;
+      }
+
+      if (refreshCache) {
+        sheetSyncInFlight = true;
+        setLoadingUi(true);
+        pgPrev.disabled = true;
+        pgNext.disabled = true;
+
+        const quick = await window.copyhub.getHistoryLocal({
+          page: currentPage,
+          pageSize,
+        });
+
+        if (quick.error) {
+          sheetSyncInFlight = false;
+          setLoadingUi(false);
+          renderHistoryResponse(quick);
+          return;
+        }
+
+        currentPage = quick.page ?? currentPage;
+        renderHistoryResponse(quick);
+
+        try {
+          const full = await window.copyhub.getHistory({
+            page: currentPage,
+            pageSize,
+            refresh: true,
+          });
+          currentPage = full.page ?? currentPage;
+          renderHistoryResponse(full);
+        } finally {
+          sheetSyncInFlight = false;
+          setLoadingUi(false);
+          syncPagerBar();
+        }
+        return;
+      }
+
+      const res = await window.copyhub.getHistory({
+        page: currentPage,
+        pageSize,
+        refresh: false,
+      });
+      renderHistoryResponse(res);
+    }
+
+    pgPrev.addEventListener('click', () => {
+      if (sheetSyncInFlight || currentPage <= 1) return;
+      void loadHistory({ page: currentPage - 1 });
+    });
+
+    pgNext.addEventListener('click', () => {
+      if (sheetSyncInFlight) return;
+      void loadHistory({ page: currentPage + 1 });
+    });
+
     window.copyhub.onOpen(() => {
-      void refresh();
+      void loadHistory({ refreshCache: true });
     });
-    void refresh();
   </script>
 </body>
 </html>
+