toolboximage.com/AGENTS.md at main · arhan18/toolboximage.com

Development

When starting the dev server, use background mode:

astro dev --background

Manage the background server with astro dev stop, astro dev status, and astro dev logs.

MANDATORY: New Tool Workflow

Every new tool MUST follow ALL steps below. Skipping any step is a bug.

Phase 1: Research (MANDATORY — do this first)

Read the Bible — Read bible/README.md + all handbook docs relevant to the tool category
GitHub research — Search for 5-10 high-quality open-source implementations of the tool. Study their architecture, algorithms, browser APIs, performance, UX, error handling, edge cases, memory management, file handling, security. Do NOT copy code — learn from the best and build original.
Ahrefs keyword research — Use Ahrefs Free Keyword Generator (or equivalent) to identify: primary keyword, secondary keywords, long-tail keywords, question keywords, related searches, low-competition keywords, high-traffic keywords. Record the findings.

Phase 2: SEO Ecosystem (MANDATORY — before or alongside tool build)

Tool page SEO — Title tag, meta description, H1, H2/H3 headings, 600-1000+ words unique content, FAQ + JSON-LD FAQ Schema, Breadcrumb Schema + SoftwareApplication Schema, Open Graph tags + Twitter Cards
Blog post — Create an SEO-optimized blog post targeting the primary keyword (1500+ words). Include FAQ, internal links to the tool and related tools, structured data.
Supporting pages — When keyword research shows meaningful search demand, create format-specific, size-specific, use-case, or comparison landing pages.
Internal linking — Link related tools together, link blog post to the tool, link tool to blog post, update related tools sections in existing pages.

Phase 3: Implementation

Build the tool — Follow the existing component patterns (ToolUpload + hidden file input interceptor, ToolSettingsPanel, etc.). Register in types, tools.ts, catch-all route, tools/[tool].astro, HomeContent.astro, translations (13 languages), ToolSeoContent.astro.
E2E tests — Add to helpers.ts, tools.spec.ts (upload + interaction + download), translations.spec.ts (3-4 languages).

Phase 4: Validation (MANDATORY — never skip)

Tool-specific validation — Read the relevant Bible handbook. Test like a real user: upload, process, preview, download, verify output correctness, edge cases, mobile/desktop layout, dark mode.
Preview matches export — Verify that what the user sees in preview exactly matches the downloaded file (dimensions, quality, pixel content).
Calculations are correct — Verify all numeric outputs (dimensions, file sizes, quality percentages, etc.).
Build — npm run build must pass with zero errors.

Rules

NEVER skip Phase 1-2. Research and SEO are not optional extras — they are part of the tool.
NEVER assume a blog post, FAQ, or keyword research is "done later." It must be done before the tool is considered complete.
CRITICAL: NEVER write SEO content, blog posts, or FAQ without Ahrefs keyword research data. Using general knowledge or assumptions instead of actual keyword data is a bug. Always run Ahrefs Free Keyword Generator (or equivalent) first to identify primary keyword, secondary keywords, long-tail keywords, question keywords, related searches, low-competition keywords, and high-traffic keywords. Record the findings. Then base all SEO content, blog headings, FAQ questions, and metadata exclusively on that data.
Read the Bible bible/TOOL_PRIORITY.md to pick the next tool.
Read the Bible handbook for the specific tool category before implementing.
If a bug is discovered post-implementation, add a handbook rule to prevent it recurring.

Session Memory

Key facts about this project (read before starting new tasks):

