Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
93 lines (70 loc) · 3.66 KB

CONTRIBUTING.md

File metadata and controls

93 lines (70 loc) · 3.66 KB
Raw

Contributing to Avemo Dev

Thanks for your interest in improving Avemo Dev! This document covers how to get a development build running, the project layout, and the conventions used here.

Prerequisites

  • Node.js 20 or newer
  • pnpm 9 or newer (corepack enable will provide it)
  • A Chromium-based browser (Chrome, Edge, Brave, Arc, …) for loading the extension

Getting started

pnpm install        # install dependencies
pnpm dev            # start Vite in watch mode with HMR

Then load the extension:

  1. Open chrome://extensions.
  2. Enable Developer mode (top-right).
  3. Click Load unpacked and select the generated dist/ folder.

CRXJS reloads the extension as you edit source files. For a production build, run pnpm build and load the same dist/ folder.

Useful scripts

Command What it does
pnpm dev Vite dev server + HMR for the extension
pnpm build Type-check (vue-tsc) then produce the unpacked extension in dist/
pnpm type-check Type-check only, no build
pnpm test Run the Vitest unit suite once
pnpm test:watch Vitest in watch mode
pnpm e2e:install One-time: download the Chromium build Playwright drives
pnpm e2e Run the Playwright end-to-end suite against dist/ (build first)

Project structure

src/
├─ background/        # MV3 service worker (toggles the panel on command/icon click)
├─ content/           # content script: mounts the Shadow-DOM host
│  ├─ overlay-root.ts     # creates the shadow root, injects tokens + Inter
│  ├─ overlay-manager.ts  # watches the Pinia store, drives the plain-JS renderers
│  └─ overlays/           # column/baseline/row grids, outlines, inspector, tools
├─ ui/                # Vue panel + section/component tree
├─ stores/            # Pinia store — the single config contract the UI drives
├─ lib/               # framework-agnostic helpers (color, grid math, storage, …)
└─ styles/            # panel.css — the avemo OKLCH token system (injected inline)

Key architectural notes:

  • Shadow DOM isolation. The panel and every overlay mount inside a shadow root so page CSS never leaks in, and the extension's styles never affect the page.
  • Store-driven overlays. src/stores/settings.ts is the source of truth; overlay-manager.ts watches it and calls the plain-JS renderers in src/content/overlays/. Overlays don't import Vue.
  • Per-domain persistence. Config is saved per host in chrome.storage.local and auto-restored on the next visit.

Coding conventions

  • TypeScript strict mode throughout — no any escape hatches without a reason.
  • Match the style, naming, and comment density of the surrounding code.
  • Keep overlay renderers framework-agnostic (no Vue imports under content/overlays/).
  • Prefer small, focused modules in src/lib/ for reusable logic and add a unit test.

Before opening a pull request

  1. pnpm type-check passes.
  2. pnpm test passes (add/adjust tests for behavior changes).
  3. pnpm build succeeds.
  4. If you touched panel/overlay behavior, sanity-check it in a real browser and, where practical, extend the Playwright suite in e2e/.

Commit messages

This project uses Conventional Commits:

feat(inspector): add contrast ratio readout
fix(panel): restore focus after closing a color field
docs: clarify E2E setup

Reporting bugs & requesting features

Use the issue templates. For anything security-related, please read SECURITY.md first.