@arki/http 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ARKI Contributors
+
+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,229 @@
+# @arki/http
+
+Typed HTTP for ARKI — route contracts as data, zod-validated handlers,
+request-scope derivers, SSE streaming, and deterministic OpenAPI
+generation. Ships a DOT adapter (`@arki/http/dot`) whose `http()` pip
+turns a composed app into a running server with correct drain-on-shutdown
+semantics.
+
+No decorators, no controller scanning, no runtime DI container. Contracts
+are plain values; wiring is checked at compile time.
+
+## The model
+
+A route is split in two:
+
+- **Contract** — pure data at module scope: method + path + zod schemas +
+  a stable id. Registerable in the DOT manifest (sync `configure`),
+  renderable as OpenAPI without booting, and the source of the handler's
+  inferred signature.
+- **Binding** — the handler, attached inside a pip's `boot` where the
+  pip's typed needs are already injected. Handlers close over real
+  services; no service locator exists.
+
+```ts
+import { route, routes } from '@arki/http';
+import { z } from 'zod';
+
+export const listOrders = route.get('/orders', {
+  id: 'orders.list',
+  query: z.object({ status: z.enum(['open', 'shipped']).optional() }),
+  output: z.array(Order),
+});
+
+export const createOrder = route.post('/orders', {
+  id: 'orders.create',
+  body: CreateOrder,
+  output: Order,
+});
+```
+
+Input validation (query/body) happens before your handler runs; output is
+validated against the contract on the way out. Failures serialize as a
+coded envelope: `{ "error": { "code", "message", "remediation?", "docsUrl?" } }`.
+
+## Inside a DOT app
+
+```ts
+import { pip, provide, service, token } from '@arki/dot/pip';
+import { routes, type RouteBundle } from '@arki/http';
+import { registerRoutes } from '@arki/http/dot';
+
+export const OrdersRoutes = token<RouteBundle>()('orders.routes');
+
+export const ordersPip = pip({
+  name: 'orders',
+  needs: { db: service<Db>() },
+  configure(ctx) {
+    registerRoutes(ctx, [listOrders, createOrder]); // manifest + OpenAPI metadata
+  },
+  async boot({ db }) {
+    return provide(
+      OrdersRoutes,
+      routes()
+        .bind(listOrders, async ({ query }) => db.orders.list(query))
+        .bind(createOrder, async ({ body }, ctx) => db.orders.create(body, ctx.requestId)),
+    );
+  },
+});
+```
+
+Mount the `http()` pip **last**, naming the bundles it serves:
+
+```ts
+import { defineApp, hookSignals } from '@arki/dot';
+import { http } from '@arki/http/dot';
+
+const app = await defineApp('shop-api')
+  .use(db({ url: DATABASE_URL }))
+  .use(ordersPip)
+  .use(http({ port: 3000, bundles: [OrdersRoutes] }))
+  .start();
+
+hookSignals(app);
+```
+
+`http()` derives its `needs` from the tokens you pass — forget to mount
+`ordersPip` and the `.use(http(...))` line fails to typecheck. Because the
+pip is declared last, reverse-order `stop` halts ingress FIRST: the server
+stops accepting, drains in-flight requests (`drainTimeoutMs`, default
+10 s, `ARKI_HTTP_E005` on overrun), and only then do feature pips tear
+down. `boot` builds the router without listening; `start` listens;
+`dispose` severs remaining connections and releases the port.
+
+The published `httpServer` service carries the composed
+`fetch: (Request) => Promise<Response>` — also the unit-test seam: call
+your whole app without a socket.
+
+## Request scope — derivers, not containers
+
+Per-request values are typed context keys derived by plain functions.
+Derivers run in declaration order; each adds a key later handlers (and
+later derivers) see typed. A deriver that throws `HttpError` is the whole
+"guard" story:
+
+```ts
+import { derive, HttpError, HTTP_ERROR_CODES } from '@arki/http';
+
+// inside boot — `auth` is an injected singleton
+const withPrincipal = derive('principal', async req => {
+  const p = await auth.verify(req.headers.get('authorization'));
+  if (!p) throw new HttpError(401, HTTP_ERROR_CODES.unauthorized, 'missing or invalid credentials');
+  return p;
+});
+
+routes()
+  .derive(withPrincipal)
+  .derive('db', (_req, ctx) => dbForTenant(ctx.principal.tenantId))
+  .bind(listOrders, async (_input, ctx) => ctx.db.orders.list());
+```
+
+Request scope is function application over the compile-time-wired
+singleton graph — no per-request container resolution, no infectious
+scopes. For code deep in a call stack you don't control, the fenced-off
+`@arki/http/context` entry exposes `requestContext()` (AsyncLocalStorage).
+It is a last resort; prefer the explicit `ctx`.
+
+## App-wide middleware
+
+For cross-cutting concerns that must see or touch the raw
+request/response — CORS, request logging — pass fetch-shaped middleware
+to `http()` (first = outermost). A middleware that throws `HttpError`
+short-circuits into the coded envelope:
+
+```ts
+http({ port: 3000, bundles: [OrdersRoutes], middleware: [requestLog(logger), cors(origins)] })
+```
+
+Middleware wraps the whole engine and is untyped by design; anything that
+produces a per-request *value* belongs in a deriver instead. Standalone
+users compose the same way with `composeMiddleware(engine.fetch, [...])`.
+
+## Streaming
+
+**Typed SSE.** `route.sse` declares a `text/event-stream` contract; the
+binding is an async generator. Every yield is validated against the event
+schema and framed as a `data:` message; client disconnect aborts
+`ctx.signal` and runs the generator's `finally`:
+
+```ts
+const progress = route.sse('/orders/:id/progress', {
+  id: 'orders.progress',
+  event: z.discriminatedUnion('type', [Queued, Shipped]),
+  heartbeatMs: 15_000, // optional :keepalive comments
+});
+
+routes().bind(progress, async function* ({ params }, ctx) {
+  for await (const step of tracker.watch(params.id, ctx.signal)) {
+    yield step;
+  }
+});
+```
+
+**Raw streams.** Any handler may return a `Response` wrapping a
+`ReadableStream` — file downloads, AI token streams. The engine is
+fetch-native end to end.
+
+## Mounting foreign handlers
+
+An oRPC router, a tRPC fetch adapter, or any fetch-shaped handler mounts
+as one manifest route — the migration on-ramp for existing backends:
+
+```ts
+routes().mount('/rpc', rpcHandler, { id: 'rpc', transport: 'orpc' });
+```
+
+## OpenAPI
+
+```ts
+import { toOpenApi } from '@arki/http';
+
+const document = toOpenApi([listOrders, createOrder, progress], {
+  title: 'shop-api',
+  version: '1.0.0',
+});
+```
+
+Deterministic — same contracts, byte-identical output. Inside a DOT app,
+`registerRoutes` puts the JSON Schemas into the manifest, so
+`dot explain --openapi` renders the document from the static manifest
+without booting anything.
+
+## Without DOT
+
+The core is framework-agnostic:
+
+```ts
+import { buildEngine, listen, routes } from '@arki/http';
+
+const engine = buildEngine([bundle]);
+const handle = await listen(engine.fetch, { port: 3000 });
+```
+
+`listen` uses `Bun.serve` under Bun and `@hono/node-server` under Node.
+Routing is Hono internally; no Hono type appears in the public API.
+
+## Error codes
+
+Stable API — match on codes, never parse messages.
+
+| Code | Meaning |
+| --- | --- |
+| `ARKI_HTTP_E001` | `start` could not bind the port |
+| `ARKI_HTTP_E002` | duplicate route: two bindings claim the same method+path (or a bundle token is listed twice) |
+| `ARKI_HTTP_E005` | `stop` exceeded `drainTimeoutMs` with requests in flight |
+| `ARKI_HTTP_E006` | malformed mount path |
+| `ARKI_HTTP_E007` | deriver key duplicates an earlier deriver or a base context key |
+| `ARKI_HTTP_E008` | a bundle token's service was missing at boot (erased composition only) |
+| `ARKI_HTTP_E400` | request validation failed (query/body) or body is not valid JSON |
+| `ARKI_HTTP_E401` / `E403` | credential / permission rejection (thrown by your derivers) |
+| `ARKI_HTTP_E404` | no route matches |
+| `ARKI_HTTP_E500` | handler crash or output-schema violation |
+
+`E0NN` codes surface through the DOT lifecycle into `app.diagnostics`;
+`E4xx`/`E5xx` codes surface on the wire in the error envelope. Unexpected
+error messages are redacted when `NODE_ENV=production`.
+
+## License
+
+MIT