Site: ToolBox Image (toolboximage.com) — privacy-first, browser-based image compression
Deploy: Cloudflare Pages via npm run deploy (wrangler). Production branch is main
Analytics: Cloudflare Web Analytics (cookieless, no consent banner needed)
SEO: 43 pages, sitemap auto-generated, good SEO meta + JSON-LD on all pages
Blog posts (19 total): why-client-side, image-compression-basics, designing-the-compressor, introducing-toolboximage, choose-image-format, batch-compression-guide, image-size-limits-social-email, compress-to-exact-file-size, png-vs-webp-vs-avif, heic-to-jpg-guide, social-media-image-sizes, image-compression-ecommerce, privacy-first-image-tools, optimize-images-wordpress, remove-exif-data-online, webp-vs-avif-comparison, reduce-image-size-without-losing-quality, how-to-convert-images-online, how-to-resize-images-for-social-media
Blog infrastructure: Categories (guides/tutorials/technology/privacy/general + "All Posts" filter tabs), multiple tags per post with clickable tag cloud sidebar, featured posts, related posts sidebar, tag-based URL filtering
Pending user actions: Submit to 5 directories (AlternativeTo, FreeForDev, SaasHub, DevHunt, AwesomeList), post Show HN, set GitHub repo description/topics
Monetization: /support page with PayPal.Me (arhanahmadkhan) + UPI (8115033956@ptyes). AdSense is active. Next steps: affiliate links, Pro tier.
Privacy/FAQ pages: Updated to honestly disclose Cloudflare Web Analytics
Font optimizations: Only preload Regular (font-display: swap for others)
Share buttons: Added to compressor result page (Twitter/X, Reddit, Email)
Competitor reference: https://imagetoolbox.app — they have 24+ tools (converters, PDF tools, AI tools, passport photo, background remover). User wants to build similar tools directory with working tools under hero section (pattern: "All / Convert / Resize / Edit / Optimize" tabs)
Live tools (8): Image Compressor, Bulk Compressor, Compress JPEG/PNG/WebP/AVIF/GIF/for-Web/for-Ecommerce, 100KB/Email/Discord/WhatsApp/Instagram targets, Rotator, Format Converter, Image Resizer, Cropper
Tools directory: /image-tools/ has tabbed layout (All/Compress/Transform/Convert/Analyze). Homepage now has 12-card tools grid below hero, matching competitor layout
Updated this session: Homepage tools grid added with live/soon status dots, link to /image-tools/, ToolUpload component got live upload handling JS (fixes rotator/tool uploads), rotate tool flip buttons fixed, homepage upload now shows tool picker overlay instead of auto-redirecting to compressor, search bar added above tools grid. Rotator status changed to Live on homepage. Playwright E2E tests added (pages.spec.ts, language.spec.ts, tools.spec.ts, translations.spec.ts). Full tools directory (/image-tools/) now renders correctly in all 13 language pages. Auto-scroll on upload added to all tools (CompressorTool, ToolUpload, RotatorTool). File persistence across language switch added via beforeunload + IndexedDB. Two competitor comparison pages created: toolbox-vs-squoosh.astro and toolbox-vs-tinycompressor.astro (both registered in catch-all route, translation keys for 13 languages, linked from CompressorSeoContent Tool Comparisons section). Total pages: 979. ToolBox Image has 13 live tools, batch cap at 200 files (concurrency 4), HEIC converter is single-file only.
i18n system (current session): Full multi-language support for 13 languages (EN, ES, FR, DE, IT, PT, RU, ZH, JA, KO, AR, HI, TR). Homepage content extracted into src/components/home/HomeContent.astro shared component used by both index.astro and [lang].astro. Catch-all route [lang]/[...slug].astro serves translated pages for all tools, blog, FAQ, about, contact, legal pages (678 total pages). Hindi translations rewritten to use conversational/natural Hindi. Language-prefixed links throughout (e.g., /hi/compressor/ instead of /compressor/).
Page count: 992 pages (across 13 languages)
Live tools (14): Image Compressor, Bulk Compressor, Compress JPEG/PNG/WebP/AVIF/GIF/for-Web/for-Ecommerce, 100KB/Email/Discord/WhatsApp/Instagram targets, Rotator, Format Converter, Image Resizer, Cropper, Image Sharpen
Image Sharpen tool (new): Canvas convolution sharpen with 0-100% strength slider, 150ms debounce, before/after preview, download as PNG. Added to ToolSeoContent.astro with full SEO content (how-to, FAQs, related tools). Blog post created: "How to Sharpen Images Online Free — Fix Blurry Photos in Your Browser" (slug: how-to-sharpen-images-online). Registered in types, tools.ts, catch-all route, tools/[tool].astro, HomeContent.astro, translations (13 languages).
Tool i18n pattern: Tool components are extracted into src/components/tools/ (e.g., CompressorTool.astro, RotatorTool.astro) so they can be reused in both English pages and language routes. When adding a new live tool:
1. Create a {ToolName}Tool.astro component in src/components/tools/ with the tool's HTML/JS (no Layout/AppShell wrapper)
2. Reference it in src/pages/tools/[tool].astro if appropriate
3. Add it to isLiveTool checks in src/pages/[lang]/[...slug].astro and import + render the component
4. Add the slug to getStaticPaths() in the catch-all route

