Separator Page - AI Coding Instructions

Project Overview

A self-contained browser tab organizer that creates customizable separator pages. The entire application lives in a single HTML file (index.html) with embedded CSS and JavaScript.

Architecture Patterns

Single-File Web App

• Everything embedded in index.html: HTML structure, CSS styles, JavaScript logic
• No build process, bundlers, or external dependencies beyond CDN libraries
• Uses showdown.js from CDN for Markdown rendering

Dual Storage Pattern

• Per-tab data: localStorage['separator-tab-${tabId}'] stores individual separator content (title, description, icon)
• Global shared data: localStorage['separator-previous-icons'] stores icon history across all tabs
• Tab ID generation: URL param ?tab=X or timestamp-based fallback

State Management

• No frameworks - direct DOM manipulation with cached element references
• Save-on-change pattern: every user action triggers saveTabData()
• URL params control initial state: ?name=X sets title, ?tab=X sets storage key

Icon System Architecture

Three-Tier Icon Management

1. Current icon: Synced between preview, favicon, and localStorage
2. Previous icons: Global history with deduplication and 100-item limit
3. Default icons: Static array from ./icons/template-icon-*.png files

Multi-Modal Icon Input

• Drag & drop image files (converts to data URLs)
• Paste images from clipboard
• URL input field
• Click selection from previous icons grid

Icon Interaction Patterns

// Standard pattern for icon click handling
iconElement.addEventListener("click", async (event) => {
    if (event.shiftKey) {
        removePreviousIcon(iconUrl);           // Remove from history
    } else if (event.ctrlKey || event.metaKey) {
        await downloadImageAsFile(iconUrl, filename); // Download individual
    } else {
        handleIconChange(iconUrl);             // Set as current
    }
});

Key Conventions

Element Selection Pattern

All DOM elements cached as typed constants at script start:

/** @type {HTMLElement} */
const iconPreview = document.getElementById("icon-preview");

Background Image Styling

• Preview icons: Use background-size: contain to show full image
• Grid icons: Use background-size: cover for consistent thumbnails
• Always set background-position: center and background-repeat: no-repeat

Data URL Handling

• Skip data:image/x-icon URLs in icon history (default favicon)
• Convert external images to data URLs for persistence
• Use Canvas API for cross-format PNG conversion

Development Workflows

Local Testing

• Open index.html directly in browser - no server required
• Default icons load from ./icons/ directory (14 template icons)
• Uses relative paths - deploy anywhere that serves static files

Icon Management

• Export: Downloads all current icons as template-icon-1.png, template-icon-2.png, etc.
• Reset: Restores to default icon set from ./icons/ folder
• Individual download: Ctrl/Cmd+click any icon for single file download

Debugging State

• Check localStorage['separator-tab-${tabId}'] for current tab data
• Check localStorage['separator-previous-icons'] for global icon history
• Console logs with console.debug() for major state changes

External Integration

• Designed for browser bookmark usage - bookmark the URL for instant separator creation
• Works with tab tree extensions (Firefox Tree Style Tab shown in screenshots)
• Markdown content rendered via Showdown.js with default settings
• All links in rendered content open in new tabs (target="_blank")