Extension Dev

Conventions de projet obligatoires

TypeScript strict

• NO any — types stricts pour toutes les APIs Chrome/Firefox
• Utiliser @types/chrome pour le typage des APIs Chrome
• Importer les types partages depuis @focus-shield/shared-types

Structure des fichiers

apps/browser-extension/
  src/
    background/
      index.ts              # Service worker entry point
      rules-manager.ts      # Gestion dynamique des declarativeNetRequest rules
      message-handler.ts    # Message passing (popup <-> background <-> content)
      native-messaging.ts   # Communication avec l'app desktop
      websocket-client.ts   # Fallback WebSocket
    content/
      index.ts              # Content script principal
      anti-bypass.ts        # Detection de tentatives de contournement
    popup/
      App.tsx               # UI React de la popup
      components/           # Composants popup (MiniTimer, StatusBadge, QuickActions)
      main.tsx              # Entry point React
    blocked/
      App.tsx               # Page de blocage React
      components/           # Composants (Quote, Timer, BreathingExercise, Counter)
      main.tsx              # Entry point React
    shared/
      storage.ts            # Wrapper chrome.storage.local/sync
      messaging.ts          # Helpers pour le message passing type-safe
      constants.ts          # IDs, clefs, etc.
  manifest.json             # Manifest V3
  manifest.firefox.json     # Overrides pour Firefox
  package.json
  tsconfig.json
  vite.config.ts            # Multi-entry build (background, content, popup, blocked)

Nommage

• Memes conventions que le reste du projet (camelCase fonctions, PascalCase types)
• Fichiers en kebab-case

Commits

• Format : type(scope): description
• Scopes : extension, extension-bg, extension-popup, extension-blocked
• Exemples : feat(extension): add declarativeNetRequest dynamic rules, fix(extension-popup): timer display on small popups

Patterns a utiliser

1. Manifest V3 structure

{
  "manifest_version": 3,
  "name": "Focus Shield",
  "version": "1.0.0",
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
    "storage",
    "alarms",
    "notifications",
    "nativeMessaging",
    "tabs"
  ],
  "optional_permissions": [
    "incognito"
  ],
  "host_permissions": ["<all_urls>"],
  "background": {
    "service_worker": "src/background/index.ts",
    "type": "module"
  },
  "content_scripts": [{
    "matches": ["<all_urls>"],
    "js": ["src/content/index.ts"],
    "run_at": "document_start"
  }],
  "action": {
    "default_popup": "src/popup/index.html"
  },
  "declarative_net_request": {
    "rule_resources": [{
      "id": "static_rules",
      "enabled": true,
      "path": "rules/static-rules.json"
    }]
  }
}

2. Dynamic rules management

// background/rules-manager.ts
interface BlockingSession {
  domains: string[];
  allowlist: string[];
}

const RULE_ID_OFFSET = 1000; // Reserve 1-999 pour les static rules

async function applyBlockingRules(session: BlockingSession): Promise<void> {
  // Supprime les anciennes rules dynamiques
  const existingRules = await chrome.declarativeNetRequest.getDynamicRules();
  const existingIds = existingRules.map(r => r.id);

  const newRules: chrome.declarativeNetRequest.Rule[] = session.domains.map((domain, i) => ({
    id: RULE_ID_OFFSET + i,
    priority: 1,
    action: {
      type: chrome.declarativeNetRequest.RuleActionType.REDIRECT,
      redirect: {
        extensionPath: '/blocked/index.html'
      }
    },
    condition: {
      urlFilter: `||${domain}`,
      resourceTypes: [
        chrome.declarativeNetRequest.ResourceType.MAIN_FRAME
      ]
    }
  }));

  // Ajouter les allowlist rules avec priorite superieure
  const allowRules: chrome.declarativeNetRequest.Rule[] = session.allowlist.map((pattern, i) => ({
    id: RULE_ID_OFFSET + session.domains.length + i,
    priority: 2, // Priorite superieure = bypass le block
    action: { type: chrome.declarativeNetRequest.RuleActionType.ALLOW },
    condition: {
      urlFilter: pattern,
      resourceTypes: [chrome.declarativeNetRequest.ResourceType.MAIN_FRAME]
    }
  }));

  await chrome.declarativeNetRequest.updateDynamicRules({
    removeRuleIds: existingIds,
    addRules: [...newRules, ...allowRules]
  });
}

async function clearAllDynamicRules(): Promise<void> {
  const rules = await chrome.declarativeNetRequest.getDynamicRules();
  await chrome.declarativeNetRequest.updateDynamicRules({
    removeRuleIds: rules.map(r => r.id)
  });
}

3. Type-safe message passing

// shared/messaging.ts
type MessageMap = {
  'session:start': { config: SessionConfig; response: { ok: boolean } };
  'session:stop': { response: { ok: boolean } };
  'session:status': { response: SessionStatus | null };
  'rules:update': { domains: string[]; allowlist: string[]; response: void };
  'stats:attempt': { domain: string; timestamp: number; response: void };
};

type MessageType = keyof MessageMap;

interface Message<T extends MessageType> {
  type: T;
  payload: Omit<MessageMap[T], 'response'>;
}

function sendMessage<T extends MessageType>(
  type: T,
  payload: Omit<MessageMap[T], 'response'>
): Promise<MessageMap[T]['response']> {
  return chrome.runtime.sendMessage({ type, payload });
}

