code-style

---
name: code-style
description: Use when writing or editing TypeScript/Svelte code in this project. Covers project-specific architectural decisions that differ from defaults — module singleton getters for service access, no utils/helpers directories, no barrel exports, and the conversational commenting style.
---

# TKA Code Style

Project-specific architectural decisions. Standard engineering wisdom (single responsibility, descriptive names, strict types) is assumed.

## Service Access: Module Singleton Getters

Services are accessed via colocated getter functions — no central container, no DI framework.

```typescript
// Getter file — lives next to the implementation
// src/lib/features/your-module/services/getYourService.ts
import { browser } from '$app/environment';
import { YourService } from './implementations/YourService';

let instance: YourService | null = null;

export function getYourService(): YourService {
  if (!browser) throw new Error('getYourService() is browser-only');
  return instance ??= new YourService();
}

// Consumer
import { getYourService } from '$lib/features/your-module/services/getYourService';
const myService = getYourService();
```

Every service: interface in `services/contracts/IName.ts`, implementation in `services/implementations/Name.ts`, getter colocated in the same services directory. Side-effect wiring (if any) lives in `src/lib/shared/bootstrap.ts`.

## Never Create Utility Files

No `utils/`, `helpers/`, or `hooks/` directories. No standalone pure functions in random files. If you think you need a utility, you need a service class with a module singleton getter.

## No Barrel Exports

Never create `index.ts` files in `src/` that re-export other modules. Vite's bundle bloats dramatically — importing one item from a barrel loads and evaluates the entire barrel, tree-shaking fails, dev-mode network requests skyrocket. Always import directly from source files using relative paths.

## Commenting Style

Write comments as if explaining to someone who uses the app but doesn't write code. Say what the user would observe, not what the code does internally. Explain *why* — what problem does this solve, what would go wrong without it.

**Good:**
```ts
// We normally find a sequence by its word (e.g. "ABBD"). But if the user
// edited and re-saved it with a different word (e.g. "ABBDJ"), our lookup
// table still has the old word and won't find the new one. In that case,
// we fall back to locating it by its unique ID instead.
```

**Bad:**
```ts
// Look up sourceRef from cache. If word changed, fall back to ownerId + id.
```

## Svelte 5

Use runes (`$state`, `$derived`, `$effect`) not legacy reactive syntax. Prefer `$derived` over `$effect` when computing values. Use `$props()` with TypeScript interfaces.

## State Management

Use context + runes for shared state, not stores. See the `state-management` skill for the factory+context pattern.