@luckystack/core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to `@luckystack/core` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- Initial public release as part of the LuckyStack package split.

package/CLAUDE.md

@@ -0,0 +1,210 @@
+# @luckystack/core
+
+> AI summary + function INDEX. For deep specs see `docs/` next to this file.
+
+## What this package does
+
+Foundation package for LuckyStack. Owns the socket-first transport contracts (`apiMessage`, `syncMessage`, io-instance slot), the registries that every other framework package reads from (project config, deploy/services config, runtime maps, prisma/redis clients, notifier, email senders, error trackers, logger), and the cross-cutting primitives (rate limiter, CORS check, validateRequest, hook bus, response normalizer, offline queue, CSRF, cookies). Every other `@luckystack/*` package depends on this one and never reaches around it.
+
+## When to USE
+
+- Reading the active runtime config (`getProjectConfig()`, `getProjectName()`, `getBindAddress()`).
+- Registering DI slots from the project's boot entry (`registerProjectConfig`, `registerPrismaClient`, `registerRedisClient`, `registerLogger`, `registerNotifier`, `registerEmailSender(s)`, `registerErrorTracker(s)`, `registerRuntimeMapsProvider`, `registerApiMethodMap`, `registerAvatarConfig`, `registerBindAddress`, `registerRateLimitStrategy`).
+- Subscribing to lifecycle/transport events via `registerHook(...)` / `registerSyncHook(...)`.
+- Calling the cross-cutting primitives directly when a feature package would be overkill (`tryCatch`, `notify`, `checkRateLimit`, `allowedOrigin`, `validateRequest`, `extractTokenFromSocket`, `extractTokenFromRequest`, the offline queue API).
+- Reading shared transport types (`BaseSessionLayout`, `AuthProps`, `apiMessage`, `syncMessage`, `SOCKETSTATUS`).
+
+## When NOT to suggest yet
+
+- Building a feature endpoint: import `@luckystack/api` / `@luckystack/sync` instead — they wrap core's hooks and validation in the file-based routing contract.
+- Sending email: use `@luckystack/email`'s `sendEmail(...)` (it routes through `getEmailSenderByName`).
+- Booting an HTTP server: use `createLuckyStackServer` from `@luckystack/server` — it wires `registerBindAddress`, `setIoInstance`, `attachSocketRedisAdapter`, security headers, etc. for you.
+- Replacing Sentry: register an adapter via `@luckystack/error-tracking` (which calls `registerErrorTracker(s)` here). Do not call `initSharedSentry` in new code.
+- Anything React-coupled: import from `@luckystack/core/client` (browser-safe subpath) or from the consuming feature package's `/client` entry. The server barrel intentionally does NOT export `apiRequest`.
+- Defining project session types: extend `BaseSessionLayout` in your project's own `config.ts` — do not edit the core type.
+
+## Function Index
+
+| Function / Export | 1-line | Deep doc |
+| --- | --- | --- |
+| `registerProjectConfig(config: ProjectConfigInput): void` | Deep-merge installer config over `DEFAULT_PROJECT_CONFIG`; call once at boot before any framework code runs. | -> docs/config-registry.md |
+| `getProjectConfig(): ProjectConfig` | Read the active config at call time (never at module load). | -> docs/config-registry.md |
+| `getProjectName(): string` | Resolve the Redis-prefix project name (config -> `PROJECT_NAME` env -> `'luckystack'`). | -> docs/config-registry.md |
+| `isProjectConfigRegistered(): boolean` | Boot-time guard for code paths that must run after registration. | -> docs/config-registry.md |
+| `DEFAULT_PROJECT_CONFIG: ProjectConfig` | Built-in defaults exported so consumers can spread + override structurally. | -> docs/config-registry.md |
+| `registerDeployConfig(config: DeployConfigShape): DeployConfigShape` | Register the project's deploy topology (resources, environments, routing, development). | -> docs/config-registry.md |
+| `getDeployConfig(): DeployConfigShape` | Read deploy topology (defaults to `{ resources: {} }`). | -> docs/config-registry.md |
+| `isDeployConfigRegistered(): boolean` | Guard for router/boot probes that need a registered deploy config. | -> docs/config-registry.md |
+| `registerServicesConfig(config: ServicesConfigShape): ServicesConfigShape` | Register services + presets topology (consumed by router/presetLoader). | -> docs/config-registry.md |
+| `getServicesConfig(): ServicesConfigShape` | Throws when no services config has been registered. | -> docs/config-registry.md |
+| `isServicesConfigRegistered(): boolean` | Non-throwing guard. | -> docs/config-registry.md |
+| `registerAvatarConfig(config: AvatarConfigInput): void` | Override avatar disk format(s) + Cache-Control header. | -> docs/config-registry.md |
+| `getAvatarConfig(): AvatarConfig` | Read active avatar config. | -> docs/config-registry.md |
+| `DEFAULT_AVATAR_CONFIG: AvatarConfig` | Default formats `[{ extension: 'webp', contentType: 'image/webp' }]` + 24h cache. | -> docs/config-registry.md |
+| `registerBindAddress(address: { ip: string; port: number }): void` | `createLuckyStackServer` writes the resolved listen address here at boot. | -> docs/app-bootstrap.md |
+| `getBindAddress(): { ip: string; port: string }` | Resolve at call time (registry -> `SERVER_IP`/`SERVER_PORT` -> `'127.0.0.1'`/`''`). | -> docs/app-bootstrap.md |
+| `registerRuntimeMapsProvider(provider: RuntimeMapsProvider): void` | DI slot for generated api/sync maps; called by project `server/prod/runtimeMaps.ts`. | -> docs/app-bootstrap.md |
+| `getRuntimeApiMaps(): Promise<RuntimeApiMapsResult>` | Async accessor for `{ apisObject, functionsObject }`. | -> docs/app-bootstrap.md |
+| `getRuntimeSyncMaps(): Promise<RuntimeSyncMapsResult>` | Async accessor for `{ syncObject, functionsObject }`. | -> docs/app-bootstrap.md |
+| `isRuntimeMapsProviderRegistered(): boolean` | Boot-fail-mode detector for `verifyBootstrap`. | -> docs/app-bootstrap.md |
+| `registerApiMethodMap(map: ApiMethodMap): void` | Register generated `apiMethodMap` so `apiRequest` can look up real HTTP methods. | -> docs/app-bootstrap.md |
+| `getRegisteredApiMethod(pagePath: string, apiName: string, version: string): HttpMethodLiteral \| undefined` | Lookup helper used by `isGetMethod`. | -> docs/app-bootstrap.md |
+| `isApiMethodMapRegistered(): boolean` | Detect whether the prefix-heuristic fallback is active. | -> docs/app-bootstrap.md |
+| `registerPrismaClient(client: PrismaClient, key?: string): PrismaClient` | Register a Prisma client into a slot (default `'default'`). Pass a `key` for graded credentials (e.g. `'ro'`/`'rw'`) or per-tenant clients. | -> docs/app-bootstrap.md |
+| `registerRedisClient(client: RedisClient, key?: string): RedisClient` | Register an ioredis client into a slot (default `'default'`). | -> docs/app-bootstrap.md |
+| `getPrismaClient(): PrismaClient` | Read the `'default'` slot (registered client or lazy default resolver). | -> docs/app-bootstrap.md |
+| `getRedisClient(): RedisClient` | Read the `'default'` slot (registered client or lazy default resolver). | -> docs/app-bootstrap.md |
+| `getPrismaClientFor(key?: string): PrismaClient` | Read a specific slot. `'default'` falls back to the resolver; any other unregistered slot throws (never silently returns the privileged default). | -> docs/app-bootstrap.md |
+| `getRedisClientFor(key?: string): RedisClient` | Read a specific Redis slot (same semantics as `getPrismaClientFor`). | -> docs/app-bootstrap.md |
+| `getPrismaClientKeys(): string[]` / `getRedisClientKeys(): string[]` | Diagnostic — which slots have an explicitly-registered client. | -> docs/app-bootstrap.md |
+| `DEFAULT_CLIENT_KEY: 'default'` | The reserved slot backing every framework internal + the `prisma`/`redis` proxies. | -> docs/app-bootstrap.md |
+| `isPrismaClientRegistered(): boolean` | Boot guard — true when the `'default'` slot is registered. | -> docs/app-bootstrap.md |
+| `isRedisClientRegistered(): boolean` | Boot guard — true when the `'default'` slot is registered. | -> docs/app-bootstrap.md |
+| `resetClientsForTests(): void` | Test-only — drop every registered slot (default resolvers stay set). | -> docs/app-bootstrap.md |
+| `redis` | Proxy that forwards every call to the currently registered ioredis client. Applies `applyStrayKeyPrefix` to single-key commands as a best-effort namespace net (keys containing `:` pass through untouched). | -> docs/redis-adapter.md |
+| `getRedisConnectionOptions(): RedisConnectionOptions` | Single source of truth for `{ host, port, username?, password? }` (router reuses for cross-env probes). | -> docs/redis-adapter.md |
+| `formatKey(namespace: string, suffix?: string): string` | Build a namespaced Redis key through the active formatter. The single authority every framework key-site routes through (`-session`, `-activeUsers`, `-pwreset`, `-email-change`, `-oauth-state`, `:rate-limit`). Default reproduces historical key bytes (zero migration). | -> docs/redis-adapter.md |
+| `registerRedisKeyFormatter(fn: RedisKeyFormatter): void` | Override how every framework Redis key is namespaced (multi-tenant per-tenant prefixing). Must preserve the `<namespace-root>:<suffix>` join so `SCAN` enumeration still works. | -> docs/redis-adapter.md |
+| `getRedisKeyFormatter(): RedisKeyFormatter` / `defaultRedisKeyFormatter` / `resetRedisKeyFormatterForTests()` | Read the active formatter / the built-in default / test reset. | -> docs/redis-adapter.md |
+| `applyStrayKeyPrefix(key: string): string` | Project-prefix an un-namespaced (colon-free) key; pass-through for already-namespaced keys. Used by the `redis` proxy net. | -> docs/redis-adapter.md |
+| `acquireLease(name, ttlMs): Promise<string \| null>` | Acquire an exclusive Redis lease (`SET NX PX`). Returns an owner token, or null if held. Single-Redis best-effort (not Redlock) — the lease is a primitive; the renew loop is app code. | -> docs/redis-adapter.md |
+| `renewLease(name, token, ttlMs): Promise<boolean>` | Owner-checked compare-and-pexpire (Lua); extends only if `token` still holds the lease. | -> docs/redis-adapter.md |
+| `releaseLease(name, token): Promise<boolean>` | Owner-checked compare-and-delete (Lua); releasing another owner's lease is a no-op. | -> docs/redis-adapter.md |
+| `attachSocketRedisAdapter(io: SocketIOServer): void` | Wire `@socket.io/redis-adapter` with duplicated pub/sub clients so room broadcasts span instances. | -> docs/redis-adapter.md |
+| `setIoInstance(io: SocketIOServer \| null): void` | Module-level slot for the running Socket.io server. | -> docs/socket-bootstrap.md |
+| `getIoInstance(): SocketIOServer \| null` | Read the slot from framework code that needs to broadcast. | -> docs/socket-bootstrap.md |
+| `socket`, `setSocket`, `incrementResponseIndex`, `waitForSocket` | Client-side socket singleton + response-index counter. | -> docs/socket-bootstrap.md |
+| `extractTokenFromSocket(socket): string \| null` | Read session token from Socket.io handshake (cookie + header). | -> docs/socket-bootstrap.md |
+| `extractTokenFromRequest(request): string \| null` | Read session token from a Node IncomingMessage (cookie + `Authorization: Bearer`). | -> docs/socket-bootstrap.md |
+| `allowedOrigin(origin: string): boolean` | Same-origin + project-configured allow-list CORS check; dispatches `corsRejected` hook on miss. | -> docs/socket-bootstrap.md |
+| `validateRequest({ data, user, auth }): ValidationResult` | Auth gate driven by `AuthProps`; checks login + `additional[]` predicates. | -> docs/session-types.md |
+| `isFalsy(value): boolean` | Helper used inside `validateRequest`. | -> docs/session-types.md |
+| `validateInputByType(value, type)` | Runtime input validation; lazy-loads `@luckystack/devkit` in dev. | -> docs/session-types.md |
+| `registerNotifier(notifier: Notifier): void` | DI for client-side toast notifier (success/error/info/warning). | -> docs/app-bootstrap.md |
+| `getNotifier(): Notifier` | Read active notifier (no-op default). | -> docs/app-bootstrap.md |
+| `notify: Notifier` | Delegating wrapper used by framework hot paths. | -> docs/app-bootstrap.md |
+| `registerEmailSender(sender: EmailSender): void` | Legacy single-sender registration; mirrors into `default` slot. | -> docs/app-bootstrap.md |
+| `registerEmailSenders(senders: EmailSenderRegistry): void` | Multi-adapter registration (`'default'`, `'transactional'`, `'marketing'`, custom). | -> docs/app-bootstrap.md |
+| `getEmailSender(): EmailSender \| null` | Read legacy/`default` sender. | -> docs/app-bootstrap.md |
+| `getEmailSenderByName(name: string): EmailSender \| null` | Read a specific slot (falls back to legacy sender for `'default'`). | -> docs/app-bootstrap.md |
+| `listEmailSenderNames(): string[]` | Diagnostic helper. | -> docs/app-bootstrap.md |
+| `isEmailSenderRegistered(): boolean` | Boot guard. | -> docs/app-bootstrap.md |
+| `registerLogger(logger: Logger): void` | Plug in Pino/Winston/Datadog (or `createDevLogger()` for colored dev output). | -> docs/app-bootstrap.md |
+| `getLogger(): Logger` | Read at call time (default = console.{debug,info,warn,error}). | -> docs/app-bootstrap.md |
+| `isLoggerRegistered(): boolean` | Boot guard. | -> docs/app-bootstrap.md |
+| `createDevLogger(): Logger` | Factory for the dev-mode colored logger (depends on `initConsolelog()`). | -> docs/app-bootstrap.md |
+| `resetLoggerForTests(): void` | Test-only — restore default logger. | -> docs/app-bootstrap.md |
+| `registerRedactedLogKeys(keys: Iterable<string>): void` | Add keys that the framework will redact from log payloads. | -> docs/app-bootstrap.md |
+| `getRedactedLogKeys(): Set<string>` | Read current redacted-keys set. | -> docs/app-bootstrap.md |
+| `isRedactedLogKey(key: string): boolean` | Hot-path lookup used inside the framework. | -> docs/app-bootstrap.md |
+| `resetRedactedLogKeysForTests(): void` | Test-only reset. | -> docs/app-bootstrap.md |
+| `initConsolelog(): void` | Monkey-patch `console.*` to render trailing color string (dev only). | -> docs/app-bootstrap.md |
+| `registerLocaleReloader(reloader: LocaleReloader): void` | DI for the dev-only i18n hot-reload trigger. | -> docs/app-bootstrap.md |
+| `getLocaleReloader(): LocaleReloader \| null` | Read active reloader (returns null when no project supplied one). | -> docs/app-bootstrap.md |
+| `registerErrorTracker(tracker: ErrorTracker): void` | Single-tracker registration (replaces previous). | -> docs/error-tracker-registry.md |
+| `registerErrorTrackers(trackers: ErrorTracker[]): void` | Multi-tracker registration (replaces the list). | -> docs/error-tracker-registry.md |
+| `getActiveErrorTrackers(): ErrorTracker[]` | Read active trackers. | -> docs/error-tracker-registry.md |
+| `captureExceptionAcrossTrackers(error, context?): void` | Fan-out exception capture; per-tracker errors are swallowed. | -> docs/error-tracker-registry.md |
+| `captureMessageAcrossTrackers(message, level, context?): void` | Fan-out message capture. | -> docs/error-tracker-registry.md |
+| `setErrorTrackerUser(user: ErrorTrackerUser \| null): void` | Fan-out user identification. | -> docs/error-tracker-registry.md |
+| `recordMetricAcrossTrackers(name, value, tags?): void` | Optional metric fan-out (skips trackers without `recordMetric`). | -> docs/error-tracker-registry.md |
+| `startSpanAcrossTrackers<T>(name, op, fn): T` | First tracker that supports spans wins; falls back to direct `fn()`. | -> docs/error-tracker-registry.md |
+| `initSharedSentry(instance)` | Legacy Sentry slot (kept for backwards compatibility). | -> docs/error-tracker-registry.md |
+| `captureException(error, context?): void` | Legacy fan-out: Sentry slot + adapter list. | -> docs/error-tracker-registry.md |
+| `captureMessage(message, level?, context?): void` | Legacy fan-out: Sentry slot + adapter list. | -> docs/error-tracker-registry.md |
+| `setSentryUser(user): void` | Legacy fan-out: Sentry slot + adapter list. | -> docs/error-tracker-registry.md |
+| `startSpan(name, op): unknown` | Legacy span helper. | -> docs/error-tracker-registry.md |
+| `checkRateLimit(params: CheckRateLimitParams): Promise<RateLimitResult>` | Delegates to the active strategy's `check()`. | -> docs/rate-limit-strategy.md |
+| `getRateLimitStatus(key, limit): Promise<RateLimitResult>` | Read-only status (does not increment). | -> docs/rate-limit-strategy.md |
+| `clearRateLimit(key): Promise<void>` | Reset a single key. | -> docs/rate-limit-strategy.md |
+| `clearAllRateLimits(): Promise<void>` | Reset every key under the active strategy's namespace. | -> docs/rate-limit-strategy.md |
+| `registerRateLimitStrategy(strategy: RateLimitStrategy): void` | Swap the backend (token-bucket, edge-KV, per-tier, no-op). | -> docs/rate-limit-strategy.md |
+| `getRateLimitStrategy(): RateLimitStrategy` | Read the currently active strategy. | -> docs/rate-limit-strategy.md |
+| `defaultRateLimitStrategy: RateLimitStrategy` | Built-in memory-or-redis backend. | -> docs/rate-limit-strategy.md |
+| `registerHook<TName>(name, handler): void` | Subscribe an async handler to a lifecycle event. | -> docs/hooks.md |
+| `registerMiddlewareHandler(handler: MiddlewareHandler): void` | Register the GLOBAL route-guard fallback. Called by `<Middleware>` / `useRouter` only when no per-page middleware is registered for the visited route. Optional — framework default allows by-default. | -> docs/hooks.md |
+| `getMiddlewareHandler(): MiddlewareHandler` | Read the active global handler. | -> docs/hooks.md |
+| `registerPageMiddleware(path: string, fn: PageMiddleware): void` | Register a per-page route guard. Auto-called by `src/main.tsx`'s `getRoutes()` for every page that exports `middleware`. Per-page takes precedence over the global handler. | -> docs/hooks.md |
+| `getPageMiddleware(path: string): PageMiddleware \| undefined` | Lookup the per-page guard for a given route. Framework-internal. | -> docs/hooks.md |
+| `hasPageMiddleware(path: string): boolean` | Existence check. | -> docs/hooks.md |
+| `MiddlewareInput`, `MiddlewareResult`, `MiddlewareHandler`, `PageMiddleware` (types) | Route-guard contract types. Both handler shapes share the same signature. | -> docs/hooks.md |
+| `validatePagePath(srcRelativePath, rules?): PagePathValidationResult` | Pure validator for the invisible-parent folder convention used by `src/main.tsx`'s page auto-discovery AND the `scaffold:page` CLI. Returns `{ valid, route?, reason? }`. | -> docs/hooks.md |
+| `DEFAULT_PAGE_ROUTE_RULES: PageRouteRules` | Default config (private-folder prefix `'_'` + reserved framework folders). | -> docs/hooks.md |
+| `dispatchHook<TName>(name, payload): Promise<DispatchResult>` | Internal: framework code invokes registered handlers in order; first stop signal aborts. | -> docs/hooks.md |
+| `clearAllHooks(): void` | Test-only — drop every registered handler (sync + async). | -> docs/hooks.md |
+| `registerSyncHook<TName>(name, handler): void` | Subscribe a synchronous mutator to a hot-path hook (e.g. error normalization). | -> docs/hooks.md |
+| `dispatchSyncHook<TName>(name, payload): void` | Internal: framework code invokes sync handlers; payload is mutated in place. | -> docs/hooks.md |
+| `BaseSessionLayout`, `SessionLocation`, `AuthProps` (types) | Foundational session-shape types; project `SessionLayout` extends `BaseSessionLayout`. | -> docs/session-types.md |
+| `HookSessionShape`, `HookName`, `HookHandler`, `HookResult`, `HookStopSignal`, `HookPayloads` (types) | Hook contract types (augmentable via TS module augmentation). | -> docs/hooks.md |
+| `isOnline()` / `enqueueApiRequest` / `enqueueSyncRequest` / `removeApiQueueItem` / `removeSyncQueueItem` / `removeApiQueueItemsByKey` / `flushApiQueue` / `flushSyncQueue` / `getApiQueueSize` / `getSyncQueueSize` | Client-side offline queue with per-item `dropPolicy` and global max-size/max-age caps. | -> docs/socket-bootstrap.md |
+| `getCsrfToken()`, `clearCsrfToken()`, `httpFetch(...)` | CSRF-aware fetch wrapper used by the client transport. | -> docs/socket-bootstrap.md |
+| `registerCsrfConfig(input: Partial<CsrfConfig>): void` | Override the CSRF cookie name, header name, token length, or cookie options. | -> docs/csrf-config.md |
+| `getCsrfConfig(): CsrfConfig` | Read the active CSRF config at call time (defaults to `DEFAULT_CSRF_CONFIG`). | -> docs/csrf-config.md |
+| `DEFAULT_CSRF_CONFIG: CsrfConfig` | Built-in defaults (`csrf-token` cookie, `x-csrf-token` header, 32-byte token). | -> docs/csrf-config.md |
+| `resetCsrfConfigForTests(): void` | Test-only — restore CSRF defaults between scenarios. | -> docs/csrf-config.md |
+| `registerSocketMiddleware(mw: SocketMiddleware): void` | Wedge an `io.use(...)` middleware into the framework's socket bootstrap; runs before any `connect` handler. | -> docs/socket-bootstrap.md |
+| `getSocketMiddlewares(): readonly SocketMiddleware[]` | Read the registered middleware list. | -> docs/socket-bootstrap.md |
+| `clearSocketMiddlewares(): void` | Drop every registered middleware (test/hot-reload helper). | -> docs/socket-bootstrap.md |
+| `applySocketMiddlewares(io: SocketIOServer): void` | Wire every registered middleware into the running Socket.io server (called from `@luckystack/server`'s `loadSocket`). | -> docs/socket-bootstrap.md |
+| `writeBootUuid(envKey?): Promise<string>` | Write a fresh UUID to `luckystack:boot:<envKey>` with the configured TTL. | -> docs/app-bootstrap.md |
+| `readBootUuid(envKey?): Promise<string \| null>` | Read the boot UUID (router cross-checks against `/_health`). | -> docs/app-bootstrap.md |
+| `resolveEnvKey(): string` | `LUCKYSTACK_ENV` -> `NODE_ENV` -> `'development'`. | -> docs/app-bootstrap.md |
+| `BOOT_KEY_PREFIX: 'luckystack:boot:'` | Constant — single source of truth so router can't drift. | -> docs/app-bootstrap.md |
+| `collectSynchronizedEnvKeys()` / `computeSynchronizedEnvHashes()` / `hashSynchronizedValue()` | Cross-env drift detection helpers for the router boot handshake. | -> docs/app-bootstrap.md |
+| `tryCatch<T>(fn): Promise<[Error \| null, T \| null]>` | Tuple-style async error handling used everywhere in the framework. | -> docs/app-bootstrap.md |
+| `sleep(ms): Promise<void>` | `setTimeout`-based delay. | -> docs/app-bootstrap.md |
+| `getParams(request)` | Parse URL params from a Node request. | -> docs/app-bootstrap.md |
+| `serveAvatar(...)` | HTTP handler for `/avatars/:fileId`; rejects path-traversal, applies `AvatarConfig`. | -> docs/app-bootstrap.md |
+| `processUpload(input: ProcessUploadInput): Promise<ProcessUploadResult>` | Wraps a project encode/save callback with the `onUploadStart`/`onUploadComplete` hook contract. | -> docs/hooks.md |
+| Response normalizers (`normalizeErrorResponse`, `extractLanguageFromHeader`, ...) | Shared error-shape + i18n helpers; dispatches `preErrorNormalize` / `postErrorNormalize` sync hooks. | -> docs/hooks.md |
+| `serviceRoute` exports | Helpers to build router-routable URLs across services. | -> docs/socket-bootstrap.md |
+| `socketEvents` exports | Wire-protocol constants for socket events. | -> docs/socket-bootstrap.md |
+| `paths` exports (`getGeneratedApiDocsPath`, `getApiMethodMapPath`, ...) | Paths resolved through `projectConfig.paths`. | -> docs/config-registry.md |
+| `cookies` exports | Cookie parse/serialise helpers used by the HTTP layer. | -> docs/socket-bootstrap.md |
+| `httpApiUtils` exports | Shared HTTP helpers (status codes, header writers). | -> docs/socket-bootstrap.md |
+
+## Config keys
+
+Env vars read directly by core (via `env.ts` and call-time helpers):
+
+| Env var | Default | Consumer |
+| --- | --- | --- |
+| `NODE_ENV` | `'development'` | Zod-validated, mirrored to `process.env`. |
+| `SERVER_IP` | `'127.0.0.1'` | `getBindAddress()` fallback. |
+| `SERVER_PORT` | `'80'` | `getBindAddress()` fallback. |
+| `SECURE` | `'false'` | `allowedOrigin` scheme selection. |
+| `DNS` | `''` | Reserved for downstream packages. |
+| `REDIS_HOST` | `'127.0.0.1'` | `redis.ts` default client + `getRedisConnectionOptions`. |
+| `REDIS_PORT` | `'6379'` | Same. |
+| `REDIS_USERNAME` | (unset) | Optional ioredis auth. |
+| `REDIS_PASSWORD` | (unset) | Optional ioredis auth. |
+| `PROJECT_NAME` | `'luckystack'` | Redis-prefix fallback in `getProjectName()`. |
+| `LUCKYSTACK_ENV` | (unset) | `resolveEnvKey()` first preference (boot UUID, router handshake). |
+| `LUCKYSTACK_ENV_FILES` | `.env,.env.local` | Ambient override for `getEnvFiles()` / `loadEnvFiles()` — comma-separated list of env files to load, "later overrides earlier". |
+
+`registerProjectConfig` slots (see `ProjectConfig` for full surface): `app.publicUrl`, `logging.*`, `rateLimiting.{enabled, store, redisKeyPrefix, defaultApiLimit, defaultIpLimit, windowMs, cleanupIntervalMs}`, `session.{basedToken, expiryDays, perBrowser, perUser, maxConcurrentPerUser, onConflict, notifyOldDeviceOnRevoke, projectName}`, `http.{sessionCookie*, requestBodyMaxBytes, healthEndpoint, liveEndpoint, readyEndpoint, testResetEndpoint, stream, securityHeaders, cors}`, `auth.{passwordPolicy, emailMaxLength, nameMaxLength, bcryptRounds, providerAccountStrategy, forgotPassword, passwordResetTtlSeconds, passwordResetBrand}`, `socket.{maxHttpBufferSize, pingTimeout, pingInterval}`, `sync.{streamThrottle, fanoutYieldEvery, fanoutYieldMs}`, `offlineQueue.{maxSize, maxAgeMs, dropPolicy}`, `dev.{hotReloadDebounceMs, watcherStabilityThresholdMs, watcherPollIntervalMs, warnOnMissingInputType}`, `paths.*`, `defaultLanguage`, `defaultTheme`, `socketActivityBroadcaster`, `socketStatusIndicator`, `locationProviderEnabled`, `loginRedirectUrl`.
+
+Other registries: `registerDeployConfig(DeployConfigShape)`, `registerServicesConfig(ServicesConfigShape)`, `registerAvatarConfig(AvatarConfigInput)`, `registerBindAddress({ ip, port })`.
+
+## Peer dependencies
+
+Required:
+
+- `@prisma/client@^6.19.0` — DB client proxied through `getPrismaClient()`.
+- `ioredis@^5.10.0` — Redis client proxied through `getRedisClient()`; backs the rate limiter, session store, boot-UUID, and offline-queue.
+- `socket.io@^4.8.0` — server-side `SocketIOServer` consumed by `setIoInstance` and `attachSocketRedisAdapter`.
+- `socket.io-client@^4.8.0` — client-side socket types used by the offline queue.
+- `zod@^4.0.0` — `env.ts` schema parsing.
+
+Optional (mark in `peerDependenciesMeta`):
+
+- `react@^19.0.0`, `react-dom@^19.0.0`, `react-router-dom@^7.0.0` — only consumed by `@luckystack/core/client` and the `react/*` subpath helpers. Pure server boots can skip these.
+- `sonner@^2.0.0` — only needed if you wire the default sonner-backed notifier from the project's React entry; the core notifier slot itself is library-agnostic.
+
+Runtime (bundled): `@socket.io/redis-adapter`, `dotenv`.
+
+## Related
+
+- README: `packages/core/README.md`
+- Architecture deep-dives: `docs/ARCHITECTURE_EXTENSION_POINTS.md`, `docs/ARCHITECTURE_PACKAGING.md`, `docs/ARCHITECTURE_SOCKET.md`, `docs/ARCHITECTURE_MULTI_INSTANCE.md`, `docs/ARCHITECTURE_API.md`, `docs/ARCHITECTURE_SYNC.md`, `docs/ARCHITECTURE_SESSION.md`, `docs/ARCHITECTURE_AUTH.md`, `docs/ARCHITECTURE_ROUTING.md`
+- Project-side glue: `config.ts`, `server/server.ts`, `server/prod/runtimeMaps.ts`, `src/_sockets/socketInitializer.ts`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathijs van Melick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @luckystack/core
+
+> Foundation package for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). Socket-first transport contracts, Redis adapter, project-config registry, hooks registry, response normalization, rate limiting, and shared session types.
+
+Every other `@luckystack/*` package depends on this one.
+
+## Install
+
+```bash
+npm install @luckystack/core
+```
+
+Peer dependencies you must install separately:
+
+```bash
+npm install @prisma/client ioredis socket.io socket.io-client zod
+```
+
+## Quickstart
+
+The core package is mostly consumed transitively through `@luckystack/server`, `@luckystack/api`, etc. You typically only touch it directly to register your project config and to call low-level utilities.
+
+```ts
+import { registerProjectConfig, getProjectConfig, notify, redis, prisma } from '@luckystack/core';
+
+registerProjectConfig({
+  defaultLanguage: 'en',
+  session: { expiryDays: 30, basedToken: false, allowMultiple: true },
+  auth: {
+    emailMaxLength: 254,
+    passwordMinLength: 8,
+    passwordMaxLength: 128,
+    nameMaxLength: 64,
+    oauthStateTtlSeconds: 600,
+  },
+  // ...see ProjectConfig type for the full surface
+});
+
+const config = getProjectConfig();
+```
+
+## Subpath: `@luckystack/core/client`
+
+Browser-safe surface for the React/Vite bundle. Re-exports the pieces consumed by `@luckystack/sync`'s client transport (`projectConfig`, `notifier`, `socketState`, `offlineQueue`, `responseNormalizer`, `serviceRoute`, `socketEvents`, `socketStatusTypes`, `apiTypeStubs`, `sessionTypes`).
+
+```ts
+import { socket, isOnline, enqueueApiRequest } from '@luckystack/core/client';
+```
+
+## Public API (server entry)
+
+| Group | Exports |
+| --- | --- |
+| Project config | `registerProjectConfig`, `getProjectConfig`, `getProjectName`, `isProjectConfigRegistered`, `DEFAULT_PROJECT_CONFIG`. Types: `ProjectConfig`, `ProjectConfigInput`, `LoggingConfig`, `RateLimitingConfig`, `SessionConfig`, `SentryConfig`, `SentrySampleRates`, `HttpConfig`, `HttpStreamConfig`, `SecurityHeadersConfig`, `CorsConfig`, `AuthConfig`, `SocketConfig`, `SyncConfig`, `SyncStreamThrottleConfig`, `OfflineQueueConfig`, `DevConfig`, `PathsConfig`, `EmailConfig`, `EmailLoggingConfig`, `EmailEnvVarsConfig`, `EmailDefaultsConfig`. **`getProjectName()`** is the canonical way to read the project's Redis-prefix string — it resolves at call time in this order: (1) `projectConfig.session.projectName` if a consumer set it, (2) `process.env.PROJECT_NAME` (read after `dotenv` has loaded), (3) literal `'luckystack'` as the absolute fallback. Reach for it from any framework or project code that needs the prefix instead of duplicating the env-read pattern. |
+| Deploy + services config | `registerDeployConfig`, `getDeployConfig`, `isDeployConfigRegistered`, `registerServicesConfig`, `getServicesConfig`, `isServicesConfigRegistered`. Types: `DeployConfigShape`, `DeployResourceShape`, `DeployEnvironmentShape`, `DeployRoutingShape`, `DeployDevelopmentShape`, `ServicesConfigShape`, `ServiceDefinition`, `PresetDefinition` |
+| Runtime maps | `registerRuntimeMapsProvider`, `getRuntimeApiMaps`, `getRuntimeSyncMaps`. Types: `RuntimeMapsProvider`, `RuntimeApiMapsResult`, `RuntimeSyncMapsResult` |
+| DI clients | `registerPrismaClient`, `registerRedisClient`, `getPrismaClient`, `getRedisClient`, `isPrismaClientRegistered`, `isRedisClientRegistered` |
+| Notifier | `registerNotifier`, `getNotifier`, `notify`. Types: `Notifier`, `NotifyInput`, `NotifyParam` |
+| Email registry | `registerEmailSender`, `getEmailSender`, `isEmailSenderRegistered`. Types: `EmailSender`, `EmailMessage`, `EmailResult` (re-exported from `@luckystack/email` for convenience) |
+| Logger | `registerLogger`, `getLogger`, `isLoggerRegistered`, `resetLoggerForTests`, `createDevLogger`. Types: `Logger`, `LoggerContext`. Default logger is a thin wrapper over `console.{debug,info,warn,error}` with no color codes — safe in production. Call `registerLogger(createDevLogger())` from a dev-only entry to opt into the colored terminal output (which still depends on `initConsolelog()` to render the trailing color string). Plug in Pino / Winston / Datadog by registering an object that satisfies `Logger`. |
+| Redacted log keys | `registerRedactedLogKeys`, `getRedactedLogKeys`, `isRedactedLogKey`, `resetRedactedLogKeysForTests` |
+| Avatar / uploads | `registerAvatarConfig`, `getAvatarConfig`, `DEFAULT_AVATAR_CONFIG`, `serveAvatar`, `processUpload`. Types: `AvatarConfig`, `AvatarConfigInput`, `ProcessUploadInput`, `ProcessUploadResult`. **Path-traversal guard:** `serveAvatar` rejects any `fileId` that does not match `/^[A-Za-z0-9_-]{1,128}$/` with a 400 before touching the filesystem — `..`, slashes, and other path-separator characters cannot escape the configured upload directory. **`processUpload`** wraps the project-supplied encode/save callback with the framework's `onUploadStart` (stoppable) and `onUploadComplete` hook contract so consumer upload routes don't need to plumb the hooks themselves. Returns `{ status: 'success', sizeBytes }`, `{ status: 'rejected', errorCode }` (when `onUploadStart` returned a stop signal), or `{ status: 'error', reason, cause? }`. See [`src/settings/_api/updateUser_v1.ts`](../../src/settings/_api/updateUser_v1.ts) for the canonical avatar usage. |
+| Bind address | `registerBindAddress({ ip, port })`, `getBindAddress() → { ip, port: string }`. `createLuckyStackServer` registers the resolved listen address at boot so framework code (e.g. `checkOrigin` building the same-origin entry) reads it from the registry instead of `SERVER_IP` / `SERVER_PORT` env vars — no more drift when consumers configure programmatically via `createLuckyStackServer({ ip, port })`. Resolution at call time: (1) `registerBindAddress(...)` value, (2) `process.env.SERVER_IP` / `SERVER_PORT` (legacy), (3) `'127.0.0.1'` / `''` fallback. |
+| Locale reloader | `registerLocaleReloader`, `getLocaleReloader`. Type: `LocaleReloader` |
+| Hooks (async) | `registerHook`, `dispatchHook`, `clearAllHooks`. Types: `HookName`, `HookHandler`, `HookResult`, `HookStopSignal`, `HookPayloads`, `DispatchResult`, `HookSessionShape`. Canonical payload types: `PreApiValidatePayload`, `PostApiValidatePayload`, `PreApiExecutePayload`, `PostApiExecutePayload`, `PreApiRespondPayload`, `PostApiRespondPayload`, `ApiResponseEnvelope`, `PreSyncFanoutPayload`, `PostSyncFanoutPayload`, `ApiErrorPayload`, `SyncErrorPayload`, `RateLimitExceededPayload`, `CorsRejectedPayload`, `CsrfMismatchPayload`, `PreSessionRefreshPayload`, `PostSessionRefreshPayload`, `OnUploadStartPayload`, `OnUploadCompletePayload`. Feature-package payloads (`Pre/PostLogin`, `Pre/PostRegister`, `Pre/PostLogout`, `Pre/PostSessionCreate`, `Pre/PostSessionDelete`, `Pre/PostEmailSend`, `Pre/PostPresenceUpdate`, socket lifecycle, etc.) augment `HookPayloads` from their owning packages — see those packages' READMEs. |
+| Hooks (sync, mutators) | `registerSyncHook`, `dispatchSyncHook`. Types: `SyncHookName`, `SyncHookHandler`, `SyncHookPayloads`, `PreErrorNormalizePayload`, `PostErrorNormalizePayload`. Sync hook handlers must be synchronous (no `async`), mutate the payload object in place, and cannot stop the flow. Use them only for hot-path mutators like error-code remapping. |
+| Session types | `BaseSessionLayout`, `SessionLocation`, `AuthProps` |
+| Socket | `setIoInstance`, `getIoInstance`, `attachSocketRedisAdapter`, `socket`, `setSocket`, `incrementResponseIndex`, `waitForSocket`. Types: `SOCKETSTATUS`, `statusContent`, `apiMessage`, `syncMessage` |
+| Auth helpers | `extractTokenFromSocket`, `extractTokenFromRequest`, `validateRequest`, `isFalsy`, `allowedOrigin`. Types: `ValidationResult` |
+| Rate limiting | `checkRateLimit`, `getRateLimitStatus`, `clearRateLimit`, `clearAllRateLimits` |
+| Validation | `validateInputByType` (resolves to `@luckystack/devkit` lazily in dev) |
+| Persistence + env | `redis`, `prisma`, `db` exports, `env` exports |
+| Boot | `writeBootUuid`, `readBootUuid`, `resolveEnvKey`, `collectSynchronizedEnvKeys`, `computeSynchronizedEnvHashes`, `hashSynchronizedValue`, `initConsolelog` |
+| Offline queue | `isOnline`, `enqueueApiRequest`, `enqueueSyncRequest`, `removeApiQueueItem`, `removeSyncQueueItem`, `removeApiQueueItemsByKey`, `flushApiQueue`, `flushSyncQueue`, `getApiQueueSize`, `getSyncQueueSize` |
+| CSRF | `getCsrfToken`, `clearCsrfToken`, `httpFetch` |
+| Cookies + paths | All exports of `./cookies`, `./httpApiUtils`, and `./paths` (`getGeneratedApiDocsPath`, `getApiMethodMapPath`, etc.) |
+| Misc | `tryCatch`, `sleep`, `getParams`, response normalizers (`normalizeErrorResponse`, `extractLanguageFromHeader`, …), service-route helpers, socket-event constants |
+
+> Note: `apiRequest` is exported from `@luckystack/core/client`, not from the server entry. The server barrel does not pull React-coupled code.
+
+## Dependencies
+
+- Runtime: `@socket.io/redis-adapter`, `dotenv`
+- Peer (canonical ranges, standardized 2026-05-07):
+  - `@prisma/client@^6.19.0`
+  - `ioredis@^5.10.0`
+  - `socket.io@^4.8.0`
+  - `socket.io-client@^4.8.0`
+  - `zod@^3.25.0`
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).

