## Contributing

**pnpm**

This project uses pnpm for package management. Ensure you have pnpm installed. If not, you can typically install it via npm:

```bash
npm install -g pnpm
```

Then, enable corepack (if not already enabled) and install dependencies:

```bash
corepack enable
corepack prepare --activate
pnpm install
```

## Command Cheatsheet

Run commands from the repository root.

```bash
pnpm install          # install dependencies
pnpm start            # run the browser app at localhost:5173
pnpm desktop:open     # build and open the Electron app locally
pnpm desktop:ci       # desktop unit tests + Electron persistence smoke
pnpm lint:ci          # workspace validation, typecheck, and Biome
pnpm test:ci          # Vitest unit tests
pnpm build            # production browser build
pnpm e2e:ci           # Playwright E2E and component tests
pnpm local-ci-check   # full local CI gate before PRs/releases
```

Desktop packaging and release commands:

```bash
pnpm desktop:dist -- --channel nightly --version 1.0.1-nightly.20260701.12
pnpm desktop:release:stable -- --version 1.0.1
```

## Repository Overview

The repository is a PNPM monorepo with multiple workspaces defined in `pnpm-workspace.yaml`:

```yaml
packages:
  - 'packages/core/*'
  - 'packages/platform/*'
  - 'packages/js-lib/*'
  - 'packages/shared/*'
  - 'packages/tooling/*'
  - 'packages/ui/*'
```

The project's goals and workspace layout are described in `RANT.md`. It explains that the repo contains several workspaces—`tooling`, `core`, `platform`, `ui`, `shared`, and `js-lib`—each with specific responsibilities and dependency rules.

## Key Packages

### Core

Contains the main application logic. Examples include the React App component and services:

- `packages/core/app` – React pages and layout.
- `packages/core/editor` – WYSIWYG editor built on ProseMirror.
- `packages/core/initialize-services` – Bootstraps all services through a dependency‑injection container. Services include routers, command dispatchers, workspace operations, etc.

### Platform

Holds platform-specific implementations, e.g., a browser router.

- `packages/platform/service-platform/src/browser-router.ts` handles URL parsing with a routing strategy and page lifecycle events.

### UI

Pure UI components.

- `packages/ui/ui-components` provides React components such as `Breadcrumb`, `ToggleGroup`, etc.

### Shared

Shared constants, commands, and types. Constants include service names, routes, and config options.

### JS‑Lib

Generic utilities such as an event Emitter, mini validation helpers (mini-zod), and browser utilities. Example: typed broadcast channel for cross‑tab communication.

### Tooling

Contains build and development utilities (vite configs, custom scripts, testing helpers).

- `packages/tooling/browser-entry` bootstraps the app in the browser.

## Core Concepts

- **Dependency Injection**: A custom dependency-injection container (`poor-mans-di`) manages services.
- **Event System**: `root-emitter` provides a scoped event emitter used across tabs and services.
- **Workspace Paths**: The `ws-path` library validates and manipulates workspace paths, ensuring operations on files and directories behave consistently.

For service authoring and wiring rules, see `docs/services.md`.

## Getting Started

**1. Install dependencies**

```bash
pnpm install
```

**2. Run the app**

```bash
pnpm start
```

The development instance will be available on `localhost:5173`.

When working from multiple git worktrees, export a deterministic port set before
running dev servers or Playwright:

```bash
eval "$(node scripts/dev-ports.js --env)"
```

This sets separate ports for the Vite dev server, production preview,
Storybook, Playwright E2E, and Playwright component tests. Generated ports stay
above `3000`, and manual overrides below `3000` are rejected. You can inspect
the assigned ports with `node scripts/dev-ports.js`.

**3. Explore the Codebase**

- Explore the services setup in `packages/core/initialize-services`.
- Look at UI components under `packages/ui/` to understand the styling and design patterns.
- Review utility libraries (under `packages/js-lib/`) to see how events, broadcast channels, and validation are implemented.
- Check `packages/shared/commands/` for the command architecture used throughout the app.
- Read the architecture notes in `RANT.md` for the big-picture design goals.

**Run all CI checks locally (Recommended)**

```bash
pn biome check --fix --unsafe && pn local-ci-check
```

The `local-ci-check` script runs all CI validation scripts defined in package.json (scripts ending with `:ci`):

