Chrome Extension Master Launch & Interception Blueprint

Chronological technical milestones achieved across the 12-hour build session:

• Milestone 1 - Problem Discovery: Identified browser redirect malware injecting into TUF submission flow via Chrome DevTools Network tab. Pivoted the debugging session into building TUFHub using the same interception technique - legitimately.
  Copy
• Milestone 2 - Architecture Lock: Defined single-purpose scope (TUF accepted solution sync to GitHub), confirmed zero-server architecture (pure client-side, GitHub REST API only), and declared all 22 platform invariants.
  Copy
• Milestone 3 - Manifest V3 + Script World Isolation: Separated interceptor.js into "world": "MAIN" for fetch monkey-patching and content.js into "world": "ISOLATED" for chrome.runtime messaging. Bridged via Custom DOM Events (TUFHUB_ACCEPTED_SUBMISSION).
  Copy
• Milestone 4 - OAuth Implementation: Built dual-path GitHub OAuth: primary via chrome.identity.launchWebAuthFlow, and a tab-based fallback listener (chrome.tabs.onUpdated) to handle Brave Browser's privacy mode which blocks .chromiumapp.org redirect URIs.
  Copy
• Milestone 5 - Real-Time Sync Engine: Engineered 3-minute (180,000ms) debounce cooldown per problem slug in chrome.storage.local. Built SHA conflict handler in uploader.js for Git 409 Conflict errors via re-fetch and retry.
  Copy
• Milestone 6 - Directory Hierarchy Builder: Defined file path schema as {Category}/{Topic}/{problem-slug}/solution.{ext} with a per-problem README.md stub and a root README.md auto-indexer table tracking total problem counts per category.
  Copy
• Milestone 7 - UX Polish: Built floating toast notifications injected into TUF DOM (green success with checkmark, red error with [Fix it] deep-link button). Added animated green badge via chrome.action.setBadgeText with 5s auto-clear timeout.
  Copy
• Milestone 8 - Onboarding Wizard: Built 3-step welcome.html page (Step 1: Connect GitHub OAuth; Step 2: Select or Auto-Create repo; Step 3: Done with live test sync) that opens automatically on chrome.runtime.onInstalled.
  Copy
• Milestone 9 - Donation UX: Implemented 15th-sync donation nudge toast with PayPal link and UPI QR modal. Wording: "Enjoying TUFHub? Support the project ☕". Counter in syncCount incremented on each accepted sync.
  Copy
• Milestone 10 - Remote Config: Implemented Gist-based remote config (tufhub-config.json) fetched on session start for dynamic DOM selector updates without extension republishing.
  Copy
• Milestone 11 - Visual Asset Pipeline: Automated 1280x800 Web Store presentation cards with Python Pillow: Fire Orange + Royal Blue ambient radial glow halos, macOS dark browser chrome headers, Apple traffic light buttons, and vector green live status dots.
  Copy
• Milestone 12 - Web Store Launch: Completed README engineering (em-dash scrub, 1-row language table, collapsible accordions, ?v=5 Camo CDN cache-busting), submitted to Web Store, hosted Privacy Policy at https://Arora-Sir.github.io/tufhub-privacy.
  Copy

These 22 decisions are locked invariants - they cannot change without breaking the extension or violating Web Store policy:

Every permission is justified. Here is the complete manifest.json with inline rationale:

{
  "manifest_version": 3,
  "name": "TUFHub - TakeUForward to GitHub Sync",
  "version": "1.0.0",
  "description": "Auto-syncs accepted TakeUForward solutions to your GitHub repository.",
  "icons": {
    "16": "assets/icons/icon16.png",
    "32": "assets/icons/icon32.png",
    "48": "assets/icons/icon48.png",
    "128": "assets/icons/icon128.png"
  },
  "action": {
    "default_popup": "popup/popup.html",
    "default_icon": "assets/icons/icon48.png"
  },
  "background": {
    "service_worker": "dist/background.js",
    "type": "module"
  },
  "content_scripts": [
    {
      "matches": ["https://takeuforward.org/plus/*"],
      "js": ["dist/interceptor.js"],
      "run_at": "document_start",
      "world": "MAIN"
    },
    {
      "matches": ["https://takeuforward.org/plus/*"],
      "js": ["dist/content.js"],
      "run_at": "document_idle"
    }
  ],
  "permissions": ["storage", "identity", "tabs"],
  "host_permissions": [
    "https://takeuforward.org/*",
    "https://api.github.com/*",
    "https://github.com/*"
  ],
  "web_accessible_resources": [
    {
      "resources": ["welcome/welcome.html", "assets/*"],
      "matches": ["<all_urls>"]
    }
  ]
}

