Skip to content

CLAUDE.md

Latest commit

 

History

History
252 lines (193 loc) · 9.25 KB

CLAUDE.md

File metadata and controls

252 lines (193 loc) · 9.25 KB
Raw

CLAUDE.md

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

Project Overview

This repository contains two browser extensions:

  1. Word Template Extension - Extracts data from websites and populates Word templates
  2. Scan Overlay Extension - Provides scanning workflows with overlays, feedback, and accessibility features

Development Commands

Scheduled Print Service

CRITICAL: Always publish to the SAME folder after ANY code changes

cd scheduled-print-service
powershell -ExecutionPolicy Bypass -File scripts/publish.ps1

NEVER create new publish folders. ALWAYS use the publish script.

  • Correct: scheduled-print-service/publish/ (output from publish.ps1)
  • Wrong: scheduled-print-service/ScheduledPrintService/bin/publish/
  • Wrong: Any other location

After any code modification:

  1. Run the publish script: powershell -ExecutionPolicy Bypass -File scripts/publish.ps1
  2. Verify files are in scheduled-print-service/publish/
  3. The script automatically builds and publishes with self-contained deployment

Word Template Extension

Building Packages

# Build distribution packages for Chrome/Edge stores
cd word-template-extension
powershell -ExecutionPolicy Bypass -File build-packages.ps1

# Build with specific version
powershell -ExecutionPolicy Bypass -File build-packages.ps1 -Version "1.0.1"

# Build including source code
powershell -ExecutionPolicy Bypass -File build-packages.ps1 -IncludeSource

# Skip native host build
powershell -ExecutionPolicy Bypass -File build-packages.ps1 -BuildNativeHost:$false

Native Host Development

cd word-template-extension/native-host

# Install Python dependencies
pip install -r requirements.txt

# Test native host manually
echo '{"action":"ping"}' | python word_updater.py

# Build standalone executable
pip install pyinstaller
pyinstaller --onefile --console --name word_updater word_updater.py

Installation (Windows)

cd word-template-extension/native-host
# Run as Administrator
install.bat

Scan Overlay Extension

Enhanced scanning extension with configurable selectors and improved UI:

Development Commands

cd scan-overlay-extension

# Generate audio files (open in browser)
# Open generate-audio.html in browser to create MP3 files
# Download generated files and place in audio/ folder

# No build process required - load unpacked for development

Configuration

  • Settings Page: Full settings interface at settings.html
  • Configurable Selectors: XPath/CSS selectors can be customized
  • Audio Generation: Use generate-audio.html to create custom sound files

Architecture

Word Template Extension

  • Browser Extension: Manifest v3 extension with popup, content scripts, and service worker
  • Native Host: Python application using python-docx for Word document processing
  • Communication: Native messaging protocol between extension and Python host
  • Template System: Word documents with {{PLACEHOLDER}} syntax for dynamic content

Key components:

  • extension/background.js: Service worker handling native messaging and data extraction
  • extension/popup.js: UI for template selection and data preview
  • extension/content.js: Web page data extraction
  • native-host/word_updater.py: Template processing and document generation

Scan Overlay Extension

  • Browser Extension: Enhanced Manifest v3 with configurable selectors and modern UI
  • Settings System: Comprehensive settings page with field selector configuration
  • Audio Feedback: Generated MP3 files for scan events with volume control
  • Overlay System: Dynamic overlays with accessibility features and customizable appearance

Key components:

  • background.js: Event logging, tab management, and settings synchronization
  • content.js: Configurable field monitoring, API interception, and scan handling
  • overlay.js: Dynamic overlay rendering with settings integration
  • popup.js: Modern popup interface with field detection and quick settings
  • settings.js: Full settings management page
  • generate-audio.html: Audio file generation tool

File Structure

BrowserExtensions/
├── word-template-extension/
│   ├── extension/              # Browser extension files
│   ├── native-host/           # Python native messaging host
│   ├── templates/             # Sample Word templates
│   ├── build-packages.ps1     # Build script for distribution
│   └── *.md                   # Documentation files
├── scan-overlay-extension/    # Complete browser extension
│   ├── audio/                 # Sound effects
│   └── *.js, *.html, *.css   # Extension files
└── css-js-toinject/           # Injectable scripts for website enhancement
    ├── router.js              # Main routing logic
    ├── auto-print-buttons.js  # Auto print buttons feature
    ├── ui-feedback.js         # Overlay system + popup controller (replaces overlay-manager.js)
    ├── status-dropdown.js     # Status dropdown controls
    ├── table-item-linker.js   # SKU/Qty clickable items
    ├── item-line-id.js        # Item line ID column
    └── *.md                   # Feature documentation

