Auric Artisan Browser Extension Developer Reference

The extension is one source tree that builds four apps for two browser engines. Only the suite, named Auric Artisan, is published; color, a11y and devtools set published: false and stay as internal build targets. There is no bundler and no transpiler: the source is the shipped JavaScript, and the build copies files, writes manifests and checks the result.

At run time there are three pieces. The background worker owns the browser's own right-click items, keyboard commands, the badge and privileged relays. One extension page, popup.html, holds every tool and is shown as the toolbar popup, the Chromium side panel, the Firefox sidebar or a separate window. The content script owns everything drawn on a web page. Nothing depends on a server; the only outbound traffic is a page the user chooses to open.

The version is 1.0.2 for every app. Section 15 notes which parts of the current source the changelog still lists as Unreleased.

• extension/version.json: the one version every manifest reads.
• extension/apps/<id>/app.config.mjs: id, name, shortName, brand, geckoId, description (132 characters at most), tabs, defaultTab, features.a11yEngine, published and commands.
• extension/build/build.mjs: the CLI that copies, composes, localizes, validates and zips. extension/build/compose.mjs: buildManifest(), manifestMessages(), buildMessages() and filterPopup().
• extension/shared/fonts/: Manrope and Fraunces. extension/store/: listing copy, artwork and permission justifications. extension/docs/: the extension's own documentation and decision records.
• extension/dist/<target>/<app>/: build output, git-ignored, plus auric-<app>-<target>-<version>.zip when zipping.

The build copies flat: packages/popup, ui and runtime land at the bundle root; core/, i18n/, fonts/ and the brand's icons/ land in folders of those names; a11y/ and data/ are added only when features.a11yEngine is set (the suite and the a11y app).

There is no manifest in the source tree. buildManifest(app, { version, target }) in compose.mjs writes extension/dist/<target>/<app>/manifest.json from MANIFEST_BASE and the app config. The manifest's description, action title, sidebar title and command descriptions are __MSG_…__ placeholders resolved from generated _locales/en and _locales/hi, with default_locale: "en".

The focused apps carry their own commands: the a11y app binds run-a11y-audit to Alt+Shift+R, and the devtools app binds inspect-element to Alt+Shift+I and adds extract-tokens without a key. The build fails on a description over 132 characters (the source or any translation), a key claimed twice, a Firefox manifest without data_collection_permissions, a referenced file missing from the bundle, an absolute path in popup.html, a declared tab with no panel, or a default tab that is not declared. Permission changes are user-visible in the stores and belong in the changelog.

• Surfaces. popup.js sets html[data-surface] before first paint: panel when the URL has ?surface=panel, otherwise popup. background.js points the side panel (sidePanel.setOptions) or sidebar (sidebarAction.setPanel) at popup.html?surface=panel, and the window button opens the same URL with windows.create as a 620 × 700 popup window.
• Tab registry. A hidden nav.aa-tabs holds one button.aa-tab[data-tab] per tool, and each tool is a <section class="aa-panel" data-panel="…">. filterPopup() removes the buttons of tools an app does not ship, marks their panels data-app-excluded="true" (the markup stays because popup.js binds listeners to it at load), activates the default tab and writes data-app, data-tabs and data-default-tab on <body>. app-scope.js stops a restored tab from showing an excluded tool. Keep class before data-panel on each section; the filter's pattern depends on that order.
• Spaces. SPACES lists Home plus four spaces; TOOL_META gives each tool its label and icon. A space whose tools are all excluded from a build is hidden.
• Side panel layout. adoptPanelLayout() moves the theme and Settings buttons into the rail and opens a port named aa-panel to the background, posting its window id.
• Home. renderDashboard() draws HOME_ACTIONS.popup (Pick a colour, Contrast, Inspect, Audit this page) as a launcher in the popup, and HOME_ACTIONS.panel (Pick, Inspect, Audit, Vision) inside the tab card on the panel surface, with the colour of the day, the page's colors, recent colors, Continue, pinned tools and site links.
• Scripts. i18n/boot.js runs in the head; then the classic scripts popup.js, app-scope.js and combo.js, then the modules color-picker.js and finding-bridge.js, which publish window.AAColorPicker and window.AAFinding for the classic code.
• Styles. theme.css is the only token deck (--aa-*, per theme on html[data-aa-theme]); shell.css covers the chrome, tools.css the tool panels, combo.css the dropdown and color-picker.css the picker.