- `test:ci` - Unit tests with Vitest
- `lint:ci` - Custom validation, typecheck, and biome linting
- `knip:ci` - Full workspace Knip plus production reachability from runtime/tooling entries
- `e2e:ci` - End-to-end and component tests
- `desktop:ci` - Electron desktop tests, build, and smoke test

This ensures your changes will pass CI before pushing to the repository.
Full unit, browser, desktop, and aggregate local CI runs share a repository
lock, so concurrent runs from linked worktrees queue instead of competing for
the same machine. The waiting command reports the PID and worktree holding the
lock and continues automatically when it is released.

`knip:ci` runs two passes:

- `pnpm knip` checks the full repo graph, including tests and tooling, for dependency hygiene and stale files/exports.
- `pnpm knip:production` checks production reachability from the browser Vite entry, Electron main/preload entries, React Native mobile entry, and executable tooling entries. Test-only helpers and specs are excluded from this production graph so tests cannot keep otherwise-dead runtime code alive.

**Typecheck**

```bash
pnpm tsc -b -w
```

**Run all tests**

```bash
pnpm vitest
```

**Snapshot test update**

If you are in mac, you will need to run docker to update the snapshots.
Note: The command for `CT Snapshot update (docker)` uses `v1.52.0-noble`. Please ensure this is the version you intend to use or update it if a newer stable version is available.

CT Snapshot update (local)

```bash
pnpm run e2e-ct-update-snapshots
```

CT Snapshot update (docker)

```bash
docker run -p 9323 -v $(pwd):/work/ mcr.microsoft.com/playwright:v1.52.0-noble bash -c 'cd work && corepack enable && corepack prepare --activate  && pnpm install  && pnpm run e2e-install && NODE_OPTIONS="--max-old-space-size=8144" pnpm run e2e-ct-update-snapshots'
```

Aria snapshot update

```bash
pnpm e2e-update-snapshots
```

**Run in playwright debug mode**

```bash
pnpm --filter "@learnitive/e2e-tests" run test --debug
```

**Component test**

```bash
pnpm e2e-ct-test --ui
```

**Deployment**

Production deployment is TeXise-specific and is intentionally not tied to an inherited upstream repository. Use the checked-in `scripts/install.sh`, `scripts/lib/texise-deploy.sh`, and `deploy/apache/` configuration for the canonical `https://www.texise.com` deployment. Do not deploy unless explicitly requested, and verify the release-quality gates before publishing.

## Custom Scripts

The project includes several utility scripts in `packages/tooling/custom-scripts/scripts/` for maintaining code quality and managing dependencies. All scripts should be run using `bun`:


### All-in-One Maintenance

**Run comprehensive workspace maintenance**

```bash
bun packages/tooling/custom-scripts/scripts/maintenance-all.ts
```

**Recommended for regular maintenance.** This aggregate script runs the most common maintenance tasks in the optimal order:

1. Adds missing workspace dependencies
2. Removes unused dependencies
3. Formats all package.json files
4. Validates workspace structure and dependencies

This command mutates dependency metadata. Review its diff before committing the result.

### Dependency Management

**Remove unused dependencies**

```bash
bun packages/tooling/custom-scripts/scripts/remove-unused-deps.ts
```

Automatically removes unused dependencies from package.json files across the workspace. Skips Node.js packages and ignores `@types/*` and `@bangle.dev/*` packages.

**Add workspace dependencies**

```bash
bun packages/tooling/custom-scripts/scripts/add-workspace-dep.ts
```

Automatically adds missing workspace dependencies to package.json files based on actual imports in TypeScript source files.

### Code Formatting and Validation

**Format all package.json files**

```bash
bun packages/tooling/custom-scripts/scripts/format-package-json.ts
```

Standardizes and sorts all package.json files in the workspace according to project conventions.

**Validate workspace**

```bash
bun packages/tooling/custom-scripts/scripts/validate-all.ts
```

Comprehensive validation of workspace structure, dependency rules, and package configurations. Ensures:

- Browser packages don't depend on Node.js packages
- Service packages follow dependency hierarchy
- All dependencies are properly declared
- Workspace dependency rules are respected

### Theme Generation

**CSS theme processor**

```bash
bun packages/tooling/custom-scripts/scripts/css-theme-gen.ts [input.css]
```

Processes CSS files with theme variables, converting colors to HSL format and validating light/dark theme consistency. Generates `.processed.css` output files.