function onMessage<T extends MessageType>(
  type: T,
  handler: (
    payload: Omit<MessageMap[T], 'response'>,
    sendResponse: (response: MessageMap[T]['response']) => void
  ) => void | boolean
): void {
  chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
    if (message.type === type) {
      return handler(message.payload, sendResponse);
    }
  });
}

4. Service worker lifecycle management

// background/index.ts
// Le service worker Manifest V3 peut etre tue a tout moment.
// Persister l'etat critique dans chrome.storage.local.

chrome.runtime.onInstalled.addListener(async (details) => {
  if (details.reason === 'install') {
    // Premier install : initialiser le storage
    await chrome.storage.local.set({ sessionActive: false, rules: [] });
  }
});

// Au reveil du service worker : restaurer l'etat
async function restoreState(): Promise<void> {
  const data = await chrome.storage.local.get(['sessionActive', 'currentSession']);
  if (data.sessionActive && data.currentSession) {
    await applyBlockingRules(data.currentSession);
  }
}
restoreState();

// Utiliser les alarms pour les timers (les setTimeout ne survivent pas au kill)
chrome.alarms.onAlarm.addListener(async (alarm) => {
  if (alarm.name === 'session-tick') {
    await handleSessionTick();
  }
  if (alarm.name === 'session-end') {
    await handleSessionEnd();
  }
});

5. Native Messaging avec l'app desktop

// background/native-messaging.ts
const NATIVE_HOST = 'com.focusshield.connector';

let port: chrome.runtime.Port | null = null;

function connectToDesktop(): chrome.runtime.Port {
  port = chrome.runtime.connectNative(NATIVE_HOST);

  port.onMessage.addListener((message: unknown) => {
    // Messages venant du desktop
    handleDesktopMessage(message);
  });

  port.onDisconnect.addListener(() => {
    port = null;
    // Fallback vers WebSocket si Native Messaging echoue
    connectViaWebSocket();
  });

  return port;
}

function sendToDesktop(message: object): void {
  if (port) {
    port.postMessage(message);
  } else {
    sendViaWebSocket(message);
  }
}

6. Page de blocage

// blocked/App.tsx
function BlockedPage() {
  const [session, setSession] = useState<SessionInfo | null>(null);
  const [quote, setQuote] = useState<Quote | null>(null);
  const [attemptCount, setAttemptCount] = useState(0);

  useEffect(() => {
    // Recuperer les infos de session depuis le background
    sendMessage('session:status', {}).then(setSession);
    // Charger une citation random
    loadRandomQuote().then(setQuote);
    // Logger la tentative de distraction
    const url = new URL(window.location.href);
    const blockedDomain = url.searchParams.get('domain') || 'unknown';
    sendMessage('stats:attempt', {
      domain: blockedDomain,
      timestamp: Date.now()
    });
  }, []);

  return (
    <div className="min-h-screen flex flex-col items-center justify-center bg-gray-50 dark:bg-gray-900 p-8">
      <div className="max-w-md text-center space-y-6">
        <h1 className="text-2xl font-bold text-gray-900 dark:text-gray-100">
          Site bloque
        </h1>
        {session && <SessionTimer endTime={session.endTime} />}
        {quote && (
          <blockquote className="text-gray-600 dark:text-gray-400 italic">
            "{quote.text}" — {quote.author}
          </blockquote>
        )}
        <p className="text-sm text-gray-500">
          {attemptCount} tentative(s) bloquee(s) cette session
        </p>
        <button
          onClick={() => window.history.back()}
          className="px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
        >
          Retour au travail
        </button>
      </div>
    </div>
  );
}

Anti-patterns a eviter

Contraintes Manifest V3

• Service worker : pas de DOM, pas de window, pas d'etat persistant en memoire
• CSP : pas de eval, pas de unsafe-inline, pas de remote code
• declarativeNetRequest : max 5000 dynamic rules, max 300000 static rules
• Alarms : minimum 1 minute d'intervalle (en release, 30s en dev)
• Storage : chrome.storage.local = 10MB max, chrome.storage.sync = 100KB max
• Native Messaging : messages max 1MB, necessite un host manifest natif installe
• Incognito : opt-in par l'utilisateur, pas force par l'extension

Cross-browser compatibility

Utiliser webextension-polyfill pour normaliser les APIs :

import browser from 'webextension-polyfill';
// Utiliser browser.* au lieu de chrome.* pour la compatibilite

Mission

Implemente dans l'extension navigateur : {{input}}

Methodologie

1. Analyse — Lis le manifest.json et les fichiers existants dans apps/browser-extension/src/
2. Manifest — Verifie que les permissions necessaires sont declarees
3. Implementation — Code avec les patterns ci-dessus, respecte les contraintes MV3
4. Message passing — Si communication inter-contextes necessaire, utilise le pattern type-safe
5. Compatibilite — Verifie que le code fonctionne sur Chrome ET Firefox
6. Build — Verifie le build multi-entry :

   # Build de l'extension
   npm run build -- --filter browser-extension
   # Type check
   npx tsc --noEmit -p apps/browser-extension/tsconfig.json
   # Tests
   npx vitest run apps/browser-extension
   

Regles de livraison

• MV3 compliant — Aucune API Manifest V2 (webRequest, persistent background, etc.)
• State resilient — Le service worker peut etre tue : l'etat est dans chrome.storage
• Cross-browser — Compatible Chrome 116+ et Firefox 109+
• Permissions minimales — Seules les permissions necessaires dans le manifest
• Pas de remote code — Tout le JS est bundle localement
• Page de blocage UX — Message clair, timer visible, bouton retour