Search is backed by COMMANDS in popup.js: 29 entries of type panel, launch (an auricartisan.com route) or click (a header button). commandIsAvailable() hides panel commands whose tab the build removed, and onPage: true flags tools that need a web page. SETTINGS_INDEX adds 15 settings, each with settingTab and settingControl so a result opens Settings at the control. Every typed word must match the title, description, group or keywords, in English or translated; an exact title ranks first. Add a COMMANDS entry, a SPACES slot and a TOOL_META label with every new tool.

Settings live in one object under aa_settings, initialized from DEFAULT_SETTINGS. On load, stored values are merged over the defaults and pickers is merged key by key, so a new picker type starts on. content.js keeps its own copy of the defaults it needs.

Imported settings pass through sanitizeImportedSettings(): enums must be known values, booleans must be booleans, accentColor must be a 6-digit hex, only known picker keys survive, and host lists are cleaned, de-duplicated and capped at 100. A new setting needs a default, a control, an importer rule and a SETTINGS_INDEX entry.

Nothing is synced and nothing injected into a website reads or writes that site's storage. Audit results live only in popup memory. a11y/store.js defines an IndexedDB database (auric-a11y) for scan history and ships in engine builds, but no runtime code imports it, so no database is created. Backups (kind: "aa-backup", schema: 1) carry settings, history, library colors, palettes and snippets. Prefer additive schema changes and update the importer with every shape change.

background.js normalizes browser and chrome, and keeps its logic small and event-driven; page analysis runs in the content script.

• runtime.onInstalled opens https://auricartisan.com/?utm_source=extension&utm_medium=install on first install, then builds the browser menu, refreshes the badge and flags the panel surface. onStartup repeats the last three.
• The MENU items aa-inspect, aa-extract, aa-scan, four aa-vision-* simulations and aa-vision-clear are built on the page and action contexts while settings.context !== false, with Hindi titles from the bundled dictionary when lang is hi.
• sendContentMessage(tabId, message) tries tabs.sendMessage, then injects overlay.css and content.js with scripting and retries once, which covers tabs opened before the install.
• queuePopupAction(panel, action) writes aa_pending_command and calls action.openPopup(); the popup opens that panel and clicks the button whose id is action.
• Relays for the in-page menu: aa-perms, aa-download, aa-view-source, aa-open-window, aa-new-tab, aa-reload-bypass, aa-capture, aa-tab (reopen, duplicate, pin-toggle, mute-toggle, close) and aa-zoom (0.25–5). URLs pass safeUrl(), which allows only http:, https:, data: and blob:.
• Side panel tracking: panel pages hold an aa-panel port and post their window id; aa-panel-open answers whether the sender's window has one, and aa-open-panel opens the panel (or Firefox sidebar) inside the click's user gesture and queues the requested tool.
• aa-set-context builds or clears the browser menu; storage.onChanged on aa_settings rebuilds it too.
• refreshBadge() shows the Library color count on #d3af37, as 99+ above 99.

content.js runs in the isolated world, guarded by window.__auricArtisanLoaded so a second injection does nothing. It merges aa_settings over its defaults and, on load and on every change, applies the theme, the language, the color picker, the website pickers and the right-click menu in that order. Heavy modules are imported with import(runtime.getURL(…)) only when needed: color-picker.js for color-input replacement, pickers.js when customPickers is on and the host is not excluded, context-menu.js when customContextMenu is on, page-overlay.js for audit outlines, a11y/engine.js on aa-scan-page, and the i18n engine for Hindi.

Every aa-inspect-* message except aa-inspect-start must carry the session that started the inspector, or it is refused, so a stale popup cannot drive a page it no longer describes. The page reports back to the popup and panel with runtime.sendMessage: aa-audit-selected (index) when a pin is selected on the page, and aa-audit-closed when the overlay closes. The inspector asks the background aa-panel-open when it starts, and keeps a compact card on the page when the panel will show the details.