This is the core of the extension. Runs in "world": "MAIN" at document_start to intercept TUF submission API responses before the page's React code processes them:

// interceptor.js - Runs in "world": "MAIN"
// WHY MAIN WORLD: Content scripts in ISOLATED world cannot access window.fetch
// or the page's JS context. MAIN world shares the page's window object.
(function () {
  'use strict';
  const _originalFetch = window.fetch;

  window.fetch = async function (...args) {
    const [resource] = args;
    const url = typeof resource === 'string' ? resource : resource?.url;
    const response = await _originalFetch.apply(this, args);

    if (url && /takeuforward\.org.*(submit|run_submission|submissions\/run)/i.test(url)) {
      try {
        const data = await response.clone().json();
        if (data && (data.status === 'AC' || data.status === 'Accepted' || data.verdict === 'Accepted')) {
          const payload = {
            problemSlug: data.problem_slug || extractSlugFromURL(url),
            language:    data.language || data.lang || 'cpp',
            code:        data.code || data.user_code || '',
            difficulty:  data.difficulty || 'Medium',
            topic:       data.topic || 'General',
            category:    data.category || 'DSA',
            timestamp:   Date.now(),
          };
          document.dispatchEvent(
            new CustomEvent('TUFHUB_ACCEPTED_SUBMISSION', { detail: payload })
          );
        }
      } catch (e) { /* Silent catch - never break the host page */ }
    }
    return response;
  };

  function extractSlugFromURL(url) {
    const match = url.match(/problems?\/([^/?#]+)/i);
    return match ? match[1].toLowerCase().replace(/\s+/g, '-') : 'unknown-problem';
  }
})();

Runs in the default ISOLATED world. Listens for DOM Events from interceptor.js and forwards payload to the background service worker:

// content.js - Runs in ISOLATED world (default)
// PURPOSE: Listen for DOM events from MAIN world, forward to background service worker,
//          and inject UI toast notifications into the TUF page.
(function () {
  'use strict';

  document.addEventListener('TUFHUB_ACCEPTED_SUBMISSION', async (event) => {
    const payload = event.detail;
    if (!payload || !payload.code) return;

    showToast('syncing', 'Syncing ' + payload.problemSlug + ' to GitHub...');

    try {
      const response = await chrome.runtime.sendMessage({ type: 'SYNC_SUBMISSION', data: payload });
      if (response && response.success) {
        showToast('success', 'Synced to GitHub! ✓ ' + payload.problemSlug);
        if (response.showDonationNudge) {
          setTimeout(() => showToast('donate', 'Enjoying TUFHub? Support the project ☕'), 4000);
        }
      } else {
        showToast('error', 'Sync failed: ' + (response?.error || 'Unknown error'), true);
      }
    } catch (err) {
      showToast('error', 'Extension error: ' + err.message, true);
    }
  });

  function showToast(type, message, showFix = false) {
    document.getElementById('tufhub-toast')?.remove();
    const colors = {
      syncing: { bg: '#1e3a5f', border: '#3b82f6', icon: '🔄' },
      success: { bg: '#052e16', border: '#10b981', icon: '✓' },
      error:   { bg: '#450a0a', border: '#ef4444', icon: '✗' },
      donate:  { bg: '#1c1205', border: '#f97316', icon: '☕' },
    };
    const c = colors[type] || colors.syncing;
    const toast = document.createElement('div');
    toast.id = 'tufhub-toast';
    toast.setAttribute('role', 'alert');
    toast.style.cssText =
      'position:fixed;bottom:24px;right:24px;z-index:2147483647;' +
      'background:' + c.bg + ';border:1px solid ' + c.border + ';' +
      'color:#f1f5f9;padding:14px 18px;border-radius:12px;' +
      'font-family:Inter,system-ui,sans-serif;font-size:14px;' +
      'max-width:340px;box-shadow:0 8px 24px rgba(0,0,0,.5);' +
      'display:flex;align-items:flex-start;gap:10px;';
    const icon = document.createElement('span');
    icon.textContent = c.icon;
    icon.style.cssText = 'font-size:18px;flex-shrink:0;margin-top:1px';
    const text = document.createElement('div');
    text.textContent = message;
    toast.append(icon, text);
    if (showFix) {
      const fix = document.createElement('button');
      fix.textContent = '[Fix it]';
      fix.style.cssText = 'background:none;border:none;color:#60a5fa;cursor:pointer;font-weight:700;padding:0 0 0 6px;font-size:13px';
      fix.addEventListener('click', () => chrome.runtime.sendMessage({ type: 'OPEN_POPUP' }));
      text.appendChild(fix);
    }
    document.body.appendChild(toast);
    setTimeout(() => toast.remove(), type === 'error' ? 8000 : 5000);
  }
})();

// background.js - MV3 Service Worker
import { uploadSubmission } from './uploader.js';

const CLIENT_ID = '<YOUR_GITHUB_CLIENT_ID>';
const REDIRECT_URI = 'https://' + chrome.runtime.id + '.chromiumapp.org/';

chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === 'install') {
    chrome.tabs.create({ url: chrome.runtime.getURL('welcome/welcome.html') });
  }
});

chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === 'SYNC_SUBMISSION') { handleSync(msg.data).then(sendResponse); return true; }
  if (msg.type === 'START_AUTH')      { startGitHubAuth().then(sendResponse); return true; }
  if (msg.type === 'GET_STATS')       { chrome.storage.local.get(['stats'], r => sendResponse(r.stats || {})); return true; }
  if (msg.type === 'DISCONNECT')      { chrome.storage.local.clear(() => sendResponse({ success: true })); return true; }
});

// PRIMARY OAuth path
async function startGitHubAuth() {
  const authURL = 'https://github.com/login/oauth/authorize?client_id=' + CLIENT_ID +
    '&redirect_uri=' + encodeURIComponent(REDIRECT_URI) + '&scope=repo';
  return new Promise((resolve) => {
    chrome.identity.launchWebAuthFlow({ url: authURL, interactive: true }, async (redirectURL) => {
      if (chrome.runtime.lastError || !redirectURL) {
        resolve({ success: false, error: 'Auth window closed or blocked' }); return;
      }
      const code = new URL(redirectURL).searchParams.get('code');
      const token = await exchangeCodeForToken(code);
      await chrome.storage.local.set({ token });
      resolve({ success: true });
    });
  });
}

// FALLBACK for Brave Browser (blocks *.chromiumapp.org redirects in strict privacy mode)
chrome.tabs.onUpdated.addListener(async (tabId, changeInfo) => {
  if (changeInfo.url && changeInfo.url.includes('.chromiumapp.org/?code=')) {
    const code = new URL(changeInfo.url).searchParams.get('code');
    if (code) {
      const token = await exchangeCodeForToken(code);
      await chrome.storage.local.set({ token });
      chrome.tabs.remove(tabId);
    }
  }
});

async function exchangeCodeForToken(code) {
  const res = await fetch('https://github.com/login/oauth/access_token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
    body: JSON.stringify({ client_id: CLIENT_ID, code }),
  });
  const data = await res.json();
  return data.access_token;
}

async function handleSync(submission) {
  const { token, repoName } = await chrome.storage.local.get(['token','repoName']);
  if (!token) return { success: false, error: 'Not authenticated. Please reconnect GitHub.' };
  if (!repoName) return { success: false, error: 'No repository selected. Open settings.' };

  const result = await uploadSubmission(token, repoName, submission);
  if (result.success) {
    const { stats = { solved:0, easy:0, medium:0, hard:0 } } = await chrome.storage.local.get('stats');
    stats.solved++;
    const d = (submission.difficulty || '').toLowerCase();
    if (d) stats[d] = (stats[d] || 0) + 1;
    await chrome.storage.local.set({ stats });

    chrome.action.setBadgeText({ text: '✓' });
    chrome.action.setBadgeBackgroundColor({ color: '#10b981' });
    setTimeout(() => chrome.action.setBadgeText({ text: '' }), 5000);

    const { syncCount = 0 } = await chrome.storage.local.get('syncCount');
    await chrome.storage.local.set({ syncCount: syncCount + 1 });
    if ((syncCount + 1) % 15 === 0) result.showDonationNudge = true;
  }
  return result;
}

