# Active

Active is a Svelte/SvelteKit application runtime: a coherent set of small engines for app composition, language resolution, diagnostics, formats, DOM/frontend state, storage, HTTP, timers, cache, sessions, authentication and permissions.

The goal is not to replace Svelte. Active fills the layer most teams rebuild differently in every app: the runtime contract between UI, server flows, security, persistence and observability.

## Status

Active is pre-`0.1.0`.

- The current line is suitable for framework exploration, internal apps and integration testing.
- The `0.1.x` goal is a stable public surface for the always-present roots.
- MFA, a full OAuth provider catalog, production WebAuthn and npm publication are intentionally outside the first stable cut.

## Quick Start

```sh
npm install
npm run dev
```

Open:

- `http://localhost:5173/active` for the ecosystem documentation.
- `http://localhost:5173/test/ecosystem` for the full integration test page.
- `http://localhost:5173/test/auth` for the authentication harness.

## Runtime Shape

Active separates logic into three layers:

- `src/libs/*`: pure contracts, constants, helpers and shared types.
- `src/svrs/*`: server-authoritative engines and adapters.
- `src/arts/*`: Svelte-facing active engines and client/runtime integrations.

Root modules follow the same vocabulary:

- `createEngineX(...)` creates an imperative, framework-neutral engine.
- `createActiveX(...)` creates a Svelte 5 reactive wrapper.
- `createActiveApp(...)` composes the always-present roots into one app runtime.

Example:

```ts
import { createActiveApp } from '$aapp';
import { consoleTransport, createEngineLogger } from '$logr';

const Logger = createEngineLogger({
	transports: [consoleTransport()]
});

const App = createActiveApp({
	logger: Logger,
	lang: { schema, defaultLocale: 'es' },
	frontend: { theme: 'base' }
});

App.Lang.t('common.ok');
App.Formats.currency.format(99.5);
App.setLocale('es-MX');
```

## Modules

- `aapp`: composition root and shared locale source.
- `lang`: typed translations, fallback resolution and literal fallback syntax.
- `logr`: logger engine, transports and module diagnostics sink.
- `fmts`: numbers, currency, units and dates derived from locale unless explicitly locked.
- `fend`: application frontend state such as theme, direction, density and scroll/focus behavior.
- `adom`: DOM utilities used by frontend and UI layers.
- `stor`: typed sync storage entries with adapters, validation, versioning and TTL.
- `http`: typed HTTP client/server contracts and shared HTTP constants.
- `timr`: deterministic timer scheduler, clocks and backoff.
- `cach`: data cache with policies, tags, stale handling and adapters.
- `sess`: session lifecycle.
- `auth`: server-first authentication flows plus a safe active client reflector.
- `perm`: authorization engine and active permission client.
- `conn`: realtime connections and channels.
- `sium`: validation schema helpers.

## Development

```sh
npm run check
npm test
npm run build
npm run test:static
npm run test:bundle
npm run test:all
```

`npm run lint` exists, but the full-repo lint pass is still a pre-`0.1` cleanup item.
Use it for focused work and do not add new lint debt.

Rules that matter for contributions:

- Do not put public strings, event names, logger categories or route names inline in implementation files. Define constants first.
- Engines must not depend on Svelte runes or browser globals.
- Active modules must expose the common active-engine shape where applicable.
- Security-sensitive behavior needs tests before it is considered closed.
- Documentation and code comments are written in English.

## Release Readiness

The active checklist before `0.1.0` lives in `docs/before_0_1.md`. The short version:

- security gaps in `auth`, `perm` and `cach` closed or explicitly out of surface;
- root API surface snapshot-tested;
- documentation good enough to onboard without reading source;
- bundle smoke keeps `createActiveApp({})` under the current `0.1` budget;
- CI runs typecheck, tests, build, static smoke and bundle smoke; full-repo lint cleanup is tracked separately before `0.1.0`;
- security policy and changelog exist.

## Security

Please read `SECURITY.md` before reporting or fixing authentication, session, permission, cache or storage issues.

## Brand

The visual direction and asset checklist live in `BRAND.md`.