@tetsujs/openapi 0.4.1 → 0.5.0

package/README.md

@@ -30,6 +30,38 @@ reported before the first request.
 prefix, guard it with hooks, or leave it out in production. Its own two
 routes are left out of the document.
 
+### The page runs someone else's code on your origin
+
+The page loads its renderer — Scalar, Swagger UI or Redoc — from
+jsDelivr and runs it on the application's origin, with that origin's
+cookies. If a session cookie lives there, a renderer that is not what it
+should be acts as the signed-in user. The defaults are pinned to an exact
+version with a Subresource Integrity hash, so a file the CDN changes is
+refused by the browser; that does not make the renderer yours, and what it
+loads in turn is not covered.
+
+Where the origin carries a session, serve the document alone:
+
+```ts
+docs({ info, ui: false });
+```
+
+`/openapi.json` is served and there is no page. For a page anyway, host
+the renderer yourself or pin your own copy, with its hash:
+
+```ts
+docs({
+  info,
+  assets: {
+    script: "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.72.1/dist/browser/standalone.js",
+    integrity: { script: "sha384-…" },
+  },
+});
+```
+
+`curl -s <url> | openssl dgst -sha384 -binary | openssl base64 -A` prints
+the hash, to be prefixed with `sha384-`.
+
 ## Options
 
 | Option | Default | |
@@ -38,11 +70,12 @@ routes are left out of the document.
 | `servers` | — | where the API is reachable |
 | `path` | `/openapi.json` | where the document is served |
 | `uiPath` | `/docs` | where the page is served |
-| `ui` | `"scalar"` | `"scalar"`, `"swagger-ui"` or `"redoc"` |
+| `ui` | `"scalar"` | `"scalar"`, `"swagger-ui"`, `"redoc"`, or `false` for no page |
 | `title` | the document's title | the page's title |
-| `assets` | the renderer's CDN | pinned or self-hosted renderer URLs |
+| `assets` | the renderer on jsDelivr, pinned | your own renderer URLs, with `integrity` hashes |
 | `documentSelf` | `false` | include `/openapi.json` and `/docs` in the document |
 | `onWarning` | `console.warn` | receives what could not be described |
+| `errors` | the framework's envelope | an error format of your own — see [below](#an-error-format-of-your-own) |
 
 ## What goes into the document
 
@@ -106,6 +139,95 @@ The `error` code is a constant in each schema, so a generated client can
 tell failures apart by it. A status the route declares itself is kept, and
 the framework's failures for the same status are listed next to it.
 
+Every envelope — the framework's, a hook's, or one the route declares
+itself — is one definition in `components` per status and code, named
+after the code (`ITEM_NOT_FOUND` is `ItemNotFound`), so a generated client
+gets one type per failure. A schema is recognized as an envelope when its
+`error` is required and a single string. When the route and a hook both
+describe one code, the route's definition is kept; if the other one has
+different fields, the generator warns. A union the route declares joins
+the other failures of its status as one flat `anyOf`.
+
+When every alternative of a status is an envelope, the union carries a
+`discriminator` on `error`, with the mapping from each code to its
+definition, and a generated client narrows on the code.
+
+## An error format of your own
+
+Every failure reaches the application's `onError` hooks — a thrown
+`HttpError`, a validation or body failure, a `404`, a `405`, a rate limit's
+refusal — so one hook answers all of them in your format:
+
+```ts
+const inOurFormat = hook.onError(({ error }) => {
+  if (!(error instanceof HttpError)) return undefined;
+
+  const { status, error: code, ...rest } = error.body as ErrorBody;
+
+  return Response.json({ code, ...rest }, { status });
+});
+```
+
+The document is generated from the routes, not from that hook, so it is
+told the same format with `errors`:
+
+```ts
+const errors: ErrorFormat = {
+  schema: ({ error, message, fields }) => ({
+    type: "object",
+    required: ["code", "message", ...Object.keys(fields)],
+    properties: {
+      code: error ? { type: "string", const: error } : { type: "string" },
+      message: { type: "string", ...(message ? { examples: [message] } : {}) },
+      ...fields,
+    },
+  }),
+  discriminator: "code",
+};
+
+createApp({
+  hooks: { onError: [inOurFormat] },
+  routes: [api, docs({ info, errors })],
+});
+```
+
+`schema` describes one failure from what the generator knows of it: its
+status, its code when known, an example message, and in `fields` what it
+carries besides — `issues` for a validation failure, `retryAfter` for a
+rate limit, a hook's own `fields`. It is used for the framework's failures
+and the hooks' refusals alike.
+
+`discriminator` names the top-level field that holds the code. Statuses of
+envelopes are then discriminated on it, and a route's own envelope is
+recognized by it — a `{ code: "ITEM_NOT_FOUND", … }` the route declares is
+the same definition as a hook's. A format that nests its code has no
+top-level field to name; it gives `code` instead, reading the code from a
+route's schema:
+
+```ts
+code: (schema) => {
+  const error = schema.properties?.error;
+  const code = typeof error === "object" ? error.properties?.code : undefined;
+
+  return typeof code === "object" && typeof code.const === "string" ? code.const : undefined;
+},
+```
+
+The hook and `errors` describe one format in two places — the core knows
+nothing about documents, and a function cannot be read for the shape it
+returns — so keep a test that holds them together: provoke a failure and
+check its body against the document, with the JSON Schema validator of
+your choice.
+
+```ts
+test("a validation failure is what the document says", async () => {
+  const res = await request("/items", { method: "POST", body: "{}" });
+  const schema = document.components?.schemas?.ValidationFailed;
+
+  expect(validator.validate(schema, await res.json())).toBe(true);
+});
+```
+
 ## Documenting hooks
 
 A hook that answers by itself — an auth check, a limiter — can say so, and
