client/core – AGENTS

Shared services, utilities, and math primitives that power both vector and matrix modes. These modules must stay framework-free, DOM-light, and reusable across future Bespoke apps.

Loading Order + Globals

• Files are loaded (via <script> tags) in deterministic order before linear-algebra.js. Do not introduce circular dependencies.
• Each module attaches itself to window.* or defines a global class. Keep those names stable; the rest of the app references them directly.

Modules

• status.js (window.StatusService)\
  • Sole gateway for status text. Only expose the allowed verbatim strings.
  • Gracefully handle missing #status (warn once, no throws).
• config.js (window.ConfigService)\
  • Fetches ./config.json, merges with DEFAULT_CONFIG, caches the result, and emits StatusService.setLoading() / setReady() / setLoadFailed().
  • Returns mutable objects internally but callers must treat them as frozen because linear-algebra.js wraps them in Object.freeze.
  • Expose clearCache() for manual reloads/tests.
• operation-schemas.js (window.OperationSchemas)\
  • Source of truth for allowed operation group keys. Always run validateOperationGroups(mode, groups) before wiring UI so that new config flags cannot break the app.
• mode-manager.js (window.ModeManager)\
  • Owns .mode-content visibility and the shared CoordinateSystem.
  • renderModeButtons(enabledModes) + hideDisabledModeContainers(enabledModes) drive what the user sees based on config.json.enabledModes.
  • onModeChange(callback) notifies helpers like the HelpService when the active mode flips.
  • registerMode(name, factory) stores factories that must return instances exposing destroy().
  • setMode(name) tears down the current instance (wrapped in try/catch) and applies .active/.hidden classes. Never mutate the DOM for mode toggles elsewhere.
• help.js (window.HelpService)\
  • Lazily fetches help-content-template.html once, initializes HelpModal, and supports appendHelpContent(). Always call initializeHelpModal before appending extra sections.
• theme-service.js (window.CanvasThemeService)\
  • Initialized exactly once with STYLE_CONSTANTS. Provides getColors(), subscribe(callback) (returns unsubscribe fn), and cleans up media-query listeners via destroy(). Subscribers must unsubscribe inside their destroy() implementation.
• color-utils.js (window.ColorUtils)\
  • Reads CSS custom properties under .bespoke (which are mapped from Design System tokens via bespoke.css). Use this to keep colors responsive to theme changes instead of hard-coding hex values.
• animator.js (class Animator)\
  • Pure animation helpers (ease curves, animate, lerp, lerpVector). Returns a control object with cancel(). Modes must cancel outstanding animations inside destroy().
• coordinate-system.js (class CoordinateSystem)\
  • Handles canvas sizing, grid/axis drawing, coordinate transforms, hover hit-testing helpers, and translated vector rendering. Register resize callbacks via setResizeCallback.
• vector.js (class Vector)\
  • Immutable 2D vector with math helpers (add, subtract, scale, dot, projections, reflections, normalization, perpendicular, angle utilities). Vector.defaultResultColor should be overridden through Vector.setDefaultResultColor so that result vectors track the theme.
• results-panel.js (class ResultsPanel)\
  • Lightweight wrapper that writes formula/result markup into a container. Use .show(...lines) and .clear() rather than manipulating DOM manually.
• format-utils.js (window.FormatUtils)\
  • HTML formatting helpers for matrices (formatMatrixAsGrid) and vectors (formatVector). Use them whenever results need inline math formatting.

Cross-Cutting Rules

• Keep modules idempotent: calling init/load functions multiple times should be safe (e.g., CanvasThemeService.init ignores missing constants, HelpService warns on double init).
• Every async function (ConfigService.loadConfig, HelpService fetches) must console.error on failure and fall back to usable defaults (e.g., placeholder help copy).
• Never mutate DOM outside the module’s intended surface (e.g., ResultsPanel can write into its container, but Vector must remain math-only).
• All exports should be documented here whenever new files are added. If you add another shared service, update this AGENTS file before landing the code.