package/dist/bundle.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Route bundles — the dynamic half of an HTTP surface.
+ *
+ * A bundle binds contracts to handlers. It is assembled inside a pip's
+ * `boot` hook — where the pip's `needs` are already injected — so handlers
+ * and derivers close over typed singletons:
+ *
+ * ```ts
+ * export const OrdersRoutes = token<RouteBundle>()('orders.routes');
+ *
+ * export const ordersPip = pip({
+ *   name: 'orders',
+ *   needs: { db: service<Db>() },
+ *   configure(ctx) {
+ *     registerRoutes(ctx, [listOrders, createOrder]); // from '@arki/http/dot'
+ *   },
+ *   async boot({ db }) {
+ *     return provide(
+ *       OrdersRoutes,
+ *       routes()
+ *         .bind(listOrders, async ({ query }) => db.orders.list(query))
+ *         .bind(createOrder, async ({ body }, ctx) => db.orders.create(body, ctx.requestId)),
+ *     );
+ *   },
+ * });
+ * ```
+ *
+ * The builder accumulates deriver-added context keys in its type — a
+ * handler bound after `.derive('principal', …)` sees `ctx.principal`
+ * typed. Same accumulation idiom as `defineApp().use()`.
+ */
+import type { ContractLike, ParamsOf, RouteContract, SseContract } from './contract.js';
+import type { BaseRequestCtx, Deriver, ErasedDeriver } from './derive.js';
+type MaybePromise<T> = T | Promise<T>;
+/** The validated inputs a bound handler receives. */
+export type RouteInput<TPath extends string, TQuery, TBody> = {
+    readonly params: ParamsOf<TPath>;
+    readonly query: TQuery;
+    readonly body: TBody;
+};
+/**
+ * What a JSON handler may return: the contract's output type (serialized
+ * and validated), or a raw `Response` as the escape hatch — redirects,
+ * files, custom streams. Contracts without an output schema must return
+ * a `Response`.
+ */
+export type HandlerResult<TOutput> = [TOutput] extends [undefined] ? Response : TOutput | Response;
+/** Handler signature inferred from a {@link RouteContract}. */
+export type RouteHandler<TPath extends string, TQuery, TBody, TOutput, TCtx extends BaseRequestCtx> = (input: RouteInput<TPath, TQuery, TBody>, ctx: TCtx) => MaybePromise<HandlerResult<TOutput>>;
+/**
+ * Handler signature inferred from an {@link SseContract}: an async
+ * iterable (usually an async generator) of events. Each yielded value is
+ * validated against the contract's event schema and framed as an SSE
+ * `data:` message. Client disconnect aborts `ctx.signal` and terminates
+ * the iterator.
+ */
+export type SseHandler<TPath extends string, TQuery, TEvent, TCtx extends BaseRequestCtx> = (input: RouteInput<TPath, TQuery, undefined>, ctx: TCtx) => AsyncIterable<TEvent>;
+/** Non-HTTP transports a {@link RouteBundleBuilder.mount} can declare. */
+export type MountTransport = 'orpc' | 'trpc' | 'rpc' | 'custom';
+export type MountMeta = {
+    /** Stable identifier — lands in the manifest like a contract id. */
+    readonly id: string;
+    /** Manifest transport tag. Defaults to `'custom'`. */
+    readonly transport?: MountTransport;
+};
+/** A contract bound to its (generics-erased) handler. */
+export type RouteBinding = {
+    readonly contract: ContractLike;
+    /**
+     * Stored erased (`never` parameters) — typed handlers are assignable
+     * via parameter contravariance from the bottom type; the engine crosses
+     * the erasure boundary at the call site. Mirrors the DOT kernel's
+     * hook-storage pattern.
+     */
+    readonly handler: (input: never, ctx: never) => unknown;
+};
+/** A mounted foreign fetch handler (oRPC/tRPC router, static files, …). */
+export type MountBinding = {
+    readonly id: string;
+    readonly path: string;
+    readonly transport: MountTransport;
+    readonly handler: (req: Request) => Response | Promise<Response>;
+};
+/**
+ * A plain value: derivers + bound contracts + mounts. Published as an
+ * ordinary DOT service under a token and collected by the `http()` pip —
+ * no new kernel concept.
+ */
+export type RouteBundle = {
+    readonly derivers: readonly ErasedDeriver[];
+    readonly bindings: readonly RouteBinding[];
+    readonly mounts: readonly MountBinding[];
+};
+/**
+ * Immutable bundle builder. Every method returns a new builder; deriver
+ * keys accumulate in `TCtx` so later `bind` handlers see them typed.
+ */
+export type RouteBundleBuilder<TCtx extends BaseRequestCtx = BaseRequestCtx> = RouteBundle & {
+    /** Add a reusable deriver (see {@link Deriver}). */
+    derive<K extends string, V>(deriver: Deriver<K, V, TCtx>): RouteBundleBuilder<TCtx & Readonly<Record<K, V>>>;
+    /** Add an inline deriver. */
+    derive<K extends string, V>(key: K, fn: (req: Request, ctx: TCtx) => V | Promise<V>): RouteBundleBuilder<TCtx & Readonly<Record<K, V>>>;
+    /**
+     * Bind a JSON contract to its handler. `NoInfer` pins the input/output
+     * generics to the contract — without it, a handler returning the wrong
+     * shape would silently widen `TOutput` instead of failing to compile.
+     */
+    bind<TPath extends string, TQuery, TBody, TOutput>(contract: RouteContract<TPath, TQuery, TBody, TOutput>, handler: RouteHandler<TPath, NoInfer<TQuery>, NoInfer<TBody>, NoInfer<TOutput>, TCtx>): RouteBundleBuilder<TCtx>;
+    /** Bind an SSE contract to its event generator. */
+    bind<TPath extends string, TQuery, TEvent>(contract: SseContract<TPath, TQuery, TEvent>, handler: SseHandler<TPath, NoInfer<TQuery>, NoInfer<TEvent>, TCtx>): RouteBundleBuilder<TCtx>;
+    /**
+     * Mount a foreign fetch handler under a path prefix — an oRPC router, a
+     * tRPC fetch adapter, a static-file handler. One manifest route, no
+     * schemas, derivers do NOT run for mounted handlers.
+     */
+    mount(path: string, handler: (req: Request) => Response | Promise<Response>, meta: MountMeta): RouteBundleBuilder<TCtx>;
+};
+/** Start an empty bundle. See the module docs for the authoring pattern. */
+export declare function routes(): RouteBundleBuilder;
+export {};
+//# sourceMappingURL=bundle.d.ts.map

