Color Science Lab Developer Reference

• tool/color-science-lab/index.html: static page shell, SEO metadata, SoftwareApplication schema, BreadcrumbList schema, shared cursor, scroll layer, loader, eye-rest UI, app container, and module imports.
• js/tool/color-science-lab.js: main ES module. Defines registry constants, theories, white points, tool records, shell rendering, Compare, Analytics, floating panels, linked controls, color math, canvas renderers, export, and window.AAColorScienceLab. Its color-space catalog is imported from js/tool/color-science/space-engine.js.
• js/library/tool-bindings.js: universal library binding. The Color Science Lab section captures focused panels, thumbnails, preview colors, input maps, semantic state, and restores panels through the public API.
• css/color-science-lab.css: page and panel-specific visual layer for the lab. The HTML shell also loads shared tool CSS, analyzer CSS, vision deficiency CSS, unified styles, dark mode, and legal page styles.
• library/documentation/articles: source HTML for this reference and the companion user guide. These articles are included in generated RSS, sitemaps, cache manifest, search index, and documentation discovery data.

The tool page follows the Auric Artisan static tool pattern. It imports /js/unified.js for platform behavior and /js/tool/color-science-lab.js for the lab application. The module initializes after the DOM is ready, reads complexity preference, renders the catalog, and installs global workspace helpers. /js/tool/color-science-views.js adds a rail of five views (Workbench, Catalogue, Compare, Gamut audit, and Illuminants); the catalog is the Catalogue view, and the page opens on Workbench unless aa_csl_lab_view remembers another view.

• Domains: colorimetry, adaptation, spectral, appearance, perceptual, spaces, theory, and rendering.
• Special tabs: __all__, __favorites__, __compare__, __analytics__, and __open__.
• Storage keys: aa_csl_depth_mode, aa_csl_active_category, aa_csl_guide_dismissed, aa_csl_favorites, and aa_csl_recents.
• Registry arrays: WHITE_POINTS, COLOR_SPACES, COLOR_THEORIES, TOOL_MODELS, and TOOLS provide the public catalog data used by cards, filters, panels, Compare, Analytics, and exports.
• Public API: window.AAColorScienceLab exposes tool metadata, color-space metadata, theory metadata, white points, open(), panels, layout helpers, linkAll(), and restoreState().

The catalog is registry-driven. A tool record controls the card text, category, depth, default model, default color space, default theory, tag surface, and preview view.

• Depth mapping: platform complexity values map to lab depth values. Basic maps to Foundation, Advanced maps to Research, and Both shows the complete catalog.
• Search index: rendered search checks names, summaries, tags, domains, depth, default model, default color space, default theory, and, for space and theory tools, catalog text.
• Debounce: search updates are delayed by 120 ms to keep typing smooth.
• Favorites: favorite slugs are stored in localStorage and surfaced through the Favorites tab and Analytics stats.
• Recents: opening a card records a recent slug, capped by MAX_RECENTS.
• Keyboard: / focuses search, ? opens shortcuts, F opens Favorites, A opens Analytics, C opens Compare, R opens a random tool, T tiles panels, and 1-5 focuses visible panels.

• Compare: renderCompareView() lets users select up to eight tools and evaluates them against the shared COMPARE_PALETTE. Output includes transformed HEX values, Delta E 76, domain labels, depth labels, and Open buttons.
• Compare filters: Quick Start, Basic, Advanced, Filtered, and Clear actions operate on registry slugs rather than open panels, so Compare can run before any panel exists.
• Analytics: renderAnalyticsDashboard() provides Heat Map, Mind Map, Stats, and Catalog modes using the same registry arrays that drive the tool cards.
• Export JSON: Analytics JSON includes counts, tools, color spaces, theories, white points, and an export timestamp.
• Export CSV: Analytics CSV emits one row per tool, color space, and theory; tool rows carry category, depth, score, default model, color space, theory, tags, and summary.
• Risk: because these views read directly from registry records, incomplete or mismatched defaults can show up as empty labels, weak search results, or poor exported catalog metadata.

• Open path: openTool(item) takes a registry record (the public open(slug) looks it up), focuses an already-open panel of the same slug unless duplicating, and otherwise ensures the host exists, creates a panel, mounts the generic tool UI, focuses it, records recents, and emits aa-csl-panel-change.
• Cap: MAX_PANELS is five. When the cap is reached, the module closes the first unpinned panel. If all visible panels are pinned, another panel is not opened.
• Titlebar actions: panels support link or unlink, duplicate, pin, minimize, maximize, and close.
• Movement: drag, resize, focus, z-index, viewport clamping, cascade, stack, tile, split horizontal, and split vertical are managed inside the panel module.
• Dock: minimized panels move into a dock item and can be restored without losing their current controls.
• Control center: ensureControlCenter() creates the floating Color Control center with workspace layout commands, Sync all, Minimize, Restore, Export, Close all, and per-panel controls.
• Linked controls: linked panels synchronize controls marked with data-sync-key, including sample color, compare color, model, white points, strength, temperature, guide visibility, and adaptation preview.

Unlike smaller workspaces that mount one custom UI per slug, Color Science Lab uses one generic panel renderer. Tool records decide labels and defaults, while the mounted panel uses the active domain to choose preview math, metrics, notes, and canvas drawing.

