Skip to content

CLAUDE.md

Latest commit

 

History

History
82 lines (55 loc) · 3.42 KB

CLAUDE.md

File metadata and controls

82 lines (55 loc) · 3.42 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

BackToClose is a browser extension that closes the active tab when the user hits back on the last history entry in the session, replicating Safari's iOS behavior. The extension works with Chrome and Firefox using Manifest v3.

Development Commands

  • pnpm dev - Start development server for Chrome
  • pnpm dev:firefox - Start development server for Firefox
  • pnpm build - Build for Chrome
  • pnpm build:firefox - Build for Firefox
  • pnpm zip - Create distribution package for Chrome
  • pnpm zip:firefox - Create distribution package for Firefox
  • pnpm compile - Type check without emitting files

Architecture

Core Components

  • Background Script (src/entrypoints/background.ts): Manages tab tracking, injects content scripts into qualifying tabs, and handles tab closure
  • Content Script (src/entrypoints/content.ts): Manipulates browser history and listens for PopStateEvents to trigger tab closure
  • Popup (src/entrypoints/popup/): Extension configuration UI

Tab Tracking Logic

The extension identifies 3 types of new tabs:

  1. New empty tab (showing the new tab page) - identified using the URL
  2. New child tab (open in new tab from another tab) - identified using the openerTabId property and the URL
  3. Others

By default, only child tabs (type 2) are tracked.

History Manipulation

Content scripts modify the browser history stack by:

  1. Changing the first history entry to have title "Close Tab" with special state
  2. Pushing the current page as the next entry
  3. Waiting for user interaction before applying changes (browser security requirement)
  4. Listening for PopStateEvents to detect back navigation to the special entry

Technology Stack

  • WXT Framework: Browser extension development framework
  • TypeScript: Primary language
  • pnpm: Package manager
  • Manifest v3: Extension API version
  • Use @https://jj-vcs.github.io for version control. YOU MUST ALWAYS USE JUJUTSU TO CREATE COMMITS. NEVER COMMIT WITH GIT. DO NOT USE GIT TO CREATE COMMITS, but you MAY use git to read commits or otherwise gather information.

Project Structure

  • src/entrypoints/ - Extension entry points (background, content, popup)
  • src/components/ - Reusable components
  • src/assets/ - Static assets
  • public/ - Public files for extension
  • wxt.config.ts - WXT framework configuration

Browser-Specific Development Notes

Chrome

  • The OpenerTabId property is also available in new empty tabs
  • All tabs (including new empty tabs) have URL '' when first created, except for reopened tabs which have the last URL in the history of the tab
  • Get the actual URL using chrome.tabs.get after tab creation and check for pendingUrl or url. If the URL is 'chrome://newtab/' then it is a new empty tab

Firefox

  • New empty tabs have URL 'about:newtab', while other new tabs have URL 'about:blank' when first created
  • The OpenerTabId property is only available in child tabs

References

After every edit, remember to commit your changes using jujutsu (jj) with a clear and descriptive commit message using the command: jj commit -m "Your commit message here"