@forinda/kickjs 6.5.0 → 6.5.1

package/dist/views-DsfBT1fR.d.mts

@@ -0,0 +1,659 @@
+
+import "./index-M6TF75MS.mjs";
+import { f as DepValue, o as ContextDecorator, s as ContextDecoratorSpec, v as MetaValue } from "./app-module-DtoySG6l.mjs";
+import { T as RequestContext, f as HttpRuntime, k as AdapterFactory, m as RouteEntry } from "./adapter-CbMq-NBf.mjs";
+import "./application-zlzYGgKD.mjs";
+import "./bootstrap-Nzgi7K2d.mjs";
+import "./cors-BuDU9CpA.mjs";
+import "./csrf-vR23CJas.mjs";
+import "./error-handler-Cr6Yt9as.mjs";
+import "./helmet-CFQUTVig.mjs";
+import "./rate-limit-Dme747JJ.mjs";
+import "./request-id-CVzJ1uHD.mjs";
+import "./request-logger-BU4ulKLp.mjs";
+import "./session-z9iewOXA.mjs";
+import "./spa-DsRUrm69.mjs";
+import "./upload-XVTyQcNN.mjs";
+import "./validate-DMYpUnrf.mjs";
+import "./kv-stores-CHowq8VP.mjs";
+import { t as BuildRoutesOptions } from "./router-builder-CMGhEBU2.mjs";
+import { Express, NextFunction, Request, Response, Router } from "express";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/core/disposables.d.ts
+/**
+ * Registry for framework-owned resources that hold timers or other handles
+ * outside the adapter/plugin lifecycle — e.g. the in-memory session and
+ * rate-limit stores' cleanup intervals. `Application.shutdown()` drains it so
+ * startup and shutdown stay symmetric even for resources created lazily by
+ * middleware factories.
+ *
+ * Intervals are `.unref()`'d so they never wedge process exit — this registry
+ * exists for IN-PROCESS teardown (test suites, HMR, multi-app hosts) where
+ * each un-disposed store would otherwise leak a live interval + backing Map
+ * per app instance.
+ */
+type Disposable = () => void | Promise<void>;
+/** Register a cleanup callback. Returns an unregister function. */
+declare function registerDisposable(fn: Disposable): () => void;
+/** Run and clear all registered disposables. Errors are swallowed per-entry. */
+declare function disposeAll(): Promise<void>;
+//#endregion
+//#region src/core/kick-error.d.ts
+/**
+ * Structured framework error with code, cause, and actionable fix hint.
+ *
+ * The goal is "the developer who hits this knows what to do next." A
+ * cryptic `Error('No binding found for: UserService')` becomes a
+ * multi-line explanation pointing at the likely cause, the exact code
+ * change to apply, and a docs link.
+ *
+ * `.message` carries the full multi-line plain-text body so Node's
+ * default `Error.toString()` and unhandled-exception printing still
+ * surface the helpful version. Call {@link formatKickError} to render a
+ * colorized version for terminals.
+ *
+ * Per-error factories live in `kick-errors.ts` — those are the public
+ * entry points framework code uses. `KickError` is exported so adopters
+ * can build their own structured errors using the same shape.
+ */
+interface KickErrorInit {
+  /** Short stable identifier (e.g. `KICK001`, `NO_PROVIDER`). */
+  code: string;
+  /** One-line headline. */
+  summary: string;
+  /** Multi-line explanation of why this happened. */
+  cause?: string;
+  /** Multi-line actionable fix — show exact code if possible. */
+  fix?: string;
+  /** Absolute URL to the docs page that covers this error. */
+  docsUrl?: string;
+  /** Arbitrary structured fields for log consumers / debug tooling. */
+  context?: Record<string, unknown>;
+}
+declare class KickError extends Error {
+  readonly code: string;
+  readonly summary: string;
+  readonly cause?: string;
+  readonly fix?: string;
+  readonly docsUrl?: string;
+  readonly context?: Record<string, unknown>;
+  constructor(init: KickErrorInit);
+}
+interface FormatKickErrorOptions {
+  /**
+   * Render ANSI colour codes. Defaults to TTY detection (`NO_COLOR` /
+   * `FORCE_COLOR` env vars honoured). Pass `false` for log files,
+   * structured loggers, or HTTP response bodies.
+   */
+  color?: boolean;
+}
+/**
+ * Render a {@link KickErrorInit} (or {@link KickError} instance) into a
+ * multi-line human-readable string. Identical layout regardless of
+ * colour — the colour flag only toggles ANSI codes.
+ */
+declare function formatKickError(err: KickErrorInit | KickError, options?: FormatKickErrorOptions): string;
+//#endregion
+//#region src/core/circuit-breaker.d.ts
+/**
+ * Circuit Breaker pattern for external service calls.
+ *
+ * Protects your application from cascading failures when downstream
+ * services are unhealthy by short-circuiting requests after a
+ * configurable failure threshold.
+ *
+ * @example
+ * ```ts
+ * const breaker = new CircuitBreaker('payment-api', {
+ *   failureThreshold: 5,
+ *   resetTimeout: 30_000,
+ * })
+ *
+ * const result = await breaker.execute(() => fetch('https://payment.example.com/charge'))
+ * ```
+ */
+type CircuitBreakerState = 'closed' | 'open' | 'half_open';
+interface CircuitBreakerOptions {
+  /** Number of consecutive failures before the circuit opens. */
+  failureThreshold: number;
+  /** Milliseconds to wait before transitioning from OPEN to HALF_OPEN. */
+  resetTimeout: number;
+  /** Max requests allowed in HALF_OPEN state before deciding (default 1). */
+  halfOpenMax?: number;
+}
+interface CircuitBreakerStats {
+  failures: number;
+  successes: number;
+  state: CircuitBreakerState;
+  lastFailure?: Date;
+}
+/**
+ * Error thrown when the circuit is open and calls are being rejected.
+ */
+declare class CircuitOpenError extends Error {
+  readonly breakerName: string;
+  constructor(breakerName: string);
+}
+declare class CircuitBreaker {
+  readonly name: string;
+  private state;
+  private failures;
+  private successes;
+  private halfOpenAttempts;
+  private lastFailure?;
+  private openedAt?;
+  private readonly failureThreshold;
+  private readonly resetTimeout;
+  private readonly halfOpenMax;
+  constructor(name: string, options: CircuitBreakerOptions);
+  /**
+   * Execute an async function through the circuit breaker.
+   * Throws `CircuitOpenError` if the circuit is open.
+   */
+  execute<T>(fn: () => Promise<T>): Promise<T>;
+  /** Returns the current circuit state. */
+  getState(): CircuitBreakerState;
+  /** Returns current statistics. */
+  getStats(): CircuitBreakerStats;
+  /** Manually reset the circuit breaker to CLOSED state. */
+  reset(): void;
+  private onSuccess;
+  private onFailure;
+  private maybeTransitionToHalfOpen;
+}
+//#endregion
+//#region src/core/context-errors.d.ts
+/**
+ * Errors thrown by the Context Contributor pipeline.
+ *
+ * `MissingContributorError`, `ContributorCycleError`, and
+ * `DuplicateContributorError` are startup-time errors raised during
+ * pipeline build (topo-sort + validation), not per-request — a
+ * misconfigured app fails to boot rather than fails a request. Per the
+ * locked design in `architecture.md` §20.4, the pipeline is validated
+ * once when each route is mounted and the resolved order is cached on
+ * the route.
+ *
+ * `MissingContextValueError` is the one request-time error here: it is
+ * raised by `ctx.require(key)` when a value a handler declared it needs
+ * is absent. See its doc comment for why that case can't be caught at
+ * startup today.
+ */
+/**
+ * A contributor declared `dependsOn: ['<key>']` but no other contributor
+ * (at any precedence level) produces that key for the same route.
+ *
+ * @example
+ * ```text
+ * MissingContributorError: Missing context contributor 'tenant' required by 'project' on route GET /projects/:id
+ *     declared at src/contributors/load-project.ts:42:18
+ * ```
+ */
+declare class MissingContributorError extends Error {
+  readonly key: string;
+  readonly dependent: string;
+  readonly route?: string;
+  readonly dependentDefinedAt?: string;
+  constructor(key: string, dependent: string, route?: string, dependentDefinedAt?: string);
+}
+/**
+ * `ctx.require(key)` found no value under `key` in the per-request
+ * metadata store.
+ *
+ * Thrown at request time, by design. `ctx.get(key)` returns
+ * `T | undefined` for every key, so the usual workaround is a
+ * non-null assertion — `ctx.get('tenant')!` — which compiles whether or
+ * not the route actually carries the contributor that produces it. On
+ * an authorization value that is the worst possible thing to leave
+ * untypeable: dropping the decorator produces no diagnostic anywhere,
+ * and the handler reads `undefined` as though it were a real value.
+ *
+ * `ctx.require()` converts that silent hole into a loud, named failure
+ * that points at the missing contributor.
+ *
+ * A handler typed with a generated route type (`Ctx<KickRoutes…>`) also
+ * gets compile-time narrowing, so a dropped decorator fails `tsc` rather
+ * than reaching this error at all. This error remains the backstop for
+ * routes typegen couldn't prove (module/adapter/bootstrap registrations),
+ * handlers typed as plain `RequestContext`, and contributors that ran but
+ * resolved to `undefined`. See `architecture.md` §20.14.
+ *
+ * @example
+ * ```text
+ * MissingContextValueError: No context value for 'tenantPerm' on GET /projects/:id
+ *     Nothing wrote this key before the handler ran. Either the contributor
+ *     that produces it isn't applied to this route, or it ran and resolved
+ *     to undefined (check `optional: true` contributors).
+ * ```
+ */
+declare class MissingContextValueError extends Error {
+  readonly key: string;
+  readonly route?: string;
+  constructor(key: string, route?: string);
+}
+/**
+ * Topo-sort detected a cycle in `dependsOn` declarations. The `cycle` field
+ * lists the keys in the order they form the loop, with the first key
+ * repeated at the end so the path reads naturally.
+ *
+ * @example
+ * ```text
+ * ContributorCycleError: Cycle in context contributors on route GET /projects/:id: tenant → project → tenant
+ * ```
+ */
+declare class ContributorCycleError extends Error {
+  readonly cycle: readonly string[];
+  readonly route?: string;
+  constructor(cycle: readonly string[], route?: string);
+}
+/**
+ * Two contributors at the same precedence level both produce the same key
+ * for the same route. Precedence resolution (method > class > module >
+ * adapter > global, per architecture.md §20.4) silently drops
+ * lower-precedence duplicates; this error fires only when ties occur
+ * within a single level — e.g., two method-level decorators declaring
+ * `key: 'tenant'`.
+ *
+ * `sources` is best-effort identifying labels for each conflicting
+ * registration (typically the decorator's call site or registering
+ * module/adapter name).
+ *
+ * @example
+ * ```text
+ * DuplicateContributorError: Duplicate context contributor for key 'tenant' at the same precedence level. Sources: LoadTenantFromHeader, LoadTenantFromSubdomain
+ * ```
+ */
+declare class DuplicateContributorError extends Error {
+  readonly key: string;
+  readonly sources: readonly string[];
+  constructor(key: string, sources: readonly string[]);
+}
+//#endregion
+//#region src/core/mount-sort.d.ts
+/**
+ * Topological sort for plugins and adapters with `dependsOn` declarations.
+ *
+ * Mirrors the algorithm used by the Context Contributor pipeline
+ * (`contributor-pipeline.ts:topoSort`) but operates on a name-keyed
+ * `MountSortItem` shape rather than a `ContributorRegistration`. Kept
+ * standalone instead of factored generic so that:
+ *
+ * 1. The contributor pipeline doesn't need refactoring (risk reduction).
+ * 2. The error classes can carry plugin/adapter-specific diagnostic
+ *    fields (`kind`, `dependent`) without bending the contributor types.
+ */
+/**
+ * A plugin or adapter that participates in dependency-ordered mounting.
+ * Both `KickPlugin` and `AppAdapter` satisfy this shape via their `name`
+ * and `dependsOn` fields.
+ */
+interface MountSortItem {
+  /** Unique mount name within the plugin/adapter set being sorted. */
+  name: string;
+  /**
+   * Other plugin/adapter names that must mount before this one. Cycles
+   * and missing names fail at boot — same fail-fast contract as the
+   * Context Contributor pipeline (architecture.md §20.4).
+   */
+  dependsOn?: readonly string[];
+}
+/** What kind of mount set the sort is operating on — surfaces in error messages. */
+type MountKind = 'plugin' | 'adapter';
+/**
+ * Two items in the same mount set declared the same `name`. Plugin/adapter
+ * names must be unique so `dependsOn` references resolve unambiguously.
+ */
+declare class DuplicateMountNameError extends Error {
+  readonly kind: MountKind;
+  readonly mountName: string;
+  constructor(kind: MountKind, mountName: string);
+}
+/**
+ * A `dependsOn` entry references a plugin/adapter that isn't in the
+ * current set. The dependency might not be installed, might be misspelled,
+ * or might live in a different mount set (plugin referencing an adapter,
+ * or vice versa — they sort independently).
+ */
+declare class MissingMountDepError extends Error {
+  readonly kind: MountKind;
+  readonly missing: string;
+  readonly dependent: string;
+  constructor(kind: MountKind, missing: string, dependent: string);
+}
+/**
+ * The `dependsOn` declarations form a cycle. Boot fails so the cycle
+ * can't poison live traffic. The `cycle` field reports one path through
+ * the offending nodes for diagnostics — formatted `A → B → C → A`.
+ */
+declare class MountCycleError extends Error {
+  readonly kind: MountKind;
+  readonly cycle: readonly string[];
+  constructor(kind: MountKind, cycle: readonly string[]);
+}
+/**
+ * Topologically sort `items` so every item with `dependsOn: ['X']` mounts
+ * after `X`. Items without `dependsOn` keep their input order via Kahn's
+ * algorithm with a FIFO queue seeded in input order — preserves the
+ * historical "plugins/adapters mount in declaration order" behaviour for
+ * any set that doesn't use `dependsOn`.
+ *
+ * @param items - mountable items, e.g. plugins or adapters
+ * @param kind - 'plugin' | 'adapter', used in error messages
+ * @returns a new array in valid mount order
+ * @throws {DuplicateMountNameError} two items share a name
+ * @throws {MissingMountDepError} a `dependsOn` references an unknown name
+ * @throws {MountCycleError} the dep graph contains a cycle
+ */
+declare function mountSort<T extends MountSortItem>(items: readonly T[], kind: MountKind): T[];
+//#endregion
+//#region src/core/asset-keys.d.ts
+type AssetKeyStrategy = 'auto' | 'strip' | 'with-extension';
+interface AssetKeyPair {
+  /** Source-relative path the file was discovered at. */
+  rel: string;
+  /** Final logical key for the manifest, including the namespace prefix. */
+  key: string;
+}
+interface GroupAssetKeysOptions {
+  /**
+   * Strategy applied to this namespace. Default `'auto'`.
+   *
+   * Adopters override per-namespace via `assetMap.<ns>.keys` in
+   * kick.config.ts when they want uniform behaviour (e.g. always
+   * include the extension regardless of collisions).
+   */
+  strategy?: AssetKeyStrategy;
+}
+interface GroupAssetKeysResult {
+  pairs: AssetKeyPair[];
+  /**
+   * Number of collision groups resolved by keeping extensions.
+   * Surfaces as an informational log ("auto-resolved N collisions")
+   * so adopters know whether they're relying on auto-mode or not.
+   * Always 0 for `'strip'` (overwrites) and `'with-extension'`
+   * (extensions always preserved, no collision possible).
+   */
+  collisionGroupsResolved: number;
+}
+/**
+ * Compute final manifest keys for a namespace's discovered paths,
+ * given the chosen strategy. Pure function — no fs / config / globals
+ * involved.
+ *
+ * @param namespace assetMap key — e.g. `'mails'`, `'pages'`.
+ * @param paths source-relative file paths (POSIX separators) discovered
+ *              under the namespace's `src` directory.
+ * @param opts grouping options.
+ */
+declare function groupAssetKeys(namespace: string, paths: readonly string[], opts?: GroupAssetKeysOptions): GroupAssetKeysResult;
+/** Strip the final extension from a path. `'mails/welcome.ejs'` → `'mails/welcome'`. */
+declare function stripExt(path: string): string;
+//#endregion
+//#region src/http/cluster.d.ts
+interface ClusterOptions {
+  /** Number of worker processes (default: os.cpus().length) */
+  workers?: number;
+  /** Delay before forcefully killing a worker during shutdown (ms), default: 5000 */
+  gracefulShutdownTimeout?: number;
+  /** Delay between worker restarts (ms), default: 1000 */
+  restartDelay?: number;
+  /** Max failures in restartWindow before refusing to restart, default: 5 */
+  maxFailures?: number;
+  /** Time window for counting failures (ms), default: 30000 */
+  restartWindow?: number;
+}
+/** Returns true if the current process is the cluster primary */
+declare function isClusterPrimary(): boolean;
+//#endregion
+//#region src/http/define-http-context-decorator.d.ts
+/**
+ * Curried form returned by {@link DefineHttpContextDecoratorFn.withParams}.
+ * Spell only the per-call params shape `P`; `K` and `D` are inferred
+ * from the spec, and `Ctx` is locked to `RequestContext`.
+ */
+interface DefineHttpContextDecoratorWithParams<P extends Record<string, unknown>> {
+  <K extends string, D extends Record<string, DepValue> = Record<string, never>>(spec: ContextDecoratorSpec<K, D, P, RequestContext>): ContextDecorator<K, D, P, RequestContext>;
+}
+/**
+ * Public shape of {@link defineHttpContextDecorator} — the positional
+ * call signature plus the curried `.withParams<P>()` helper that fixes
+ * partial-inference for the parameterised case.
+ */
+interface DefineHttpContextDecoratorFn {
+  <K extends string, D extends Record<string, DepValue> = Record<string, never>, P extends Record<string, unknown> = Record<string, never>>(spec: ContextDecoratorSpec<K, D, P, RequestContext>): ContextDecorator<K, D, P, RequestContext>;
+  /**
+   * Curried entry point. Spell only `P`; `K` and `D` infer from the
+   * spec. `Ctx` is locked to `RequestContext`.
+   *
+   * ```ts
+   * const LoadTenant = defineHttpContextDecorator.withParams<{
+   *   source: 'header' | 'subdomain'
+   * }>()({
+   *   key: 'tenant',
+   *   deps: { repo: TENANT_REPO },           // D inferred
+   *   paramDefaults: { source: 'header' },
+   *   resolve: (ctx, { repo }, params) => repo.findFor(ctx, params),
+   * })
+   * ```
+   */
+  withParams<P extends Record<string, unknown>>(): DefineHttpContextDecoratorWithParams<P>;
+}
+declare const defineHttpContextDecorator: DefineHttpContextDecoratorFn;
+//#endregion
+//#region src/http/runtimes/express.d.ts
+/**
+ * Materialize a controller's {@link RouteEntry}[] onto a fresh `express.Router`.
+ * Reproduces the legacy handler ordering precisely: validation → upload →
+ * `(ctx, next)` middleware → contributor runner → terminal handler. Each step
+ * constructs its own `RequestContext` over the same `req`/`res` — request-scoped
+ * state lives in the AsyncLocalStorage store, not on the ctx instance, so the
+ * per-step instances share state exactly as before.
+ */
+declare function materializeRouter(entries: RouteEntry[]): Router;
+/**
+ * Build an Express Router from a controller class decorated with @Get, @Post,
+ * etc. The public, back-compatible entry point: a thin shim over
+ * {@link buildRouteTable} + {@link materializeRouter}. Returns an
+ * `express.Router` exactly as before — modules pass it to `app.use(path, router)`.
+ *
+ * @see buildRouteTable for the engine-neutral route-table form.
+ */
+declare function buildRoutes(controllerClass: any, options?: BuildRoutesOptions): Router;
+/**
+ * The default HTTP runtime. Express stays a peer dependency of `@forinda/kickjs`;
+ * apps that pass no `runtime` get this and behave exactly as before.
+ */
+declare function expressRuntime(): HttpRuntime<Express>;
+//#endregion
+//#region src/http/request-store.d.ts
+/** Per-request storage for REQUEST-scoped DI and request context propagation */
+interface RequestStore {
+  /** Unique request identifier */
+  requestId: string;
+  /**
+   * Per-request singleton cache for REQUEST-scoped services. Keys are
+   * heterogeneous (class constructors, `InjectionToken` objects, raw
+   * strings), so the map type stays `Map<any, any>`.
+   */
+  instances: Map<any, any>;
+  /**
+   * Per-request key/value bag. Canonical backing store for
+   * `RequestContext.set/get` and the Context Contributor pipeline (#107)
+   * since Phase 3. Anything written here is visible to every concrete
+   * execution context constructed for the same request, regardless of
+   * which middleware/contributor wrote it.
+   *
+   * Keys are constrained to `string` per the locked decision in
+   * `architecture.md` §20.12 (#4); the value type is `unknown` because
+   * the concrete shape at each key is determined by the consumer's
+   * `ContextMeta` augmentation, not by the store itself.
+   *
+   * Prefer the {@link getRequestValue} helper over reaching into this
+   * map directly — it threads the augmented `ContextMeta` shape through
+   * `MetaValue<K>` so consumers get typed reads without an `as` cast.
+   * Writes should flow through `ctx.set(key, value)` or a Context
+   * Contributor's return value — see the `setRequestValue` note below
+   * for why this package intentionally does NOT ship a service-level
+   * write helper.
+   */
+  values: Map<string, unknown>;
+  /** Set once {@link disposeRequestStore} has run — guards double-dispose. */
+  disposed?: boolean;
+}
+/** AsyncLocalStorage instance shared across the framework */
+declare const requestStore: AsyncLocalStorage<RequestStore>;
+/**
+ * Get the current request store. Throws if called outside a request context.
+ * Used by the Container to resolve REQUEST-scoped dependencies.
+ */
+declare function getRequestStore(): RequestStore;
+/**
+ * Read a per-request `ContextMeta`-keyed value from outside a controller
+ * (services, repositories, anywhere with no `ctx` reference). Returns
+ * the augmented type for the key — `MetaValue<K>` — so consumers get the
+ * same static safety as `ctx.get(key)` without holding the context.
+ *
+ * Returns `undefined` outside an active request frame (background jobs,
+ * startup code, tests without `requestScopeMiddleware()`) — the helper
+ * is intentionally null-tolerant so calling it from a service that
+ * runs in both request and non-request paths doesn't throw.
+ *
+ * @example
+ * ```ts
+ * declare module '@forinda/kickjs' {
+ *   interface ContextMeta { tenant: { id: string; name: string } }
+ * }
+ *
+ * @Service()
+ * class AuditService {
+ *   log(action: string) {
+ *     const tenant = getRequestValue('tenant')  // typed: { id; name } | undefined
+ *     db.audit.insert({ action, tenantId: tenant?.id })
+ *   }
+ * }
+ * ```
+ */
+declare function getRequestValue<K extends string>(key: K): MetaValue<K> | undefined;
+//#endregion
+//#region src/http/middleware/request-scope.d.ts
+/**
+ * Wraps each request in an AsyncLocalStorage context.
+ * Enables REQUEST-scoped DI and automatic requestId propagation to logs.
+ *
+ * Should be mounted early in the middleware pipeline (before route handlers).
+ * `Application` mounts this automatically unless `contextStore: 'manual'` is set
+ * or the user already includes one in their middleware list.
+ */
+declare function requestScopeMiddleware(): (req: Request, res: Response, next: NextFunction) => void;
+//#endregion
+//#region src/http/middleware/trace-context.d.ts
+/**
+ * W3C Trace Context header name.
+ * @see https://www.w3.org/TR/trace-context/#traceparent-header
+ */
+declare const TRACEPARENT_HEADER = "traceparent";
+interface TraceContextOptions {
+  /**
+   * When true, respond with a `traceresponse` header containing the trace ID.
+   * Useful for debugging. Default: false.
+   */
+  propagateResponse?: boolean;
+}
+/**
+ * Parsed W3C trace context fields.
+ */
+interface TraceContext {
+  /** W3C traceparent version (usually '00') */
+  version: string;
+  /** 32-hex-char distributed trace ID */
+  traceId: string;
+  /** 16-hex-char parent span ID */
+  parentSpanId: string;
+  /** 2-hex-char trace flags */
+  flags: string;
+}
+/**
+ * Parse a W3C traceparent header value.
+ * Returns null if the format is invalid.
+ */
+declare function parseTraceparent(header: string): TraceContext | null;
+/**
+ * Middleware that extracts W3C `traceparent` header and stores trace context
+ * in the request's AsyncLocalStorage store.
+ *
+ * If no valid `traceparent` header is present, a new traceId is generated
+ * so that every request always has a trace ID available for correlation.
+ *
+ * Must be mounted **after** `requestScopeMiddleware()` (which creates the store).
+ *
+ * @example
+ * ```ts
+ * bootstrap({
+ *   middleware: [
+ *     requestScopeMiddleware(),
+ *     traceContext(),          // extracts or generates traceId
+ *     requestLogger(),
+ *     express.json(),
+ *   ],
+ * })
+ * ```
+ */
+declare function traceContext(options?: TraceContextOptions): (req: Request, res: Response, next: NextFunction) => void;
+//#endregion
+//#region src/http/middleware/views.d.ts
+interface ViewAdapterOptions {
+  /**
+   * Template engine — pass the engine module or a render function.
+   * Supported engines: ejs, pug, handlebars, nunjucks, or any
+   * Express-compatible engine with a __express property.
+   *
+   * @example
+   * ```ts
+   * import ejs from 'ejs'
+   * ViewAdapter({ engine: ejs, ext: 'ejs' })
+   *
+   * import pug from 'pug'
+   * ViewAdapter({ engine: pug, ext: 'pug' })
+   * ```
+   */
+  engine: any;
+  /** File extension for templates (e.g., 'ejs', 'pug', 'hbs') */
+  ext: string;
+  /** Directory containing template files (default: 'src/views') */
+  viewsDir?: string;
+  /** Default layout template (optional — depends on engine) */
+  layout?: string;
+}
+/**
+ * View/template adapter — pluggable template engine support for KickJS.
+ *
+ * Registers an Express view engine and sets the views directory.
+ * Use `ctx.render()` in controllers to render templates.
+ *
+ * Migrated to the `defineAdapter()` factory in v4 — call without `new`.
+ * The pre-v4 `new ViewAdapter({...})` form is gone; see
+ * `docs/guide/migration-v3-to-v4.md` for the rename.
+ *
+ * @example
+ * ```ts
+ * import ejs from 'ejs'
+ * import { ViewAdapter } from '@forinda/kickjs'
+ *
+ * bootstrap({
+ *   modules,
+ *   adapters: [
+ *     ViewAdapter({ engine: ejs, ext: 'ejs', viewsDir: 'src/views' }),
+ *   ],
+ * })
+ *
+ * // In a controller:
+ * @Get('/dashboard')
+ * async dashboard(ctx: RequestContext) {
+ *   ctx.render('dashboard', { user: currentUser, title: 'Dashboard' })
+ * }
+ * ```
+ */
+declare const ViewAdapter: AdapterFactory<ViewAdapterOptions, unknown>;
+//#endregion
+export { mountSort as A, FormatKickErrorOptions as B, groupAssetKeys as C, MountCycleError as D, MissingMountDepError as E, CircuitBreaker as F, disposeAll as G, KickErrorInit as H, CircuitBreakerOptions as I, registerDisposable as K, CircuitBreakerState as L, DuplicateContributorError as M, MissingContextValueError as N, MountKind as O, MissingContributorError as P, CircuitBreakerStats as R, GroupAssetKeysResult as S, DuplicateMountNameError as T, formatKickError as U, KickError as V, Disposable as W, ClusterOptions as _, TraceContextOptions as a, AssetKeyStrategy as b, requestScopeMiddleware as c, getRequestValue as d, requestStore as f, defineHttpContextDecorator as g, materializeRouter as h, TraceContext as i, ContributorCycleError as j, MountSortItem as k, RequestStore as l, expressRuntime as m, ViewAdapterOptions as n, parseTraceparent as o, buildRoutes as p, TRACEPARENT_HEADER as r, traceContext as s, ViewAdapter as t, getRequestStore as u, isClusterPrimary as v, stripExt as w, GroupAssetKeysOptions as x, AssetKeyPair as y, CircuitOpenError as z };
+//# sourceMappingURL=views-DsfBT1fR.d.mts.map