Documentation

Full documentation: https://docs.astro.build

Consult these guides before working on related tasks:

i18n Development Rules

Same UI across all languages: Every page (blog, tools, about, FAQ, etc.) must render the exact same UI in all 13 languages. Never use stripped-down inline HTML for non-English versions — all pages must use shared components. Use src/components/blog/BlogIndexPage.astro and src/components/blog/BlogPostPage.astro for blog pages in all languages.
Always pass lang prop: Every page-level and tool component must accept an optional lang prop (default 'en').
Use useTranslations(lang): In Astro frontmatter, always call const _ = useTranslations(lang) and use _(key) for all user-facing strings.
JS runtime strings: For strings displayed by client-side <script> code, use data-i18n="key.name" attributes on HTML elements and a runtime lookup function:
```
const i18n = (key) => document.querySelector(`[data-i18n="${key}"]`)?.textContent ?? key;
```
New translation keys: When adding new user-facing text, add 'key.name': 'English value' to the en section of src/i18n/translations.ts and provide translations for all 13 languages before shipping.
13 languages: ES, FR, DE, IT, PT, RU, ZH, JA, KO, AR, HI, TR + EN. Always include ALL languages when adding new keys.
Tool status badges: Use _('tools.live'), _('tools.soon'), _('nav.planned') rather than hardcoded strings.
Catch-all route: [lang]/[...slug].astro passes lang={langCode} to live tool components.
Language switcher: Uses translatePath() which already handles lang-prefixed URLs correctly — never construct lang URLs manually.
Nav/Footer links: Use langPath(lang, href) for all internal links to preserve the current language.
SEO: Pass lang to Layout and use localeFromLang() for og:locale and Schema.org inLanguage.

Tool Development & Research Rules

1. Research Before Building

Research high-quality open-source implementations on GitHub (multiple repos, not one).
Study architecture, algorithms, browser APIs, performance, UX, error handling, accessibility, edge cases, memory management, file handling, security.
Learn from the best implementations, then build an original implementation. Do not copy code.
Reuse existing shared components.

2. Browser First — Zero Budget

Prefer browser-native processing. No paid APIs, no paid services, no subscriptions.
Every tool must work 100% free, client-side, with no server costs.
Only use third-party libraries if they're MIT/Apache/BSD licensed and run entirely in the browser.
Process files locally. Keep images on device. Never upload.
If a tool requires AI/ML, use browser-compatible ONNX/TF.js models — but only if the model is small enough for practical web use.
Tools that require paid APIs (remove.bg, Cloudinary, etc.) are automatically deprioritized regardless of search demand.

3. Reusable Architecture

Every new tool must reuse shared layouts, components, UI, upload/download systems, and localization. Never duplicate existing code.

3b. New Tool Checklist (Mandatory — Do Not Skip)

When adding a new live tool component (e.g., ImageRedactorTool.astro), apply ALL of these or the tool will not work:

1. Upload fix — Add hidden file input + click interceptor Every tool component needs a hidden <input type="file"> and document-level capture-phase click/keydown interceptors that stop the ToolUpload component's own click handler and redirect to the hidden input. Copy this exact pattern from CircleCropTool.astro lines 23, 450-471:

<ToolUpload {tool} {lang} />
<input type="file" accept="image/*" data-TOOL-file-input hidden aria-hidden="true" />

// In script: query the hidden input
const toolFileInput = document.querySelector<HTMLInputElement>('[data-TOOL-file-input]');

// Add change handler
if (toolFileInput) {
  toolFileInput.addEventListener('change', () => {
    const files = Array.from(toolFileInput.files || []);
    toolFileInput.value = '';
    if (files.length) onFilesReceived(files);
  });
}

