Hacking
=======

Build & check
-------------

Toolchain prerequisites: node 22+.

```
make setup      # npm install + activates the pre-commit hook
make check      # dprint verify, typecheck, unit tests -- what the pre-commit hook runs
make fmt        # apply dprint
make build      # emits dist/ for the publishable packages, and bundles the gallery
make check-e2e  # drives the gallery in a headless Chrome with trusted input; not part of check
make publish    # npm publish for the public packages
```

Run `make` alone for the full target list.


Layout
------

This is an npm workspace.  The root `package.json` is private and fans out to `packages/*`:

- `packages/yukey/` -- the kit.  Published.
  Components (`src/yk-*.ts`) and their mechanisms, the default theme, and the component gallery (`src/gallery/`, bundled to `static/gallery.js`).
  Unit tests live beside their subject as `src/*.test.ts`.
- `packages/yukey-testkit/` -- a dependency-free CDP client for driving a page with trusted input.  Published.
  Node-only; it exists so that apps built on yukey (and yukey's own e2e suite) can test real keyboard traversal, which synthetic DOM events can't do.
- `packages/e2e/` -- yukey's own end-to-end suite.  Private.
  Serves the gallery bundle, launches a headless Chrome, runs scenarios against the gallery entries.
- `docs/` -- the precepts (what yukey's design follows) and, as they appear, guides for composing with it.


Things worth knowing
--------------------

- The published packages ship `dist/` (`.js` + `.d.ts` + maps), not `.ts`.
  Lit's decorators require `experimentalDecorators` and `useDefineForClassFields: false`; compiling here means consumers don't have to match those flags.
  Consequence: anything consuming yukey via a `file:` dependency must `make build` here first.
- `packages/e2e` imports `yukey-testkit` through the workspace symlink.
  The testkit's `exports` map carries a `yukey-source` condition pointing at `src/*.ts`;
  the e2e package's tsconfig (`customConditions`) and its node invocation (`--conditions=yukey-source`) both select it,
  so typechecking and running the suite never require a testkit build.
  The default condition still resolves to `dist/`, which is what every outside consumer gets.
- The e2e suite needs a Chromium.  It defaults to `/headless-shell/headless-shell`; `YUKEY_E2E_CHROME` overrides.