• Popup math. popup.js holds the conversions (sRGB and linear, HSL, HSV, CMYK, LAB, LCH, OKLAB, OKLCH, HWB), the CSS named-color map, WCAG ratios and APCA Lc. Keep these helpers deterministic and side-effect free; Contrast, Page palette, Harmony, Scale, Gradient, Mix and Convert all reuse them.
• The Picker. runtime/color-picker.js is the website's js/components/color-picker.js plus extension-only safety. Its FORMATS are HEX, RGB, HSL, HSV, HWB, CMYK, LAB, LCH, OKLAB, OKLCH, XYZ and P3, and its sections are Specs, Harmony, Scale, Contrast, Vision, Code, Page and Recent.
• WCAG rows. AA Body 4.5, AA Large 3, AAA Body 7, AAA Large 4.5, AA UI 3 and Gfx 3. APCA tiers are Lc 90, 75, 60, 45 and 30.
• Fixes. Targets are AA 4.5:1, AA Large 3:1, AAA 7:1, APCA Lc 60 and APCA Lc 75. huePreservingFixes() walks lightness out from the base color, keeping hue and saturation, and returns up to six passing candidates for text and for background.
• Contrast scan. runContrastScan() in content.js composites backgrounds up the tree. Text is large at 24 px or more, or 18.66 px bold; the threshold is 3:1 for large text and 4.5:1 otherwise. A pair within 1.5 of its threshold, or over a background image or text shadow, is a warning or manual review.
• Page palette. extractPaletteInPage() runs in the tab through scripting.executeScript: up to 6,000 elements, 12 color properties, custom properties weighted three times, the top 48 kept; clusterPalette() merges near-duplicates and the Dominant mode clusters to eight.
• Gradients. interpolatedStops() writes 13 stops for the OKLCH and HSL options; the OKLCH option mixes in OKLab.

When changing color math, check every tool that copies, exports or stores color data: one helper feeds previews, accessibility results and saved library payloads at the same time.

• Every rule skips the extension's own UI (OWN_UI_SELECTOR in a11y/dom-utils.js: the vision overlays, the color picker and [data-aa-overlay]). A rule that throws is recorded in ruleErrors and the audit carries on.
• The engine's limits are separate from scanDeep, which sets the fast contrast scan's limit and issueLimit (3,500 and 160, or 1,800 and 80). Called without options, the scan defaults to 2,600 elements and 120 issues; aa-scan-outline raises the issue default to 250.
• core/finding.js maps audit issues, contrast results and scan issues onto one finding shape (fromA11yIssue, fromContrastResult, fromScanIssue), which the Findings tool sorts by severity.
• runtime/page-overlay.js draws the outlines in its own shadow root through createOverlayHost(), built with createElement only. Pins are numbered in the list's order; the selected finding's card offers the nearest passing text color, Try the fix (an inline color preview put back on undo or close), Copy CSS and Next; the dock closes with Done or Escape. No class, attribute or style of the page is otherwise touched.
• a11y/store.js (IndexedDB scan history) and the analysis*.js helpers are shipped and tested but not imported by any runtime code yet.

• color-picker.js exports ColorPicker, createColorPicker, mountInlinePicker, initAllColorPickers, enableAutoColorPickers, disableAutoColorPickers, configureColorPickers, setColorPickerTheme, parseColor and colorMath. It has three shapes: a 296 px popover on color inputs, split in the popup's Picker, stacked in the side panel. An input with data-cp-skip is never replaced, and it persists only on extension pages, never on a visited site.
• pickers.js is an enhancer registry ({type, selector, match, create}) for select, date, month, number, range, time, week, datetime, file, multiselect, datalist, radio and checkbox. Values are written with setNativeValue() plus real input and change events; lists longer than SEARCH_THRESHOLD = 7 get a search field; one debounced MutationObserver tracks the page.
• ui/combo.js enhances the popup's own select[data-aa-combo] dropdowns with the same search rule.
• overlay-host.js: createOverlayHost({id, theme, accent}) returns {mount, place, setTheme, destroy}, a zero-size host on document.documentElement with an open shadow root and an all: initial reset. Hosts in use include #aa-pickers, #aa-color-pickers and #aa-context-menu.
• context-menu.js builds one scene per right-click (edit, colour, selection, image, media, link, page or element), keeps its quick bar and layout in aa_cm_prefs (default quick bar back, forward, reload, copy-url, copy-shot), offers Inspect in side panel outside Firefox, and stands down on Shift, a page that already handled the event (with cmStepAside), data-aa-no-ext-menu, data-native-context-menu, <meta name="auric-extension-menu" content="off">, [data-aa-own-menu] and auricartisan.com. It uses createElement only, so it works under Trusted Types.
• core/dom.js, core/events.js and core/utils.js are small shared helpers; core/finding.js is the finding model.