// Click interceptor (capture phase stops ToolUpload's own handler)
document.addEventListener('click', (e) => {
  const zone = (e.target as HTMLElement).closest('[data-tool-upload]');
  if (!zone) return;
  if ((e.target as HTMLElement).closest('[data-action="paste"]')) return;
  e.stopImmediatePropagation();
  e.preventDefault();
  requestAnimationFrame(() => toolFileInput?.click());
}, { capture: true });

// Keyboard interceptor
document.addEventListener('keydown', (e) => {
  if (e.key !== 'Enter' && e.key !== ' ') return;
  const zone = (e.target as HTMLElement).closest('[data-tool-upload]');
  if (!zone) return;
  e.stopImmediatePropagation();
  e.preventDefault();
  requestAnimationFrame(() => toolFileInput?.click());
}, { capture: true });

2. HomeContent.astro mappings — Three objects must have an entry In src/components/home/HomeContent.astro, the tool must appear in ALL three mapping objects (lines ~62-80):

toolCatFromId: 'tool-id': 'Edit' (or 'Convert' / 'Resize' / 'Analyze')
toolKeyFromId: 'tool-id': 'tools.toolCamelCase'
toolDescFromId: 'tool-id': 'tools.toolCamelCaseDesc'

3. Translations — Add to ALL 13 language sections The tools.toolCamelCase and tools.toolCamelCaseDesc translation keys must exist in EVERY language section of src/i18n/translations.ts, not just English. Insert them right after tools.passportDesc in each section.

4. Routing pages — Three files to update

src/types/index.ts — Add tool ID to ToolId union
src/lib/tools.ts — Add ToolConfig entry
src/pages/[lang]/[...slug].astro — Import component, add to isLiveTool check, add to toolKeyFromId/toolDescFromId maps, add to getStaticPaths(), add ogImageMap, add to rendering ternary
src/pages/tools/[tool].astro — Import and add to rendering ternary

5. e2e tests — Three files

e2e/helpers.ts — Add to LIVE_TOOL_PAGES and classifyUrl
e2e/tools.spec.ts — Add test suite with upload, mode buttons, interaction, download
e2e/translations.spec.ts — Add translation checks for 3-4 languages

4. SEO Requirements (Mandatory)

Every new tool must include complete SEO before it is considered finished.

Before building the SEO:

Research keywords using Ahrefs Free Keyword Generator (or equivalent free tool).
Identify: primary keyword, secondary keywords, long-tail keywords, question keywords, related searches, low-competition keywords, high-traffic keywords.

Use this research to build a complete SEO ecosystem.

Tool page:

SEO-friendly URL, title tag, meta description, H1, H2/H3 headings
600–1000+ words of unique content
Internal links, related tools
FAQ + JSON-LD FAQ Schema
Breadcrumb Schema + SoftwareApplication Schema (when applicable)
Open Graph tags + Twitter Cards

Supporting pages: Whenever keyword research shows meaningful search demand, create supporting landing pages (format-specific, size-specific, use-case, industry, comparison pages). Each must have unique content and link to the main tool page.

Blog: Whenever keyword research identifies informational search intent, create SEO blog posts targeting one primary keyword each. Link to the relevant tool. Include FAQ and structured data.

FAQ: Automatically expand the website FAQ whenever new high-volume questions are discovered. Answer clearly, target search intent, add to relevant tool pages, include in JSON-LD FAQ Schema.

Internal linking: Whenever new pages are created: link related tools together, link blog posts to tools, link tools to blogs, link FAQs where appropriate.

Definition of done: A new tool is not complete until: the tool works correctly, supporting landing pages are created (when justified), SEO content is complete, relevant blog posts are created, FAQs are updated, structured data is added, internal linking is complete.

5. Content

Every tool page needs: overview, features, benefits, step-by-step guide, supported formats, best practices, common use cases, SEO FAQ, CTA, related tools links.

6. Quality Assurance

Before marking complete verify: upload, drag & drop, multi-upload, folder upload, clipboard paste, processing, preview, download, output validity, file sizes, statistics, responsive layout, dark mode, accessibility, all languages, SEO metadata, structured data.