• Mount: mountTool(panel) renders controls, tabs, canvases, chips, metrics, model path, diagram, audit notes, and custom dropdowns.
• Controls: sample color, compare color, model, color space or standard, theory or observer, source white, target white, strength, temperature, guides, and adaptation preview.
• Output tabs: Experiment, Metrics, Chart, Graph, Diagram, and Audit share the same panel state but render different explanations and canvases.
• State read: readState(panel) normalizes HEX values and returns model, space, theory, white points, strength, temperature, guide flag, and adaptation flag.
• Render: renderPanel(panel) updates labels, swatches, metrics, model path, notes, and the canvases, then keeps linked control state in sync.
• Duplicate safety: every generated element uses panel.prefix so two panels of the same slug can exist without duplicate IDs.

• Core conversions: helpers cover HEX, sRGB linearization, RGB to XYZ, XYZ to Lab, xy, Luv, Oklab, HSL, HSV, HWB, CMYK, Lab LCh, Delta E 76, CAT matrices, Kelvin RGB, and wavelength RGB.
• White points: the registry includes common A, B, C, D-series, DCI, E, and F illuminant references used by adaptation controls and white point atlas views.
• Color spaces: metadata covers sRGB, linear sRGB, scRGB, Display P3, DCI-P3, Adobe RGB, ProPhoto, Rec.2020, Rec.709, Rec.601, ACES, CIE RGB, component video spaces, cylindrical artist spaces, CIE spaces, perceptual spaces, print/process models, and named systems.
• Theories: theory metadata spans Newton, Goethe, Young-Helmholtz, Hering, Grassmann, Maxwell, Munsell, Ostwald, CIE 1931, MacAdam, Von Kries, Retinex, Fairchild, CIECAM02, CAM16, iCAM, IPT, Oklab, and related references.
• Domain preview: previewHexForView() dispatches into domain helpers such as appearance, perceptual, rendering, space, and theory preview functions.
• Canvas rendering: drawToolCanvas(), drawChartCanvas(), and drawGraphCanvas() prepare HiDPI canvases and route to domain-specific drawings.
• Risk: changing shared conversion helpers affects Compare output, metrics, panel canvases, exported thumbnails, library previews, and documentation examples at the same time.

• Workspace export: exportWorkspace() creates a PNG montage from open panel canvases and labels the output with panel names.
• Binding: attachTool() matches /tool/color-science-lab/ and declares tool id color-science-lab.
• Capture: captureColorScienceLabPanel() finds the focused panel, reads synced controls, captures input maps by id, key, and suffix, extracts swatch colors, and creates a compact JPEG thumbnail from the active or main canvas.
• Asset data: saved payloads include panel_slug, panel_prefix, raw inputs, settings, semantic inputs, control values, preview colors, and color_science_state.
• Restore bridge: window.AAColorScienceLab.restoreState(slug, state) closes an existing same-slug panel, opens a duplicate-capable panel, waits two animation frames, applies saved input values, and focuses the restored panel.
• Compatibility: when changing control IDs or data-sync-key values, update CSL_CONTROL_SUFFIXES and restore fallbacks so older saved assets remain useful.

1. Add or update a domain entry only if the existing eight domains do not describe the new experiment.
2. Add model choices to TOOL_MODELS when the panel needs new selectable model labels.
3. Add any required white point, color space, or theory metadata before referencing it from a tool record.
4. Add a complete TOOLS record with slug, name, category, depth, summary, tags, view, and any default model, default color space, and default theory.
5. If the new domain needs special preview behavior, extend previewHexForView() and the relevant metrics and notes helpers.
6. If the new domain needs new visuals, extend drawToolCanvas(), drawChartCanvas(), or drawGraphCanvas() with a focused drawing branch.
7. Keep controls tied to stable IDs and data-sync-key values so linked panels and saved library assets continue to work.
8. Update Compare and Analytics assumptions when a new record changes depth, category, or default model semantics.
9. Update js/library/tool-bindings.js if capture or restore needs additional semantic state.
10. Add or update user and developer documentation, then regenerate documentation JSON, RSS, sitemaps, PWA cache manifest, and search index.

• Catalog: verify category tabs, All, Favorites, Compare, Analytics, Open Panels, mode switch, search, guide dismissal, favorites, recents, and keyboard shortcuts.
• Panels: open five panels, duplicate a panel, exceed the cap, pin all panels, drag, resize, maximize, minimize, restore, close, and verify viewport clamping.
• Linked controls: link two panels and verify sample HEX, compare HEX, model, source white, target white, strength, temperature, guides, and adaptation preview sync both from native inputs and custom dropdowns.
• Views: test Compare with Quick Start, Basic, Advanced, Filtered, and Clear; test Analytics Heat Map, Mind Map, Stats, Catalog, JSON export, and CSV export.
• Math: smoke test RGB to XYZ to Lab, Oklab, LCh, Delta E, adaptation matrices, Kelvin color, wavelength color, and each domain preview path.
• Rendering: resize panels and inspect Experiment, Chart, and Graph canvases on standard and HiDPI displays.
• Library: save focused panels, save multiple visible panels, restore each saved asset, and confirm restored values are applied after the two-frame restore pass.
• Risk: this module is highly connected. Registry changes can affect catalog, search, Compare, Analytics, exports, library previews, and SEO docs. Color math changes can shift every panel output at once.