Injected UI follows fixed rules: floating UI lives in a shadow root; anything that must sit in the page is inline-styled; nothing touches the site's storage; the host page is never translated; the audit never audits the extension; and turning a feature off tears down all of its listeners, observers and replaced controls.

• Runtime engine. packages/i18n/i18n.js translates by text: a key is the whitespace-collapsed English of a segment, a text node or a translatable attribute, looked up in locales/hi.json and then in the patterns of locales/patterns.hi.json. Re-running over translated DOM matches nothing, which keeps its MutationObserver from looping.
• Boot. boot.js imports the engine and dictionary only when the language is not English; aa_settings.lang is the setting and the aa_lang localStorage mirror stops a Hindi popup from painting English first.
• Pages. In a content script the engine starts with no root; only surfaces registered through i18n/overlay.js are translated, never the host page. Values, format names and standard names are marked data-no-i18n.
• Browser strings. manifestMessages() and buildMessages() generate _locales/en and _locales/hi from the same hi.json, following the browser's own language. The background translates its eight menu titles with a flat lookup in the same dictionary.
• Workflow. npm run i18n:extension harvests strings and reports missing Hindi; add the translation to hi.json, or a pattern for strings built from live values.

The privacy model has no network requests of its own (no analytics, telemetry or remote code), no accounts, no writes to a website's storage, and page-changing features that are opt-in. Outbound navigation is limited to the welcome page opened once on install and pages the user chooses: auricartisan.com links, the palette's Open, and web search and Google Translate from the custom menu. The Firefox manifest declares data_collection_permissions: { required: ["none"] }; the policy is the extension privacy policy.

Security measures: allow-listed URL schemes for privileged relays, a translation gate that rejects scripts, styles, frames, forms, event handlers and javascript:, validated backups, a 512 KB cap on the inspector snapshot, reversible Live CSS, queued commands that expire after 30 seconds, session-bound inspector messages, and no inline script in extension pages.

npm run extension:build                          # every app, both targets
npm run extension:build -- --app suite --target chrome
npm run extension:build:zip                      # --zip --published: store zips for the suite
npm run test:extension:full                      # build, both suites, brutal a11y fixtures

Version and changelog. extension/version.json is the only place the version lives; bump it there. 1.0.2, dated 2026-09-23, is the latest release in extension/CHANGELOG.md. The source also contains work the changelog lists under Unreleased: the side panel as home base with its rail, the popup as a quick launcher, the audit drawn by runtime/page-overlay.js with numbered pins, a finding card and a page dock, the inspector handing its details to the side panel, the Inspect in side panel menu action, and the aa-panel port with aa-panel-open and aa-open-panel. A build from source therefore reports 1.0.2 but includes that work, while a store install can still show the earlier layout. At release, rename Unreleased to the new version and date and bump the version.

Before uploading, lint the Firefox zip with npx addons-linter; it must report no errors. Chrome, Edge and Opera take the Chromium zip, and Brave and Vivaldi install from the Chrome listing. Safari is not built here: run xcrun safari-web-extension-converter extension/dist/chrome/suite on macOS and build the generated Xcode project; Safari has no side panel or sidebar.

• Run npm run extension:build before any test; the suites load extension/dist/chrome/<app>/, and a stale build passes tests that test nothing.
• tests/a11y/build.test.js: manifests and filtered popups for 4 apps × 2 targets. tests/extension/background-commands.test.js: every declared command is routed.
• The popup audits itself with the bundled engine (score 97 or more, no critical or serious failures, in tests/a11y/extension.test.js), and axe-core must report no violations over every panel (popup-accessibility.test.js).
• The side panel must not scroll sideways from 280 px up (sidebar-responsive.test.js, studio-redesign.test.js); side-panel-redesign.test.js covers the rail, the launcher and the audit overlay.
• Adding a tool: three tests count 18 panels (popup-real-user.test.js, popup-accessibility.test.js, tests/a11y/extension.test.js).
• Manually, on the built package in Chrome and Firefox: the popup, side panel and window; Pick from page with the OS eyedropper; the three optional permission prompts, declined once and then accepted; every default shortcut; pickers staying native on auricartisan.com; the Firefox sidebar, a picker, the inspector and the right-click menu; and switching to हिन्दी and back.

For workflow-level instructions, see the Browser Extension User Guide.