Bible Directory

This project follows the ToolboxImage Engineering Bible.

When choosing which tool to build next, consult bible/TOOL_PRIORITY.md — it ranks tools by search demand, feasibility, and brand fit.

Before Every Task

Read the Bible README — understand the project's engineering principles.
Read only the handbook documents relevant to the current task — don't waste time on unrelated ones.
Never upload, commit, publish, or expose any handbook file. The Bible is confidential local documentation and is never part of the repository.
Before writing code, inspect the existing project — reuse components whenever possible. Never duplicate existing code.
Before implementing, explain your plan — outline what you'll build and how.

After Implementing

After implementing any feature, do NOT report "Done" immediately.

Instead:

Read the relevant handbook documents.
Identify the tool category and create a tool-specific validation plan.
Test the feature like a real user would.
Verify that previews match exported results.
Verify calculations and transformations.
Test edge cases, mobile/desktop layouts, and major browsers.
Run Playwright tests.
Fix every issue found before reporting completion.

Mandatory Validation

Passing compilation is NOT sufficient.

Passing Playwright is NOT sufficient.

Passing unit tests is NOT sufficient.

Every feature must be validated from the perspective of a real user.

AI agents must identify the tool category and perform tool-specific validation before considering any task complete.

Example — Image Resizer:

Verify preview accuracy.
Verify exported image dimensions.
Verify aspect ratio preservation.
Verify mobile layout.
Verify browser compatibility.
Verify accessibility.

Example — Image Compressor:

Verify file size reduction.
Verify visual quality.
Verify metadata handling.
Verify target-size compression.
Verify preview matches download.
Verify downloads.

Example — Crop Tool:

Verify crop preview accuracy.
Verify exported crop matches preview.
Verify preset aspect ratios.
Verify freeform crop.
Verify touch/drag support.

Each tool has different validation requirements.

Think about how users will actually use the tool and test those scenarios.

Never assume the preview is correct.

Never assume the exported file is correct.

Never assume calculations are correct.

Verify them.

Bugs Become Rules

Every bug discovered after implementation must become a permanent handbook rule if it exposes a missing validation step.

If you discover missing handbook guidance, recommend improvements to the handbook itself.

Definition of Done

A feature is complete only when:

Engineering standards pass — code follows project conventions, builds cleanly.
UX validation passes — workflows are intuitive, no confusing states.
Tool-specific validation passes — the tool works correctly for all intended use cases.
Accessibility passes — keyboard navigation, screen readers, color contrast.
Performance passes — processing is fast, no jank, memory usage is reasonable.
Security passes — no exposed data, no injection vectors.
SEO passes — metadata, structured data, internal links, content.

The objective is not to produce code.

The objective is to produce a reliable product that users trust.

Testing with Playwright

The project uses Playwright for end-to-end testing. Tests are in e2e/.

Commands

npm run test           # Run all tests
npm run test:ui        # Run with interactive UI mode
npm run test:headed    # Run with visible browser (debugging)

Workflow

First build: npm run build (tests read sitemap from dist/)
Then preview: npx astro preview (serves from dist/ on port 4321)
Then test: npx playwright test

Or use the convenience script: npm run test:full (builds, waits, then tests).

What tests exist

pages.spec.ts — Loads every page from the sitemap (678 pages across 13 languages), checks for 200 status and zero console errors. Runs on Chromium only by default.
language.spec.ts — Verifies language switcher works, translated content renders on each language's pages, no English fallback leaks. Runs on all browser projects.
tools.spec.ts — Tests Compressor, Rotator, Converter, and Resizer upload flows: zone visibility, file acceptance, preview rendering, no console errors. Runs on all browser projects.
translations.spec.ts — Asserts specific translated strings appear on the correct language pages and English strings don't appear where they shouldn't. Runs on all browser projects.

Browser Matrix

Project	Browser	Viewport	pages.spec.ts
chromium	Chrome/Edge/Brave	Desktop 1280×720	✅ full
firefox	Firefox	Desktop 1280×720	❌ skipped
webkit	Safari	Desktop 1280×720	❌ skipped
mobile-chrome	Chrome (Pixel 5)	Mobile 393×851	❌ skipped
mobile-safari	Safari (iPhone 13)	Mobile 390×844	❌ skipped
tablet	Safari (iPad Pro 11)	Tablet 834×1194	❌ skipped