package/dist/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"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"}

package/dist/bundle.js

@@ -0,0 +1,98 @@
+/**
+ * Route bundles — the dynamic half of an HTTP surface.
+ *
+ * A bundle binds contracts to handlers. It is assembled inside a pip's
+ * `boot` hook — where the pip's `needs` are already injected — so handlers
+ * and derivers close over typed singletons:
+ *
+ * ```ts
+ * export const OrdersRoutes = token<RouteBundle>()('orders.routes');
+ *
+ * export const ordersPip = pip({
+ *   name: 'orders',
+ *   needs: { db: service<Db>() },
+ *   configure(ctx) {
+ *     registerRoutes(ctx, [listOrders, createOrder]); // from '@arki/http/dot'
+ *   },
+ *   async boot({ db }) {
+ *     return provide(
+ *       OrdersRoutes,
+ *       routes()
+ *         .bind(listOrders, async ({ query }) => db.orders.list(query))
+ *         .bind(createOrder, async ({ body }, ctx) => db.orders.create(body, ctx.requestId)),
+ *     );
+ *   },
+ * });
+ * ```
+ *
+ * The builder accumulates deriver-added context keys in its type — a
+ * handler bound after `.derive('principal', …)` sees `ctx.principal`
+ * typed. Same accumulation idiom as `defineApp().use()`.
+ */
+import { BASE_CTX_KEYS } from './derive.js';
+import { HTTP_ERROR_CODES, HttpConfigError } from './error.js';
+function assertFreshDeriverKey(key, existing) {
+    const reserved = BASE_CTX_KEYS.includes(key);
+    const duplicate = existing.some(d => d.key === key);
+    if (!reserved && !duplicate)
+        return;
+    throw new HttpConfigError({
+        code: HTTP_ERROR_CODES.duplicateDeriverKey,
+        message: reserved
+            ? `[http] deriver key "${key}" shadows a base request-context key.`
+            : `[http] deriver key "${key}" is already derived in this bundle.`,
+        remediation: `Pick a different key — base keys (${BASE_CTX_KEYS.join(', ')}) and earlier deriver keys are reserved.`,
+    });
+}
+function makeBuilder(state) {
+    const impl = {
+        derivers: state.derivers,
+        bindings: state.bindings,
+        mounts: state.mounts,
+        derive(keyOrDeriver, fn) {
+            let deriver;
+            if (typeof keyOrDeriver === 'string') {
+                if (fn === undefined) {
+                    throw new HttpConfigError({
+                        code: HTTP_ERROR_CODES.duplicateDeriverKey,
+                        message: `[http] derive("${keyOrDeriver}") is missing its deriver function.`,
+                        remediation: 'Pass derive(key, fn) or derive(deriverObject).',
+                    });
+                }
+                deriver = { key: keyOrDeriver, derive: fn };
+            }
+            else {
+                deriver = keyOrDeriver;
+            }
+            assertFreshDeriverKey(deriver.key, state.derivers);
+            return makeBuilder({ ...state, derivers: [...state.derivers, deriver] });
+        },
+        bind(contract, handler) {
+            return makeBuilder({ ...state, bindings: [...state.bindings, { contract, handler }] });
+        },
+        mount(path, handler, meta) {
+            if (!path.startsWith('/') || path.includes(' ')) {
+                throw new HttpConfigError({
+                    code: HTTP_ERROR_CODES.invalidMount,
+                    message: `[http] mount path "${path}" is invalid — it must start with "/" and contain no spaces.`,
+                    remediation: 'Mount under an absolute path prefix, e.g. mount("/rpc", handler, { id: "rpc" }).',
+                });
+            }
+            return makeBuilder({
+                ...state,
+                mounts: [...state.mounts, { id: meta.id, path, transport: meta.transport ?? 'custom', handler }],
+            });
+        },
+    };
+    // Erasure seam: the implementation works on erased contracts/handlers/
+    // derivers; the public builder type re-attaches the generics. The typed
+    // methods' arguments are structurally assignable to the erased
+    // parameters, so the only unsafe step is this widening of the return
+    // type — same seam as the DOT app builder's makeBuilder.
+    return impl;
+}
+/** Start an empty bundle. See the module docs for the authoring pattern. */
+export function routes() {
+    return makeBuilder({ derivers: [], bindings: [], mounts: [] });
+}
+//# sourceMappingURL=bundle.js.map