// uploader.js - GitHub REST API File Uploader
const GITHUB_API = 'https://api.github.com';
const LANG_EXT = { 'c++':'cpp',cpp:'cpp',java:'java',python:'py',python3:'py',
  javascript:'js',js:'js',typescript:'ts','c#':'cs',csharp:'cs',go:'go',rust:'rs',
  kotlin:'kt',swift:'swift',sql:'sql' };

export async function uploadSubmission(token, repoName, submission) {
  const { problemSlug, language, code, difficulty, topic, category } = submission;
  const ext  = LANG_EXT[language?.toLowerCase()] || 'txt';
  const cat  = sanitize(category);
  const top  = sanitize(topic);
  const slug = sanitize(problemSlug);

  // Check debounce (3 minutes per slug)
  const dbKey = 'db_' + slug;
  const { [dbKey]: last } = await chrome.storage.local.get(dbKey);
  if (last && Date.now() - last < 180000)
    return { success: false, error: 'Debounce cooldown (3 min). Already synced recently.' };

  const { login } = await getUser(token);
  const headers = { Authorization: 'token ' + token, 'Content-Type': 'application/json',
    Accept: 'application/vnd.github.v3+json' };

  const base = GITHUB_API + '/repos/' + login + '/' + repoName + '/contents/';
  const filePath = cat + '/' + top + '/' + slug + '/solution.' + ext;

  // Upload solution file (with SHA conflict retry)
  const sr = await putFile(base + filePath, headers,
    'Add ' + slug + ' [' + language + '] [TUFHub]',
    btoa(unescape(encodeURIComponent(code))));
  if (!sr.ok) return { success: false, error: 'GitHub API ' + sr.status };

  // Upload per-problem README stub
  const rm = '# ' + slug.replace(/-/g,'  ') + '\n\n**Difficulty:** ' + difficulty + ' | **Topic:** ' + topic;
  await putFile(base + cat + '/' + top + '/' + slug + '/README.md', headers,
    'Add ' + slug + ' README [TUFHub]', btoa(unescape(encodeURIComponent(rm))));

  await chrome.storage.local.set({ [dbKey]: Date.now() });
  return { success: true, filePath };
}

// PUT with automatic 409/422 SHA conflict retry
async function putFile(url, headers, message, content) {
  let body = { message, content, committer: { name:'TUFHub', email:'tufhub@noreply' } };
  let res = await fetch(url, { method:'PUT', headers, body: JSON.stringify(body) });
  if (res.status === 409 || res.status === 422) {
    const g = await fetch(url, { headers });
    if (g.ok) { body.sha = (await g.json()).sha; }
    res = await fetch(url, { method:'PUT', headers, body: JSON.stringify(body) });
  }
  return res;
}

async function getUser(token) {
  const r = await fetch(GITHUB_API + '/user', { headers:{ Authorization:'token ' + token } });
  return r.json();
}

function sanitize(s) {
  return (s || 'General').toLowerCase().replace(/\s+/g,'-').replace(/[^a-z0-9-]/g,'');
}

popup.js - Stats Dashboard

// popup.js - Extension toolbar popup
document.addEventListener('DOMContentLoaded', async () => {
  const { stats, token, repoName } = await chrome.storage.local.get(['stats','token','repoName']);
  const s = stats || { solved:0, easy:0, medium:0, hard:0 };
  document.getElementById('stat-solved').textContent = s.solved;
  document.getElementById('stat-easy').textContent   = s.easy   || 0;
  document.getElementById('stat-medium').textContent = s.medium || 0;
  document.getElementById('stat-hard').textContent   = s.hard   || 0;

  const banner = document.getElementById('auth-banner');
  if (!token) {
    banner.textContent = '⚠️ Not connected to GitHub';
    banner.style.background = '#450a0a';
  } else {
    banner.textContent = '✓ Connected | Repo: ' + (repoName || 'Not set');
    banner.style.background = '#052e16';
  }

  document.getElementById('btn-connect').addEventListener('click', async () => {
    const res = await chrome.runtime.sendMessage({ type: 'START_AUTH' });
    if (res.success) location.reload();
    else alert('Auth failed: ' + res.error);
  });

  document.getElementById('btn-disconnect').addEventListener('click', async () => {
    if (confirm('Disconnect GitHub? All local data will be cleared.')) {
      await chrome.runtime.sendMessage({ type: 'DISCONNECT' });
      location.reload();
    }
  });

  document.getElementById('btn-donate-upi').addEventListener('click', () => {
    document.getElementById('upi-modal').style.display = 'flex';
  });
});