@@ -127,10 +249,25 @@ export const auth = secured(
 );
 
 export const guard = documented(hook.beforeParse(check), {
-  responses: [{ status: 429, description: "Rate limit exceeded", error: "RATE_LIMITED" }],
+  responses: [
+    {
+      status: 429,
+      description: "Rate limit exceeded",
+      error: "RATE_LIMITED",
+      fields: { retryAfter: { type: "integer", minimum: 0 } },
+      headers: { "retry-after": { schema: { type: "integer", minimum: 0 } } },
+    },
+  ],
 });
 ```
 
+A response with an `error` code is the framework's envelope, defined once
+in `components` and named after the code. `fields` adds what the hook puts
+next to `status`, `message` and `error`, each always present; `headers`,
+what it sets on the response. Both are JSON Schema written by hand, typed
+keyword by keyword (`JsonSchema`), so a misspelled keyword does not
+compile. A hook whose body is not the envelope passes a `schema` instead.
+
 Hooks from `@tetsujs/rate-limit` are already documented this way. A scheme
 is identified by its `name`: the same one mounted twice is one
 requirement, and two different schemes under one name are reported.

package/dist/src/annotations.d.ts

@@ -16,6 +16,7 @@
  * @module
  */
 import type { AnyHook, AnySchema } from "@tetsujs/core";
+import type { JsonSchema } from "./json-schema.ts";
 /**
  * The definition of a scheme, as OpenAPI spells it.
  *
@@ -70,6 +71,45 @@ export interface DocumentedResponse {
     readonly error?: string;
     /** An example of the envelope's `message`, for the same reason. */
     readonly message?: string;
+    /**
+     * Fields the hook adds to the envelope, as JSON Schema by name — the
+     * `retryAfter` of `{ ...errorBody(429, "RATE_LIMITED"), retryAfter }`.
+     *
+     * Each is documented as always present. The envelope's own `status`,
+     * `message` and `error` are not redefined by a field of the same name:
+     * `error` is what a client discriminates on, and it stays the code the
+     * hook declared. Ignored when the response has a `schema`, which says
+     * everything about the body itself.
+     *
+     * @example
+     * ```ts
+     * documented(limiter, {
+     *   responses: [
+     *     {
+     *       status: 429,
+     *       description: "Too many requests",
+     *       error: "RATE_LIMITED",
+     *       fields: { retryAfter: { type: "integer", minimum: 0 } },
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    readonly fields?: Readonly<Record<string, JsonSchema>>;
+    /**
+     * Headers the hook sets on this response, by name — the `retry-after`
+     * of a refusal.
+     *
+     * Documented as possible rather than required: a status several sources
+     * answer with is one response in the document, and a header one of them
+     * sets is not on the others'.
+     */
+    readonly headers?: Readonly<Record<string, DocumentedHeader>>;
+}
+/** A header a hook's response carries. */
+export interface DocumentedHeader {
+    readonly description?: string;
+    readonly schema: JsonSchema;
 }
 /**
  * Requirements of which a hook accepts any one: a session cookie *or* a

package/dist/src/annotations.d.ts.map

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

package/dist/src/controller.d.ts

@@ -15,20 +15,34 @@
 import type { App, RouteDef, SchemaConfig, ValidatePath } from "@tetsujs/core";
 import { onMount } from "@tetsujs/core";
 import type { OpenApiDocument } from "./document.ts";
+import type { ErrorFormat } from "./errors.ts";
 import type { GeneratorWarning } from "./index.ts";
 import type { DocsAssets, DocsUi } from "./page.ts";
 /** What the documentation controller serves, and from where. */
-export interface DocsOptions<Path extends string, UiPath extends string> {
+export interface DocsOptions<Path extends string, UiPath extends string, Ui extends DocsUi | false = DocsUi | false> {
     /** Title, version and the rest of the document's `info` block. */
     readonly info: OpenApiDocument["info"];
     /** Servers the API is reachable at. */
     readonly servers?: OpenApiDocument["servers"];
+    /**
+     * How the application's errors look, when not like the framework's
+     * envelope — see `errors` on {@link openapi}.
+     */
+    readonly errors?: ErrorFormat;
     /** Where the document is served. Defaults to `/openapi.json`. */
     readonly path?: Path & ValidatePath<Path>;
     /** Where the page is served. Defaults to `/docs`. */
     readonly uiPath?: UiPath & ValidatePath<UiPath>;
-    /** Which renderer the page bootstraps. Defaults to `"scalar"`. */
-    readonly ui?: DocsUi;
+    /**
+     * Which renderer the page bootstraps. Defaults to `"scalar"`.
+     *
+     * `false` serves the document without a page — what production wants
+     * on an origin that carries a session. The page runs its renderer on the
+     * application's origin, so a renderer that is not what it should be acts
+     * in the signed-in user's name there; the document alone runs nothing.
+     * `uiPath`, `title` and `assets` are then unused.
+     */
+    readonly ui?: Ui;
     /** Browser title of the page. Defaults to the document's own title. */
     readonly title?: string;
     /** Overrides the renderer's CDN URLs, for a pinned or self-hosted copy. */
@@ -56,15 +70,24 @@ export interface DocsOptions<Path extends string, UiPath extends string> {
  * Instantiated through the factory, never directly — the routes carry the
  * configured paths in their types, which only the factory can infer.
  */
-export declare class DocsController<Path extends string, UiPath extends string> {
+export declare class DocsController<Path extends string, UiPath extends string, Page extends boolean = true> {
     private readonly options;
     /** The document itself, as `application/json`. */
     readonly json: RouteDef<Path, SchemaConfig, never, undefined, "GET">;
-    /** The page that renders it. */
-    readonly ui: RouteDef<UiPath, SchemaConfig, never, undefined, "GET">;
+    /** The page that renders it — none with `ui: false`. */
+    readonly ui: Page extends true ? RouteDef<UiPath, SchemaConfig, never, undefined, "GET"> : undefined;
     private document;
-    constructor(options: DocsOptions<Path, UiPath>, documentPath: string, uiPath: string, page: string);
-    /** Generates the document of the application this was mounted in. */
+    private page;
+    constructor(options: DocsOptions<Path, UiPath>, documentPath: string, uiPath: string);
+    /**
+     * Generates the document of the application this was mounted in, and
+     * the page that renders it.
+     *
+     * The page is built here rather than with the routes because only the
+     * application knows where the document ended up: a group this controller
+     * is mounted under prefixes its path, and a page pointing at the path as
+     * configured would fetch a `404`.
+     */
     [onMount](app: App): void;
 }
 /**
@@ -87,5 +110,5 @@ export declare class DocsController<Path extends string, UiPath extends string>
  * The page loads its renderer from a CDN; see {@link docsPage} for the
  * trade and for how to point it at a self-hosted copy.
  */
-export declare function docs<const Path extends string = "/openapi.json", const UiPath extends string = "/docs">(options: DocsOptions<Path, UiPath>): DocsController<Path, UiPath>;
+export declare function docs<const Path extends string = "/openapi.json", const UiPath extends string = "/docs", const Ui extends DocsUi | false = "scalar">(options: DocsOptions<Path, UiPath, Ui>): DocsController<Path, UiPath, Ui extends false ? false : true>;
 //# sourceMappingURL=controller.d.ts.map

package/dist/src/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAS,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGpD,gEAAgE;AAChE,MAAM,WAAW,WAAW,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM;IACrE,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAE9C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAE1C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAEhD,kEAAkE;IAClE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAErB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAE7B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,qBAAa,cAAc,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM;IAUlE,OAAO,CAAC,QAAQ,CAAC,OAAO;IAT1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAErE,gCAAgC;IAChC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAErE,OAAO,CAAC,QAAQ,CAA8B;IAE9C,YACmB,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EACnD,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAgCb;IAED,qEAAqE;IACrE,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAaxB;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAClB,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,eAAe,EAC3C,KAAK,CAAC,MAAM,SAAS,MAAM,GAAG,OAAO,EACrC,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAYlE"}
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/controller.ts"],"names":[],"mappings":"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"}

package/dist/src/document.d.ts

@@ -14,6 +14,7 @@
  *
  * @module
  */
+import type { JsonSchema } from "./json-schema.ts";
 /** Metadata every OpenAPI document must carry. */
 export interface DocumentInfo {
     readonly title: string;
@@ -38,9 +39,15 @@ export interface ParameterObject {
 export type ContentMap = Record<string, {
     readonly schema?: Record<string, unknown>;
 }>;
+/** A header a response carries. */
+export interface HeaderObject {
+    readonly description?: string;
+    readonly schema: JsonSchema;
+}
 /** One response of an operation. */
 export interface ResponseObject {
     readonly description: string;
+    readonly headers?: Record<string, HeaderObject>;
     readonly content?: ContentMap;
 }
 /** One endpoint: a method on a path. */

package/dist/src/document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,MAAM,CAC7B,MAAM,EACN;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAC9C,CAAC;AAEF,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;CAC/B;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;KAC9B,CAAC;IACF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACpD;AAED,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAE7D,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAE/C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE;QACpB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC5C,CAAC;IAEF,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC"}
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,MAAM,CAC7B,MAAM,EACN;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAC9C,CAAC;AAEF,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;CAC/B;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;KAC9B,CAAC;IACF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACpD;AAED,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAE7D,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAE/C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE;QACpB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC5C,CAAC;IAEF,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC"}

package/dist/src/emit.d.ts

@@ -6,13 +6,15 @@
  * @module
  */
 /**
- * A JSON Schema as the generator reads it: any keyword, with the two it
+ * A JSON Schema as the generator reads it: any keyword, with the ones it
  * looks into named, so reading them does not depend on the reader's
  * `noPropertyAccessFromIndexSignature`.
  */
 export interface JsonSchemaObject {
     properties?: unknown;
     required?: unknown;
+    anyOf?: unknown;
+    oneOf?: unknown;
     [keyword: string]: unknown;
 }
 /** Which shape of a schema to describe: what arrives, or what leaves. */

package/dist/src/emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,yEAAyE;AACzE,KAAK,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC/B,SAAS,GAAE,SAAoB,GAC9B,gBAAgB,GAAG,SAAS,CAkB9B"}
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,yEAAyE;AACzE,KAAK,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC/B,SAAS,GAAE,SAAoB,GAC9B,gBAAgB,GAAG,SAAS,CAkB9B"}

package/dist/src/envelopes.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Error envelopes, one definition per status and code.
+ *
+ * An envelope reaches a document from four directions: a route's response
+ * map, a hook's annotation, a guard's security requirement, and the
+ * framework's own failures. Each used to be described where it arrived —
+ * a route's inline, the rest by reference — so one `UNAUTHORIZED` could be
+ * listed twice under one status, once as a `$ref` and once as the same
+ * shape without a name, and a generated client got a named type next to an
+ * anonymous twin.
+ *
+ * Here every envelope, whoever declared it, becomes a reference to the
+ * one definition of its status and code. That is also what makes a status
+ * discriminable: a client can branch on `error` only if every code under
+ * the status has exactly one shape.
+ *
+ * The route's definition wins. It is the author's own contract — usually
+ * the stricter one, a validator's `additionalProperties: false` — where a
+ * hook's is the framework's generic envelope. The routes are therefore
+ * read first, before any operation is built, so the winner does not depend
+ * on which route happens to come first in the table.
+ *
+ * What an envelope looks like — how one is described, where its code is,
+ * what a client discriminates on — is the document's error format, which
+ * the registry carries for everything that builds or reads one.
+ *
+ * Internal to the package.
+ *
+ * @module
+ */
+import type { SchemaComponents, SchemaRef } from "./components.ts";
+import type { JsonSchemaObject } from "./emit.ts";
+import type { ResolvedFormat } from "./errors.ts";
+/** The definitions of every envelope of one document. */
+export interface Envelopes {
+    /** The document's error format. */
+    readonly format: ResolvedFormat;
+    /**
+     * Records a route's definition, before anything is referenced. The first
+     * route to declare a status and code defines it.
+     */
+    declare(status: number, code: string, schema: JsonSchemaObject): void;
+    /**
+     * The reference to the definition of a status and code.
+     *
+     * `schema` is how the caller describes it. When a definition already
+     * exists, that is what is referenced; if the caller's differs from it
+     * in fields, `warn` hears about it — once per document, not once per
+     * operation the hook runs on.
+     */
+    ref(status: number, code: string, schema: JsonSchemaObject, warn: (message: string) => void): SchemaRef;
+    /**
+     * The code a reference stands for, when it is one this handed out — what
+     * a discriminator maps back from.
+     */
+    codeOf(ref: string): string | undefined;
+}
+export declare function envelopes(components: SchemaComponents, format: ResolvedFormat): Envelopes;
+/**
+ * The alternatives a schema stands for, as a list the status's own union
+ * can take in.
+ *
+ * `anyOf` nested in `anyOf` says nothing its branches do not say side by
+ * side, so a schema that is only an `anyOf` is replaced by its branches.
+ * A `oneOf` is different — "exactly one" of two overlapping shapes refuses
+ * what both accept — and is taken apart only when its branches cannot
+ * overlap: envelopes with a different code each. A schema with anything
+ * beside its union, a `title` or a `$defs`, is left whole: those keywords
+ * belong to the union, and would be lost with it.
+ */
+export declare function branchesOf(schema: JsonSchemaObject, code: (schema: JsonSchemaObject) => string | undefined): JsonSchemaObject[];
+//# sourceMappingURL=envelopes.d.ts.map

package/dist/src/envelopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelopes.d.ts","sourceRoot":"","sources":["../../src/envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAEtE;;;;;;;OAOG;IACH,GAAG,CACD,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,SAAS,CAAC;IAEb;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,wBAAgB,SAAS,CACvB,UAAU,EAAE,gBAAgB,EAC5B,MAAM,EAAE,cAAc,GACrB,SAAS,CAsEX;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,GACrD,gBAAgB,EAAE,CA0BpB"}

package/dist/src/errors.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The shape the document gives an error.
+ *
+ * Every failure an application answers with reaches its `onError` hooks,
+ * so one hook sets the format of all of them. The document is generated
+ * from the routes, not from that hook, and cannot see what it does: an
+ * application with a format of its own says so here too, and the framework's
+ * failures, the hooks' refusals and the routes' own envelopes are described
+ * in it. Keeping the two in step is the application's to do — the core knows
+ * nothing about documents, and a function cannot be read for the shape it
+ * returns.
+ *
+ * Without it the format is the framework's envelope,
+ * `{ status, message, error }`.
+ *
+ * @module
+ */
+import type { JsonSchemaObject } from "./emit.ts";
+import type { JsonSchema, JsonSchemaKeywords } from "./json-schema.ts";
+/**
+ * One failure the document describes, as the generator knows it.
+ *
+ * This is everything known about a failure before it is answered: its
+ * status, its code when the framework or the hook knows it, an example of
+ * its message, and what else it carries — the `issues` of a validation
+ * failure, the `retryAfter` of a rate limit. Where each goes in the body
+ * is the format's to decide.
+ */
+export interface DocumentedFailure {
+    readonly status: number;
+    /** The code a client branches on, when it is known. */
+    readonly error?: string;
+    /** An example of the message; wording, never a contract. */
+    readonly message?: string;
+    /** What the failure carries besides, as JSON Schema by name. */
+    readonly fields: Readonly<Record<string, JsonSchema>>;
+}
+/** How the application's errors look, for the document to describe them. */
+export interface ErrorFormat {
+    /** The body of one failure. */
+    readonly schema: (failure: DocumentedFailure) => JsonSchemaKeywords;
+    /**
+     * The top-level field that holds the code, for a client to discriminate
+     * on — `"code"` in `{ code, message }`. A status whose alternatives are
+     * all envelopes then carries a `discriminator` on it.
+     *
+     * None unless named: OpenAPI discriminates on a top-level field only, and
+     * a format that nests its code — `{ error: { code } }` — has none to
+     * name.
+     */
+    readonly discriminator?: string;
+    /**
+     * The code of a schema a route or a hook declared, when it is an
+     * envelope in this format — how the document knows a route's own `404`
+     * is the same failure as a hook's, and gives both one definition.
+     *
+     * Read off the JSON Schema the validator emitted. By default, the
+     * `const` of the discriminator's field, when there is one; a nested
+     * format says where its code is.
+     */
+    readonly code?: (schema: JsonSchemaKeywords) => string | undefined;
+}
+/** What the generator works with: every part of a format, filled in. */
+export interface ResolvedFormat {
+    describe(failure: DocumentedFailure): JsonSchemaObject;
+    code(schema: JsonSchemaObject): string | undefined;
+    readonly discriminator: string | undefined;
+}
+/**
+ * A format as the generator uses it. Absent, the framework's envelope,
+ * discriminated on `error`.
+ */
+export declare function resolveFormat(format: ErrorFormat | undefined): ResolvedFormat;
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;CACvD;AAED,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,kBAAkB,CAAC;IAEpE;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,MAAM,GAAG,SAAS,CAAC;CACpE;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IACvD,IAAI,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,cAAc,CAqB7E"}

package/dist/src/index.d.ts

@@ -20,11 +20,14 @@
  */
 import type { App } from "@tetsujs/core";
 import type { OpenApiDocument } from "./document.ts";
-export type { DocumentedResponse, HookContributions, HookDocs, SecurityAlternatives, SecurityRequirement, SecurityScheme, } from "./annotations.ts";
+import type { ErrorFormat } from "./errors.ts";
+export type { DocumentedHeader, DocumentedResponse, HookContributions, HookDocs, SecurityAlternatives, SecurityRequirement, SecurityScheme, } from "./annotations.ts";
 export { documented, secured } from "./annotations.ts";
 export type { DocsOptions } from "./controller.ts";
 export { DocsController, docs } from "./controller.ts";
-export type { ContentMap, DocumentInfo, DocumentServer, OpenApiDocument, OperationObject, ParameterObject, PathItemObject, ResponseObject, } from "./document.ts";
+export type { ContentMap, DocumentInfo, DocumentServer, HeaderObject, OpenApiDocument, OperationObject, ParameterObject, PathItemObject, ResponseObject, } from "./document.ts";
+export type { DocumentedFailure, ErrorFormat } from "./errors.ts";
+export type { JsonSchema, JsonSchemaKeywords, JsonSchemaType, } from "./json-schema.ts";
 export type { DocsAssets, DocsPageOptions, DocsUi } from "./page.ts";
 export { docsPage } from "./page.ts";
 /**
@@ -35,6 +38,32 @@ export interface OpenApiOptions {
     readonly info: OpenApiDocument["info"];
     /** Servers the API is reachable at. */
     readonly servers?: OpenApiDocument["servers"];
+    /**
+     * How the application's errors look, when not like the framework's
+     * envelope — for an application whose `onError` hook answers in a format
+     * of its own. The framework's failures, the hooks' refusals and the
+     * routes' own envelopes are then described in it.
+     *
+     * @example `{ code, message }`, discriminated on `code`
+     * ```ts
+     * openapi(app, {
+     *   info,
+     *   errors: {
+     *     schema: ({ error, message, fields }) => ({
+     *       type: "object",
+     *       required: ["code", "message", ...Object.keys(fields)],
+     *       properties: {
+     *         code: error ? { type: "string", const: error } : { type: "string" },
+     *         message: { type: "string", ...(message ? { examples: [message] } : {}) },
+     *         ...fields,
+     *       },
+     *     }),
+     *     discriminator: "code",
+     *   },
+     * });
+     * ```
+     */
+    readonly errors?: ErrorFormat;
 }
 /**
  * What the generator could not describe faithfully.

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,eAAe,CAAC;AAIrE,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CAsF1E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,eAAe,CAAC;AAErE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK/C,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAE9C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CA8F1E"}