package/dist/bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.js","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Ambient request context — the last resort.
+ *
+ * Explicit `ctx` threading fails in one honest case: code deep in a call
+ * stack whose signatures you don't control (log enrichment inside a
+ * shared library). For that, this entry exposes the current request's
+ * {@link BaseRequestCtx} via `AsyncLocalStorage`.
+ *
+ * Ambient context is a smell — prefer the explicit `ctx` parameter and
+ * derivers everywhere a signature is yours to change. Note that OTel
+ * trace context already propagates this way, so span/log correlation
+ * needs none of this.
+ *
+ * This module is deliberately NOT re-exported from the package root.
+ * Import it as `@arki/http/context`.
+ */
+import type { BaseRequestCtx } from './derive.js';
+/**
+ * The context of the request currently being handled, or `undefined`
+ * outside a request (startup, background jobs, tests that call handlers
+ * directly).
+ */
+export declare function requestContext(): BaseRequestCtx | undefined;
+/**
+ * Engine seam: run `fn` with `ctx` as the ambient request context. Called
+ * by the engine around every request — not part of the public surface.
+ */
+export declare function runWithRequestContext<T>(ctx: BaseRequestCtx, fn: () => T): T;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,cAAc,GAAG,SAAS,CAE3D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5E"}

package/dist/context.js

@@ -0,0 +1,34 @@
+/**
+ * Ambient request context — the last resort.
+ *
+ * Explicit `ctx` threading fails in one honest case: code deep in a call
+ * stack whose signatures you don't control (log enrichment inside a
+ * shared library). For that, this entry exposes the current request's
+ * {@link BaseRequestCtx} via `AsyncLocalStorage`.
+ *
+ * Ambient context is a smell — prefer the explicit `ctx` parameter and
+ * derivers everywhere a signature is yours to change. Note that OTel
+ * trace context already propagates this way, so span/log correlation
+ * needs none of this.
+ *
+ * This module is deliberately NOT re-exported from the package root.
+ * Import it as `@arki/http/context`.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+/**
+ * The context of the request currently being handled, or `undefined`
+ * outside a request (startup, background jobs, tests that call handlers
+ * directly).
+ */
+export function requestContext() {
+    return storage.getStore();
+}
+/**
+ * Engine seam: run `fn` with `ctx` as the ambient request context. Called
+ * by the engine around every request — not part of the public surface.
+ */
+export function runWithRequestContext(ctx, fn) {
+    return storage.run(ctx, fn);
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAkB,CAAC;AAExD;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAI,GAAmB,EAAE,EAAW;IACvE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC9B,CAAC"}