Non-Chromium projects run tools, translations, and language tests to catch cross-browser JS/CSS bugs where they actually matter.

Before Deploy

Run the full matrix manually to catch any page-specific issues in Firefox/WebKit:

npx playwright test --project=chromium --project=firefox --project=webkit

This tests all 678 pages in all three engine families. Takes ~20min.

Adding new tests

When adding a new tool or page:

Add the slug to e2e/helpers.ts LIVE_TOOL_PAGES array if it's a live tool
Add upload + process + download test in e2e/tools.spec.ts
Add translation checks in e2e/translations.spec.ts
Run npm run test:full to verify everything passes

Rules

Always build before running tests (tests parse the sitemap from dist/)
Tests are fully parallel by default (Chromium-only: ~700 tests in ~35s; six projects: ~4200 tests in ~5min)
Failed tests capture screenshots and traces in test-results/
Do not skip console-error checks — a page with JS errors is a broken page

Monthly Tasks (Repeating)

These need to be done every ~30 days. Remind the user at the start of each session:

Directory Re-Submissions

Submitx.com — Re-submit to 376 search engines/directories (URL: https://toolboximage.com, category: Internet & Web Services, description: "Privacy-first browser-based image tools. Compress, resize, convert, edit")
Entireweb.com — Re-submit manually in browser to avoid spam filter (email: toolboximageofficial@gmail.com)
FreeWebSubmission.com — Re-submit (email: toolboximageofficial@gmail.com)

Directory Submissions (Done)

SaaSHub — Submitted ✅
DevHunt — Submitted ✅
Submitx.com — 376 directories ✅
FreeWebSubmission — Verify email ✅
Active Search Results — 37 pages submitted ✅

IndexNow

IndexNow key: 5b8eb44c08f070e11b6defb645c515df (file at public/5b8eb44c08f070e11b6defb645c515df.txt) Pings Bing + Yandex + Seznam about URL changes. Run after deploying new pages:

curl -X POST "https://www.bing.com/indexnow" \
  -H "Content-Type: application/json" \
  -d '{"host":"toolboximage.com","key":"5b8eb44c08f070e11b6defb645c515df","urlList":["https://toolboximage.com/new-page"]}'

dev.to

API key: fTMQq5fCfyjVzDJ8pwU8MHX9
30 posts/day limit. Post more blog content there.
Profile: https://dev.to/arhan_ahmad_a67ef7bd2b992

Gmail SMTP (for outreach & signups)

Email: toolboximageofficial@gmail.com
App Password: bngx wkla ltny jqpx
SMTP: smtp.gmail.com:587 (TLS)

Account-Age-Gated (only if HN/Reddit/PH accounts are old enough)

Hacker News Show HN — Post the draft (see session history)
AlternativeTo — Re-submit listing (they decline "simple collections of tools" — position as privacy-first comprehensive toolkit)
Product Hunt — Launch post

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

Development

MANDATORY: New Tool Workflow

Phase 1: Research (MANDATORY — do this first)

Phase 2: SEO Ecosystem (MANDATORY — before or alongside tool build)

Phase 3: Implementation

Phase 4: Validation (MANDATORY — never skip)

Rules

Session Memory

Documentation

i18n Development Rules

Tool Development & Research Rules

1. Research Before Building

2. Browser First — Zero Budget

3. Reusable Architecture

3b. New Tool Checklist (Mandatory — Do Not Skip)

4. SEO Requirements (Mandatory)

5. Content

6. Quality Assurance

Bible Directory

Before Every Task

After Implementing

Mandatory Validation

Bugs Become Rules

Definition of Done

Testing with Playwright

Commands

Workflow

What tests exist

Browser Matrix

Before Deploy

Adding new tests

Rules

Monthly Tasks (Repeating)

Directory Re-Submissions

Directory Submissions (Done)

IndexNow

dev.to

Gmail SMTP (for outreach & signups)

Account-Age-Gated (only if HN/Reddit/PH accounts are old enough)