package/dist/apiTypeStubs.d.ts

@@ -0,0 +1,7 @@
+interface ApiTypeMap {
+}
+interface SyncTypeMap {
+}
+type StreamPayload = Record<string, unknown>;
+
+export type { ApiTypeMap, StreamPayload, SyncTypeMap };

package/dist/apiTypeStubs.js

@@ -0,0 +1 @@
+//# sourceMappingURL=apiTypeStubs.js.map

package/dist/apiTypeStubs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/client.d.ts

@@ -0,0 +1,236 @@
+import { StreamPayload, ApiTypeMap } from './apiTypeStubs.js';
+export { SyncTypeMap } from './apiTypeStubs.js';
+import { B as BaseSessionLayout } from './pageRouteValidation-CxZJVwZh.js';
+export { A as ApiMethodMap, a as AppConfig, b as AuthProps, D as DEFAULT_PAGE_ROUTE_RULES, H as HttpMethodLiteral, L as Logger, c as LoggerContext, d as LoggingConfig, N as Notifier, e as NotifyInput, f as NotifyParam, P as PagePathValidationResult, g as PageRouteRules, h as ProjectConfig, R as RateLimitingConfig, S as SOCKETSTATUS, i as SessionConfig, j as SessionLocation, k as buildApiResponseEventName, l as buildApiStreamEventName, m as buildGetJoinedRoomsResponseEventName, n as buildJoinRoomResponseEventName, o as buildLeaveRoomResponseEventName, p as buildSyncProgressEventName, q as buildSyncResponseEventName, r as clearCsrfToken, s as enqueueApiRequest, t as enqueueSyncRequest, u as flushApiQueue, v as flushSyncQueue, w as getApiQueueSize, x as getCsrfToken, y as getLogger, z as getNotifier, C as getProjectConfig, E as getRegisteredApiMethod, F as getSyncQueueSize, G as httpFetch, I as incrementResponseIndex, J as isApiMethodMapRegistered, K as isOnline, M as isProjectConfigRegistered, O as normalizeErrorResponseCore, Q as notify, T as parseServiceRouteName, U as registerApiMethodMap, V as registerLogger, W as registerNotifier, X as registerProjectConfig, Y as removeApiQueueItem, Z as removeApiQueueItemsByKey, _ as removeSyncQueueItem, $ as setSocket, a0 as sleep, a1 as socket, a2 as socketEventNames, a3 as statusContent, a4 as tryCatch, a5 as validatePagePath, a6 as waitForSocket } from './pageRouteValidation-CxZJVwZh.js';
+import * as react from 'react';
+import { ReactNode, Dispatch, SetStateAction } from 'react';
+import 'socket.io-client';
+
+type ApiStreamEvent<T extends StreamPayload = StreamPayload> = T;
+type DataRequired<T> = Record<string, never> extends T ? false : true;
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends ((arg: infer I) => void) ? I : never;
+type ApiRouteRecord = UnionToIntersection<{
+    [P in keyof ApiTypeMap]: {
+        [N in keyof ApiTypeMap[P] as P extends 'root' ? `system/${Extract<N, string>}` : `${Extract<P, string>}/${Extract<N, string>}`]: ApiTypeMap[P][N];
+    };
+}[keyof ApiTypeMap]>;
+type ApiFullName = Extract<keyof ApiRouteRecord, string>;
+type VersionsForFullName<F extends ApiFullName> = keyof ApiRouteRecord[F] & string;
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type InputForFullName<F extends ApiFullName, V extends VersionsForFullName<F>> = ApiRouteRecord[F][V] extends {
+    input: infer I;
+} ? I : never;
+type OutputForFullName<F extends ApiFullName, V extends VersionsForFullName<F>> = ApiRouteRecord[F][V] extends {
+    output: infer O;
+} ? O : never;
+type StreamForFullName<F extends ApiFullName, V extends VersionsForFullName<F>> = ApiRouteRecord[F][V] extends {
+    stream: infer S;
+} ? S : never;
+type ApiStreamCallbackForFullName<F extends ApiFullName, V extends VersionsForFullName<F>> = [
+    StreamForFullName<F, V>
+] extends [never] ? never : (event: ApiStreamEvent<Prettify<StreamForFullName<F, V> extends StreamPayload ? StreamForFullName<F, V> : StreamPayload>>) => void;
+type ApiParamsForFullName<F extends ApiFullName, V extends VersionsForFullName<F>> = DataRequired<InputForFullName<F, V>> extends true ? {
+    name: F;
+    version: V;
+    data: Prettify<InputForFullName<F, V>>;
+    abortable?: boolean;
+    disableErrorMessage?: boolean;
+    onStream?: ApiStreamCallbackForFullName<F, V>;
+    signal?: AbortSignal;
+} : {
+    name: F;
+    version: V;
+    data?: Prettify<InputForFullName<F, V>>;
+    abortable?: boolean;
+    disableErrorMessage?: boolean;
+    onStream?: ApiStreamCallbackForFullName<F, V>;
+    signal?: AbortSignal;
+};
+/**
+ * Type-safe API request function.
+ *
+ * @example
+ * ```typescript
+ * // Full name usage - includes page in the name
+ * const result = await apiRequest({ name: 'examples/publicApi', version: 'v1', data: { message: 'hello' } });
+ * // result is typed correctly for publicApi
+ *
+ * // Global APIs use service-first naming
+ * await apiRequest({ name: 'system/session', version: 'v1' });
+ * ```
+ */
+declare function apiRequest<F extends ApiFullName, V extends VersionsForFullName<F>>(params: ApiParamsForFullName<F, V>): Promise<Prettify<OutputForFullName<F, V>>>;
+
+type LocalesMap = Record<string, unknown>;
+type LanguageSource = () => string | null | undefined;
+declare const registerLocales: (locales: LocalesMap) => void;
+declare const getRegisteredLocales: () => LocalesMap;
+declare const getDefaultLocale: () => string;
+declare const registerLanguageSource: (fn: LanguageSource) => void;
+declare const getActiveLanguage: () => string;
+declare const getLocaleByCode: (code: string) => unknown;
+
+interface MiddlewareInput {
+    location: string;
+    searchParams: Record<string, string>;
+    session: BaseSessionLayout | null;
+}
+type MiddlewareResult = {
+    success: true;
+    redirect?: undefined;
+} | {
+    success: false;
+    redirect: string;
+} | undefined;
+type MiddlewareHandler = (input: MiddlewareInput) => MiddlewareResult | Promise<MiddlewareResult>;
+declare const registerMiddlewareHandler: (handler: MiddlewareHandler) => void;
+declare const getMiddlewareHandler: () => MiddlewareHandler;
+type PageMiddleware<TSession extends BaseSessionLayout = BaseSessionLayout> = (input: {
+    location: string;
+    searchParams: Record<string, string>;
+    session: TSession | null;
+}) => MiddlewareResult | Promise<MiddlewareResult>;
+declare const registerPageMiddleware: (path: string, middleware: PageMiddleware) => void;
+declare const getPageMiddleware: (path: string) => PageMiddleware | undefined;
+declare const hasPageMiddleware: (path: string) => boolean;
+
+interface ClientHookPayloadMap {
+    preLogin: {
+        candidateSession: BaseSessionLayout;
+    };
+    postLogin: {
+        session: BaseSessionLayout;
+    };
+    postLogout: {
+        previousSession: BaseSessionLayout;
+    };
+}
+type ClientHookName = keyof ClientHookPayloadMap;
+interface ClientHookStopSignal {
+    stop: true;
+    errorCode: string;
+}
+type ClientHookResult = void | undefined | ClientHookStopSignal;
+type ClientDispatchResult = {
+    stopped: false;
+} | {
+    stopped: true;
+    signal: ClientHookStopSignal;
+};
+type ClientHookHandler<N extends ClientHookName> = (payload: ClientHookPayloadMap[N]) => ClientHookResult | Promise<ClientHookResult>;
+/**
+ * Subscribe to a client-side lifecycle hook. Returns an unsubscribe function
+ * — call it to remove the handler (e.g. inside a React effect cleanup).
+ *
+ * Multiple handlers can be registered for the same hook; they all fire on
+ * each dispatch. A handler that throws (sync) or rejects (async) is logged
+ * to `console.error` and does not affect other handlers.
+ */
+declare function registerClientHook<N extends ClientHookName>(name: N, handler: ClientHookHandler<N>): () => void;
+/**
+ * Fire a client-side hook (fire-and-forget). Framework-internal — consumers
+ * should not call this directly. Used for `post*` hooks where any stop-signal
+ * returned by a handler is intentionally ignored: a `postLogin` listener that
+ * tried to "stop" the framework would be too late — the transition already
+ * happened. Use `dispatchVetoableClientHook` for `pre*` hooks where the
+ * caller actually awaits the veto decision.
+ */
+declare function dispatchClientHook<N extends ClientHookName>(name: N, payload: ClientHookPayloadMap[N]): void;
+/**
+ * Awaits every registered handler for a `pre*` client hook. If any handler
+ * returns a `ClientHookStopSignal`, dispatch short-circuits and returns
+ * `{ stopped: true, signal }`; callers must respect the veto (skip the
+ * pending action). Handlers that throw or reject are logged but treated as
+ * `undefined` — a buggy handler must not silently block the user flow.
+ *
+ * Mirrors `dispatchHook` from `@luckystack/core` so consumer/framework code
+ * can use the same stop-signal pattern on both sides of the wire.
+ */
+declare function dispatchVetoableClientHook<N extends ClientHookName>(name: N, payload: ClientHookPayloadMap[N]): Promise<ClientDispatchResult>;
+
+interface SessionContextValue<TSession extends BaseSessionLayout = BaseSessionLayout> {
+    session: TSession | null;
+    sessionLoaded: boolean;
+}
+declare const SessionContext: react.Context<SessionContextValue<BaseSessionLayout>>;
+declare function useSession<TSession extends BaseSessionLayout = BaseSessionLayout>(): SessionContextValue<TSession>;
+declare const setLatestSession: (session: BaseSessionLayout | null) => void;
+declare const getCurrentSession: <TSession extends BaseSessionLayout = BaseSessionLayout>() => TSession | null;
+/**
+ * Vetoable entry point for committing a null → session transition (i.e. a
+ * fresh login or a page-load session restore). Dispatches the `preLogin`
+ * client hook to every registered handler in parallel; if any returns a
+ * stop signal, the transition is aborted and `{ committed: false, signal }`
+ * is returned. Otherwise, `setLatestSession(session)` runs synchronously
+ * (which fires `postLogin`) and `{ committed: true }` comes back.
+ *
+ * Consumer's `SessionProvider` should `await` this for non-null session
+ * commits and roll local React state back to `null` when a veto comes
+ * through, so the UI doesn't render a half-logged-in state.
+ */
+type ProposeLoginResult = {
+    stopped: false;
+    committed: true;
+} | {
+    stopped: true;
+    signal: ClientHookStopSignal;
+    committed: false;
+};
+declare const proposeLogin: (session: BaseSessionLayout) => Promise<ProposeLoginResult>;
+
+type AvatarStatus = 'avatar' | 'fallback';
+interface AvatarContextType {
+    avatarStatuses: Record<string, AvatarStatus>;
+    setAvatarStatus: (key: string, status: AvatarStatus) => void;
+}
+declare const AvatarProvider: ({ children }: {
+    children: ReactNode;
+}) => react.JSX.Element;
+declare function useAvatarContext(): AvatarContextType;
+
+type Theme = 'light' | 'dark';
+declare const useTheme: () => {
+    theme: Theme;
+    setTheme: (next: Theme) => void;
+};
+
+type TranslationRecord = Record<string, unknown>;
+declare function TranslationProvider({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function useTranslation(): TranslationRecord;
+declare function useUpdateLanguage(): Dispatch<SetStateAction<string>>;
+interface TranslateParam {
+    key: string;
+    value: string | number | boolean;
+}
+declare function translate({ translationList, key, params }: {
+    translationList: TranslationRecord;
+    key: unknown;
+    params?: TranslateParam[];
+}): string;
+declare const useTranslator: () => ({ key, params }: {
+    key: string;
+    params?: TranslateParam[];
+}) => string;
+
+interface NotifyInput {
+    key: string;
+    params?: TranslateParam[];
+}
+declare const notify: {
+    success: (input: NotifyInput) => void;
+    error: (input: NotifyInput) => void;
+    info: (input: NotifyInput) => void;
+    warning: (input: NotifyInput) => void;
+};
+
+declare function Middleware({ children }: {
+    children: ReactNode;
+}): react.JSX.Element | null;
+
+declare function useRouter(): (path: string) => Promise<void>;
+
+export { type ApiStreamEvent, ApiTypeMap, AvatarProvider, type AvatarStatus, BaseSessionLayout, type ClientDispatchResult, type ClientHookHandler, type ClientHookName, type ClientHookPayloadMap, type ClientHookResult, type ClientHookStopSignal, type LanguageSource, type LocalesMap, Middleware, type MiddlewareHandler, type MiddlewareInput, type MiddlewareResult, type PageMiddleware, SessionContext, type SessionContextValue, StreamPayload, type Theme, type TranslateParam, TranslationProvider, type TranslationRecord, apiRequest, dispatchClientHook, dispatchVetoableClientHook, getActiveLanguage, getCurrentSession, getDefaultLocale, getLocaleByCode, getMiddlewareHandler, getPageMiddleware, getRegisteredLocales, hasPageMiddleware, notify as i18nNotify, proposeLogin, registerClientHook, registerLanguageSource, registerLocales, registerMiddlewareHandler, registerPageMiddleware, setLatestSession, translate, useAvatarContext, useRouter, useSession, useTheme, useTranslation, useTranslator, useUpdateLanguage };