welcome.js - 3-Step Onboarding Wizard

// welcome.js
let step = 0;
const steps = ['step-connect', 'step-repo', 'step-done'];
const show = (n) => steps.forEach((id, i) =>
  document.getElementById(id).style.display = i === n ? 'block' : 'none');

// Step 1: Connect GitHub OAuth
document.getElementById('btn-start-auth').addEventListener('click', async () => {
  const res = await chrome.runtime.sendMessage({ type: 'START_AUTH' });
  if (res.success) show(++step);
  else alert('Authentication failed: ' + res.error);
});

// Step 2: Create or select repository
document.getElementById('btn-create-repo').addEventListener('click', async () => {
  const name = document.getElementById('repo-name').value.trim() || 'TUF-Solutions';
  const isPrivate = document.getElementById('repo-private').checked;
  const { token } = await chrome.storage.local.get('token');
  const res = await fetch('https://api.github.com/user/repos', {
    method: 'POST',
    headers: { Authorization: 'token ' + token, 'Content-Type': 'application/json' },
    body: JSON.stringify({ name, private: isPrivate, auto_init: true }),
  });
  if (res.ok || res.status === 422) { // 422 = repo already exists
    await chrome.storage.local.set({ repoName: name });
    show(++step);
  } else {
    alert('Could not create repo. Check GitHub permissions.');
  }
});

show(0);

// webpack.config.js
const path = require('path');

module.exports = {
  mode: 'production',
  entry: {
    background:  './scripts/background.js',
    interceptor: './scripts/tuf/interceptor.js',
    content:     './scripts/tuf/content.js',
    uploader:    './scripts/uploader.js',
    popup:       './popup/popup.js',
    welcome:     './welcome/welcome.js',
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].js',
    clean: true,
  },
  optimization: {
    splitChunks: false,   // CRITICAL: each extension script must be self-contained
    runtimeChunk: false,
  },
  resolve: { extensions: ['.js'] },
};

Build Commands

# Install dependencies
npm install webpack webpack-cli --save-dev

# Production build (ready for Web Store)
npx webpack --mode production

# Development build (with source maps)
npx webpack --mode development

# Package for submission (PowerShell)
Compress-Archive -Path dist,manifest.json,popup,welcome,assets -DestinationPath TUFHub_v1.0.0.zip -Force

Every significant bug encountered during the 12-hour build session, its root cause, and the exact fix:

Pre-Submission Checklist

• 1. Create Chrome Web Store Developer Account (one-time $5 registration fee)Copy
• 2. Run production webpack build: npx webpack --mode productionCopy
• 3. ZIP the submission: dist/ + manifest.json + popup/ + welcome/ + assets/ (exclude node_modules/ and Python scripts)Copy
• 4. Drag-drop the ZIP into chrome://extensions in Developer Mode and test all flows before submittingCopy
• 5. Ensure Privacy Policy is live at a permanent public URL before submittingCopy

Store Listing Fields Used

Asset Specifications

Color Palette

• Background: #0b1120 - Deep Navy matching TUF platform dark mode
• Fire Orange glow: #f97316 alpha 90/255 for radial ellipse fill
• Royal Blue glow: #2563eb alpha 80/255 for radial ellipse fill
• macOS header bar: #1e293b background, #334155 URL bar
• Traffic lights: Red #ff5f57, Yellow #ffbd2e, Green #28c840
• Status dot: #22c55e green dot for "Active & Syncing" label

make_glowing_store_cards.py - Screenshot Framing Script

from PIL import Image, ImageDraw, ImageFilter
import os

W, H = 1280, 800
INPUT_DIR  = './screenshots_raw'
OUTPUT_DIR = './store-assets/screenshots'