Key Technologies

Word Template Extension

  • JavaScript: ES6+ with Chrome extension APIs
  • Python 3.7+: Native host with python-docx library
  • Native Messaging: JSON protocol for browser-Python communication
  • Word Processing: Template placeholders like {{EMAIL}}, {{DATE}}, {{AMOUNT}}

Scan Overlay Extension

  • JavaScript: Vanilla JS with Chrome extension APIs
  • CSS: Custom styling for overlays
  • Web Audio API: Sound feedback system

Development Notes

  • Both extensions use Manifest v3
  • Word Template Extension requires Python runtime and native host registration
  • Native messaging host manifest must be registered in Windows registry
  • Templates use double-brace syntax: {{PLACEHOLDER_NAME}}
  • Build script creates packages for Chrome Web Store and Edge Add-ons
  • Extension IDs and native host names are hardcoded in configuration files

Documentation Standards

IMPORTANT: All documentation files must be created in the docs folder within each project.

  • Scheduled Print Service: All .md documentation files should be placed in scheduled-print-service/docs/
  • Word Template Extension: All .md documentation files should be placed in word-template-extension/docs/
  • Scan Overlay Extension: All .md documentation files should be placed in scan-overlay-extension/docs/
  • CSS-JS-ToInject: All .md documentation files should be placed in css-js-toinject/docs/

Exception: Project root files like README.md and CLAUDE.md should remain in the root directory.

Testing

Word Template Extension

  • Test native host: echo '{"action":"ping"}' | python word_updater.py
  • Load extension unpacked from extension/ folder
  • Verify native messaging registration in browser console
  • Test with sample templates in templates/ folder

Scan Overlay Extension

  • Load unpacked from root folder
  • Test overlay rendering on various websites
  • Verify audio feedback functionality
  • Check accessibility features with screen readers

CSS-JS-ToInject Scripts

Injectable scripts for enhancing the 3PL website:

Auto Print Buttons Feature (#outbound/packing)

  • Monitors "Create Shipment" button clicks
  • Automatically combines "Print Carton Label" + "Packing Slip" buttons
  • Prints Carton Label first (async API), waits for completion
  • Then prints Packing Slip second (prevents window overlap)
  • Auto-clicks ONLY when "Create Shipment" button was pressed
  • See AUTO-PRINT-BUTTONS-README.md and SEQUENTIAL-PRINTING-EXPLANATION.md for details

Testing:

// Disable auto-click
window.autoPrintButtons.setAutoClick(false);

// Manual trigger
window.autoPrintButtons.printAll();

// View configuration
window.autoPrintButtons.config

Status Dropdown (#outbound/ProcessPersonalizedOrderItems)

  • Adds status dropdown to page tools
  • Auto-fills status-scan input field
  • Enlarges scan modal for better visibility

Item Line ID Column (#outbound/ProcessPersonalizedOrderItems)

  • Adds Item Line ID column to order items table
  • Auto-populates from API responses
  • Watches for table changes via MutationObserver

Packing Slip Column (#outbound/shipment)

  • Adds "Packing Slip" link column to shipment table
  • Links to #outbound/packingSlipdetail?id=<shipmentId>
  • Updates dynamically as table loads

Placard Text Enhancement (#Outbound/shipmentdetails)

  • Doubles text sizes on shipping placards
  • Makes all text bold for better readability
  • Works in iframes and main document

Production Status Column (#SO/orderdetails)

  • Adds "Production Status" column to order items table
  • Intercepts API responses to get ItemStatusId for each item
  • Looks up status names from session storage
  • Updates dynamically as table loads
  • See docs/PRODUCTION-STATUS-COLUMN.md for full documentation

Testing:

// Refresh the column manually
window.productionStatusAPI.refreshColumn();

// View stored API data
console.log(window.productionStatusAPI.store.data);

// Get status list
console.log(window.productionStatusAPI.getStatusList());