# AGENTS.md

## Scope
- This file guides AI coding agents working in `absol-acomp`.
- Related docs live in sibling repo `../absol-doc`; component docs are generated from runtime registrations.

## Big Picture Architecture
- Core entry is `AComp.js`: exports `AComp` with `core`, `_`, `$`, `$$`, and shared helpers.
- `ACore.js` creates a singleton `Dom` instance from `absol/src/HTML5/Dom` and exposes DOM DSL helpers.
- `dev.js` is the webpack entry and a side-effect hub: imports many components/utilities, attaches them to global `absol`, and sets `window.AComp`.
- Component registration is centralized in `js/dom/install.js` via `core.install()` calls.
- Build output is `dist/absol-acomp.js` (configured in `webpack.config.js`).

## Component + CSS Conventions
- Typical component file pattern (`js/CheckBox.js`, `js/AutoCompleteInput.js`):
  - top-level CSS side-effect import, e.g. `import '../css/checkbox.css'`
  - class/static object with `render()` and `tag`
  - tag is lowercase (explicit string or `Name.toLowerCase()`)
- CSS files are in `css/` with mostly kebab/lowercase names and map closely to component names.
- Prefer existing DOM helpers from `ACore` (`_`, `$`, `$$`) over ad-hoc DOM manipulation where local style matches.

## Build, Dev, and Debug Workflows
- Install/build commands (from `package.json`):
  - `npm run dev` -> `webpack serve --config webpack.config.js`
  - `npm run dist` -> `webpack --config webpack.config.js --progress --profile --mode production`
- On macOS in this repo, use wrapper scripts when needed:
  - `mac_start_dev.sh`
  - `mac_start_dist.sh`
- Those scripts export `NODE_OPTIONS=--openssl-legacy-provider`; keep this in mind if webpack fails on newer Node/OpenSSL.
- Manual validation is demo-first: use files in `demo/` and browser-run scripts in `test/` (no formal unit-test framework configured).

## Integration Points
- `dev.js` loads external assets at runtime (Material Design Icons + Google Fonts); avoid breaking these side effects unless intentionally refactoring bootstrap.
- `absol-doc/content/table_of_content.js` inspects `absol.AComp.core.creator` and `render()` presence to generate component doc links.
- Changes to component tags/registration can silently affect docs generation in `absol-doc`.

## Agent Working Rules for This Repo
- Prefer minimal, local edits: this codebase relies on side-effect imports and global namespace wiring.
- When adding a new component:
  - add `js/<Component>.js` with `tag` + `render()`
  - add/import matching CSS in `css/`
  - register/import through existing install/entry flow (`js/dom/install.js` and/or `dev.js` pattern)
  - sanity-check via a `demo/*.html` page or equivalent manual browser verification.
- Preserve existing global exports in `dev.js` unless the task explicitly asks to change public API behavior.