def create_card(ss_path, out_path):
    bg = Image.new('RGBA', (W, H), (11, 17, 32, 255))

    # Fire Orange glow (top-right)
    g1 = Image.new('RGBA', (W, H), (0,0,0,0))
    ImageDraw.Draw(g1).ellipse((int(W*.55), -150, int(W*1.3), int(H*.75)), fill=(249,115,22,90))
    bg = Image.alpha_composite(bg, g1.filter(ImageFilter.GaussianBlur(130)))

    # Royal Blue glow (bottom-left)
    g2 = Image.new('RGBA', (W, H), (0,0,0,0))
    ImageDraw.Draw(g2).ellipse((-150, int(H*.4), int(W*.5), int(H*1.2)), fill=(37,99,235,80))
    bg = Image.alpha_composite(bg, g2.filter(ImageFilter.GaussianBlur(130)))

    # macOS browser chrome header
    draw = ImageDraw.Draw(bg)
    HEADER_H = 52
    draw.rounded_rectangle([60, 80, W-60, 80+HEADER_H], radius=12, fill=(30,41,59,255))
    for i, color in enumerate([(255,95,87),(255,189,46),(40,200,64)]):
        cx = 90 + i*24
        draw.ellipse([cx-7, 80+HEADER_H//2-7, cx+7, 80+HEADER_H//2+7], fill=color)
    draw.rounded_rectangle([160, 89, W-180, 123], radius=7, fill=(51,65,85,255))
    draw.text((180, 97), '●  takeuforward.org/plus', fill=(34,197,94))

    # Composite screenshot into content area
    if os.path.exists(ss_path):
        ss = Image.open(ss_path).convert('RGBA')
        ss.thumbnail((W-120, H-80-HEADER_H-60), Image.LANCZOS)
        bg.paste(ss, ((W-ss.width)//2, 80+HEADER_H+2), ss)

    bg.convert('RGB').save(out_path, 'PNG', optimize=True)
    print('Created:', out_path)

os.makedirs(OUTPUT_DIR, exist_ok=True)
for i, f in enumerate(sorted(os.listdir(INPUT_DIR))):
    if f.endswith(('.png','.jpg')):
        create_card(os.path.join(INPUT_DIR, f), os.path.join(OUTPUT_DIR, f'screenshot_{i+1:02d}.png'))

Supported Languages Table (1-Row Format)

## 💻 Supported Languages

| **C++** (`.cpp`) | **Java** (`.java`) | **Python** (`.py`) | **JavaScript** (`.js`) | **C#** (`.cs`) | **Go** (`.go`) | **SQL** (`.sql`) |
| :---: | :---: | :---: | :---: | :---: | :---: | :---: |

Key technical questions raised during the session and the architectural decisions they produced:

A complete engineering checklist derived from the TUFHub build session. Use this as a template for any production Chrome Extension:

Phase A: Ideation, Scope & Manifest V3 Core (Points 1-10)

• 1. Write a one-sentence 'Single Purpose Statement' that clearly describes what the extension does and nothing else.Copy
• 2. Define exact host_permissions - list ONLY the domains the extension actually communicates with.Copy
• 3. List all browser permissions needed and write a one-line justification for each (storage, identity, tabs, etc.).Copy
• 4. Decide: zero-server vs. backend-server architecture. Zero-server preferred for privacy-first tools.Copy
• 5. Specify manifest_version: 3 - MV2 is deprecated and will stop working.Copy
• 6. Decide background script type: event-driven service worker (MV3) vs. persistent background page (deprecated).Copy
• 7. Identify if content scripts need MAIN world (fetch/window access) or ISOLATED world (chrome APIs) - you may need both.Copy
• 8. Plan the user's onboarding flow: what must they configure before the extension is useful?Copy
• 9. Draft the privacy policy - what data is collected, where it goes, and how it is deleted.Copy
• 10. Identify all CSS class names that could trigger AdBlock filters (.social-*, .share-*, .donate-*) and rename them.Copy

Phase B: Service Worker & State Management (Points 11-20)

• 11. Use chrome.storage.local for all user data. Never store sensitive data in chrome.storage.sync (100KB limit).Copy
• 12. Handle service worker termination: MV3 service workers idle-terminate. Keep all operations under 25 seconds.Copy
• 13. Use chrome.runtime.onInstalled to open onboarding page only on first install (check details.reason === 'install').Copy
• 14. Return true from chrome.runtime.onMessage listener if the response is async (keeps message channel open).Copy
• 15. Implement a 'Disconnect / Reset' flow that clears all stored data (token, stats, settings) in one operation.Copy
• 16. Add chrome.action.setBadgeText for visual feedback on sync success/error state without requiring popup open.Copy
• 17. Always check for auth token before performing API calls. Return a clear error message if missing.Copy
• 18. Implement OAuth token refresh or re-auth flow for when tokens expire.Copy
• 19. Never log sensitive data (tokens, private code) to console.log - logs are visible in chrome://extensions devtools.Copy
• 20. Test service worker termination by waiting 30s idle and then triggering an action - ensure state reloads from storage correctly.Copy

Phase C: Network Interception & World Isolation (Points 21-30)

• 21. Always clone the Response before reading: response.clone().json() - never consume the original stream.Copy
• 22. Wrap all interception logic in try/catch with silent catch - never throw errors that could break the host page.Copy
• 23. Store the original fetch reference immediately: const _originalFetch = window.fetch before any page scripts modify it.Copy
• 24. Bridge MAIN to ISOLATED via document.dispatchEvent(new CustomEvent(...)) - the ONLY safe communication channel.Copy
• 25. Use specific URL pattern matching (regex) - never intercept ALL fetch requests, only exact API endpoints needed.Copy
• 26. Test interception with both window.fetch AND XMLHttpRequest - some platforms use XHR even today.Copy
• 27. For OAuth: implement both launchWebAuthFlow (primary) and tab URL listener fallback (for Brave and strict privacy browsers).Copy
• 28. Implement debounce per resource identifier (problem slug, URL, ID) to prevent duplicate API calls.Copy
• 29. Handle GitHub API 409 Conflict: GET existing file SHA, then retry PUT with sha field included in body.Copy
• 30. Use btoa(unescape(encodeURIComponent(content))) for Base64 encoding any content that may contain Unicode.Copy

Phase D: Content Scripts, DOM & UX (Points 31-40)

• 31. Inject UI elements with unique, prefixed IDs to avoid conflicts with host page DOM (id="tufhub-toast" not id="toast").Copy
• 32. Always use z-index: 2147483647 (max int32) for injected overlays to ensure they appear above host page elements.Copy
• 33. Add CSS animations via injected <style> tags, not external CSS files (content script CSS can cause FOUC).Copy
• 34. Auto-dismiss toasts (5s for success, 8s for error). Include manual close button for accessibility.Copy
• 35. Add role="alert" to notification elements for screen reader accessibility.Copy
• 36. Use inline CSS (style.cssText) for injected elements - extension CSS files are not guaranteed to load in all contexts.Copy
• 37. Remove any pre-existing injected elements before re-injecting: document.getElementById('tufhub-toast')?.remove().Copy
• 38. For popup UI: use DOMContentLoaded not load event - popup has no external resources to wait for.Copy
• 39. Implement micro-interactions: hover scale(1.05) with cubic-bezier easing, active press scale(0.97).Copy
• 40. Test all UI elements with AdBlock Plus, uBlock Origin, and Brave Shields enabled.Copy

Phase E: Build, Store Graphics & Submission Audit (Points 41-50)

• 41. Use Webpack 5 multi-entry build with splitChunks: false - extension scripts must be self-contained bundles.Copy
• 42. Verify the ZIP package contains: manifest.json at root, all scripts in dist/, and all referenced assets.Copy
• 43. Test the packed ZIP by drag-dropping it into chrome://extensions in Developer Mode before submitting.Copy
• 44. Create icons in all 4 required sizes: 16px, 32px, 48px, 128px. Test at 16px - must be recognizable.Copy
• 45. Generate 5 screenshots at 1280x800. Use Python Pillow to add browser chrome framing and ambient glow halos.Copy
• 46. Create small promo tile (440x280) and marquee promo tile (1400x560) with consistent visual identity.Copy
• 47. Host Privacy Policy at a permanent public URL (GitHub Pages works). Include: what is collected, not collected, storage duration, deletion method.Copy
• 48. Write permission justification text for EVERY permission requested - the review form requires it for each.Copy
• 49. Self-audit: search all source files for eval(, innerHTML =, document.write( - all will cause rejection.Copy
• 50. After approval: monitor reviews, respond to issues via GitHub Issues, and use remote config (Gist) to patch DOM selectors without republishing.Copy