package/dist/views-DsfBT1fR.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views-DsfBT1fR.d.mts","names":[],"sources":["../src/core/disposables.ts","../src/core/kick-error.ts","../src/core/circuit-breaker.ts","../src/core/context-errors.ts","../src/core/mount-sort.ts","../src/core/asset-keys.ts","../src/http/cluster.ts","../src/http/define-http-context-decorator.ts","../src/http/runtimes/express.ts","../src/http/request-store.ts","../src/http/middleware/request-scope.ts","../src/http/middleware/trace-context.ts","../src/http/middleware/views.ts"],"mappings":"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"}

package/dist/web.d.mts

@@ -1,9 +1,8 @@
 
-import { x as MiddlewareHandler } from "./decorators-wEJBqXHg.mjs";
-import { d as ContributorRegistrations, r as AppModuleEntry } from "./app-module-BSpHKlhE.mjs";
-import { D as SseHandler, b as RuntimeResponse, m as RouteEntry } from "./adapter-CEt1MEdF.mjs";
-import { a as KvSessionStoreOptions, c as InferHandlerResponse, d as isReply, f as reply, i as KvSessionStore, l as Reply, n as KvRateLimitStore, o as RateLimitGuardOptions, r as KvRateLimitStoreOptions, s as rateLimitGuard, t as KvLike } from "./kv-stores-duYHIEr1.mjs";
-
+import { x as MiddlewareHandler } from "./decorators-Bks7cgBJ.mjs";
+import { d as ContributorRegistrations, r as AppModuleEntry } from "./app-module-DtoySG6l.mjs";
+import { D as SseHandler, b as RuntimeResponse, m as RouteEntry } from "./adapter-CbMq-NBf.mjs";
+import { a as KvSessionStoreOptions, c as InferHandlerResponse, d as isReply, f as reply, i as KvSessionStore, l as Reply, n as KvRateLimitStore, o as RateLimitGuardOptions, r as KvRateLimitStoreOptions, s as rateLimitGuard, t as KvLike } from "./kv-stores-CHowq8VP.mjs";
 //#region src/http/web/driver.d.ts
 /**
  * Presents a web `Request` as the express-shaped `req` object that