@gaganref/confect-core 10.3.1-fork.7 → 10.3.1-fork.70

package/src/Http.ts

@@ -7,7 +7,7 @@ import * as SchemaAST from "effect/SchemaAST";
 import type * as HttpApi from "effect/http-api/HttpApi";
 import * as HttpApiBuilder from "effect/http-api/HttpApiBuilder";
 import type * as HttpApiGroup from "effect/http-api/HttpApiGroup";
-import * as HttpApiScalar from "effect/http-api/HttpApiScalar";
+import { scalarDocs } from "./internal/scalarDocs.js";
 import * as App from "./App.js";
 
 const TypeId = "~@confect/core/Http";
@@ -57,10 +57,7 @@ export const make = <
   const routes =
     options.docs === undefined
       ? api
-      : Layer.merge(
-          api,
-          HttpApiScalar.layerCdn(options.api, { path: options.docs }),
-        );
+      : Layer.merge(api, scalarDocs(options.api, options.docs));
   const http: Http<HttpApi.HttpApi<Id, Groups>, typeof routes> = {
     [TypeId]: TypeId,
     api: options.api,
@@ -73,10 +70,7 @@ export const make = <
 export const isHttp = (u: unknown): u is Any =>
   Predicate.hasProperty(u, TypeId) && u[TypeId] === TypeId;
 
-export type Owner =
-  | { readonly kind: "app" }
-  | { readonly kind: "docs" }
-  | { readonly kind: "mount"; readonly mount: string };
+export type Owner = { readonly kind: "app" } | { readonly kind: "docs" };
 
 export interface Route {
   readonly method: string;
@@ -104,7 +98,7 @@ export class DuplicateRoute extends Data.TaggedError("DuplicateRoute")<{
   readonly second: Owner;
 }> {
   override get message(): string {
-    return `${this.method} ${this.path} is declared twice (${ownerLabel(this.first)} and ${ownerLabel(this.second)}).`;
+    return `${this.method} ${this.path} is declared twice (${this.first.kind} and ${this.second.kind}).`;
   }
 }
 
@@ -124,9 +118,6 @@ export type RouteError =
   | DuplicateRoute
   | OverlappingMountPrefixes;
 
-const ownerLabel = (owner: Owner): string =>
-  owner.kind === "mount" ? `mount "${owner.mount}"` : owner.kind;
-
 const trimSlash = (prefix: string): string =>
   prefix.length > 1 && prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
 
@@ -160,14 +151,10 @@ interface KeyedRoute {
   readonly key: string;
 }
 
-const apiRoutes = (
-  api: App.Api,
-  prefix: string,
-  owner: Owner,
-): ReadonlyArray<KeyedRoute> =>
+const apiRoutes = (api: App.Api, owner: Owner): ReadonlyArray<KeyedRoute> =>
   Object.values<HttpApiGroup.Top>(api.groups).flatMap((group) =>
     Object.values(group.endpoints).map((endpoint) => {
-      const path = prefix + endpoint.path;
+      const path = endpoint.path;
       const declared = paramNames(endpoint.params);
       return {
         route: { method: endpoint.method, path, owner },
@@ -177,20 +164,19 @@ const apiRoutes = (
   );
 
 /**
- * Every HTTP route the backend serves: the app's api, its docs page and each
- * mount's api under its prefix. Fails when an app route or the docs page is at
- * or under a mount's prefix (Convex accepts that and lets the app route
- * silently shadow the component's), when two routes share a method and path, or
- * when two mount prefixes overlap.
+ * The backend's own HTTP routes and docs page. Fails when a route is at or
+ * under a mount's prefix (Convex accepts that and lets the app route silently
+ * shadow the component's), when two routes share a method and path, or when two
+ * mount prefixes overlap.
  */
 export const routes = (
   app: App.Any,
   http?: Any,
 ): Result.Result<ReadonlyArray<Route>, RouteError> => {
-  const mounts = App.mounts(app).flatMap(({ name, httpPrefix, api }) =>
+  const mounts = App.mounts(app).flatMap(({ name, httpPrefix }) =>
     httpPrefix === undefined
       ? []
-      : [{ name, httpPrefix: trimSlash(httpPrefix), api }],
+      : [{ name, httpPrefix: trimSlash(httpPrefix) }],
   );
 
   for (const [index, first] of mounts.entries()) {
@@ -213,7 +199,7 @@ export const routes = (
     http === undefined
       ? []
       : [
-          ...apiRoutes(http.api, "", { kind: "app" }),
+          ...apiRoutes(http.api, { kind: "app" }),
           ...(http.docs === undefined
             ? []
             : [
@@ -244,16 +230,8 @@ export const routes = (
     }
   }
 
-  const all = [
-    ...own,
-    ...mounts.flatMap(({ name, httpPrefix, api }) =>
-      api === undefined
-        ? []
-        : apiRoutes(api, httpPrefix, { kind: "mount", mount: name }),
-    ),
-  ];
   const seen = new Map<string, Route>();
-  for (const { route, key } of all) {
+  for (const { route, key } of own) {
     const previous = seen.get(key);
     if (previous !== undefined) {
       return Result.fail(
@@ -267,5 +245,5 @@ export const routes = (
     }
     seen.set(key, route);
   }
-  return Result.succeed(all.map(({ route }) => route));
+  return Result.succeed(own.map(({ route }) => route));
 };

package/src/ManifestSection.ts

@@ -0,0 +1,74 @@
+import type * as FunctionSpec from "./FunctionSpec.js";
+import type * as MiddlewareSpec from "./MiddlewareSpec.js";
+
+export interface Data<Value = unknown> {
+  readonly format: number;
+  readonly functions: Readonly<Record<string, Value>>;
+}
+
+/**
+ * What codegen hands a section's `render`: the exports of each `confect/` file
+ * it matched, every registered function with the spec file declaring it, and
+ * each mounted component with the specifier of its definition.
+ */
+export interface GenerateInput {
+  readonly modules: ReadonlyArray<{
+    readonly relativePath: string;
+    readonly exports: Readonly<Record<string, unknown>>;
+  }>;
+  readonly functions: ReadonlyArray<{
+    readonly path: string;
+    readonly source: string;
+  }>;
+  readonly mounts: ReadonlyArray<{
+    readonly name: string;
+    readonly definition: string;
+  }>;
+}
+
+export interface Generate {
+  readonly file: string;
+  match(relativePath: string): boolean;
+  render(input: GenerateInput): {
+    readonly contents: string;
+    readonly errors: ReadonlyArray<string>;
+  };
+}
+
+/**
+ * What codegen hands a section's `summarize`: the `confect/` files its
+ * `generate` matched, and each function's description by path.
+ */
+export interface SummarizeInput<Value = unknown> {
+  readonly modules: GenerateInput["modules"];
+  readonly functions: Readonly<Record<string, Value>>;
+}
+
+export interface ManifestSection<
+  Value = unknown,
+  Data_ extends { readonly format: number } = Data<Value>,
+> {
+  readonly owner: string;
+  readonly format: number;
+  describe(input: {
+    readonly path: string;
+    readonly spec: FunctionSpec.AnyWithProps;
+    readonly middleware: ReadonlyArray<MiddlewareSpec.AnyMiddlewareSpec>;
+  }): Value;
+  summarize?(input: SummarizeInput<Value>): Data_;
+  check?(
+    next: Data_,
+    previous: unknown,
+  ): {
+    readonly errors: ReadonlyArray<string>;
+    readonly notes: ReadonlyArray<string>;
+  };
+  readonly generate?: Generate;
+}
+
+export type Any = ManifestSection<unknown, { readonly format: number }>;
+
+export interface Entry {
+  readonly key: string;
+  readonly section: Any;
+}

package/src/Profile.ts

@@ -0,0 +1,141 @@
+import type * as Schema from "effect/Schema";
+import type * as FunctionProvenance from "./FunctionProvenance.js";
+import type * as MiddlewareSpec from "./MiddlewareSpec.js";
+
+/**
+ * A type-level function from a function's name and args fields to the fields a
+ * profile's builders require. Read `this["Name"]` and `this["Args"]` directly
+ * in `Type`, passing them to a type alias; a nested object type cannot name
+ * `this`.
+ */
+export interface Fields {
+  readonly Name: string;
+  // `unknown`, not `ArgsFields`: an index signature here would leak into
+  // `keyof this["Args"]`.
+  readonly Args: unknown;
+  readonly Type: object;
+}
+
+export interface NoFields extends Fields {
+  readonly Type: {};
+}
+
+export type Apply<
+  Fields_ extends Fields,
+  Name_ extends string,
+  Args_,
+> = (Fields_ & { readonly Name: Name_; readonly Args: Args_ })["Type"];
+
+/**
+ * A base profile's fields and its extension's, for one function.
+ */
+export interface Both<
+  Base extends Fields,
+  Extension extends Fields,
+> extends Fields {
+  readonly Type: Apply<Base, this["Name"], this["Args"]> &
+    Apply<Extension, this["Name"], this["Args"]>;
+}
+
+/**
+ * What a profile callback sees. `args` stays a thunk.
+ */
+export interface Info<FieldsType> {
+  readonly name: string;
+  readonly description?: string;
+  readonly args: () => FunctionProvenance.ArgsFields;
+  readonly fields: "description" extends keyof FieldsType
+    ? Omit<FieldsType, "description">
+    : FieldsType;
+}
+
+export interface Attachment<
+  MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec,
+  FieldsType,
+> {
+  readonly spec: MiddlewareSpec_;
+  readonly options: (
+    info: Info<FieldsType>,
+  ) => MiddlewareSpec.Options<MiddlewareSpec_>;
+}
+
+/**
+ * A middleware without options has none to compute and is attached at most
+ * once, so it joins a profile's list directly.
+ */
+type TakesOptions<MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec> = [
+  MiddlewareSpec.WithoutOptions<MiddlewareSpec_>,
+] extends [never]
+  ? unknown
+  : MiddlewareSpec.AttachmentError<`Middleware "${MiddlewareSpec.Key<MiddlewareSpec_>}" takes no options, so list it without Profile.attach`>;
+
+/**
+ * Attach a middleware that takes options to every function a profile builds,
+ * with options computed from each function's fields.
+ */
+export const attach = <
+  MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec,
+  FieldsType,
+>(
+  spec: MiddlewareSpec_ & TakesOptions<MiddlewareSpec_>,
+  options: (
+    info: Info<FieldsType>,
+  ) => MiddlewareSpec.Options<NoInfer<MiddlewareSpec_>>,
+): Attachment<MiddlewareSpec_, FieldsType> => ({ spec, options });
+
+/**
+ * A type function for a schema wrapper, applied to each declared codec.
+ */
+export interface SchemaTransform {
+  readonly Input: Schema.Codec<unknown, unknown>;
+  readonly Type: Schema.Codec<any, any>;
+}
+
+/**
+ * Args wrappers transform the declared field map, before Struct composition.
+ */
+export interface ArgsTransform {
+  readonly Input: unknown;
+  readonly Type: FunctionProvenance.ArgsFields;
+}
+
+export interface Transforms {
+  readonly args?: ArgsTransform;
+  readonly returns?: SchemaTransform;
+  readonly item?: SchemaTransform;
+  readonly error?: SchemaTransform;
+}
+
+export type Transform<T, Input> = (T & { readonly Input: Input })["Type" &
+  keyof T];
+
+/**
+ * Error wrappers opt into Schema.Never when no error thunk was declared.
+ */
+export type Wrappers<T extends Transforms, FieldsType> = {
+  readonly [K in keyof T]-?: K extends keyof Transforms
+    ? <
+        Input extends (K extends "args"
+          ? FunctionProvenance.ArgsFields
+          : Schema.Codec<any, any>),
+      >(
+        thunk: () => Input,
+        info: Info<FieldsType>,
+      ) => () => Transform<T[K], Input>
+    : never;
+} & { readonly [K in Exclude<keyof Transforms, keyof T>]?: never };
+
+type NonemptyError<T extends Transforms> = T extends {
+  readonly error: infer E extends SchemaTransform;
+}
+  ? [Transform<E, typeof Schema.Never>["Type"]] extends [never]
+    ? MiddlewareSpec.AttachmentError<"Profile error wrapper must add an error to Schema.Never">
+    : unknown
+  : unknown;
+
+export type SchemaConfig<T extends Transforms, FieldsType> = ([
+  keyof T,
+] extends [never]
+  ? { readonly schemas?: never }
+  : { readonly schemas: Wrappers<T, FieldsType> }) &
+  NonemptyError<T>;

package/src/Ref.ts

@@ -6,7 +6,7 @@ import type {
   PaginationOptions,
   PaginationResult,
 } from "convex/server";
-import { getFunctionAddress, makeFunctionReference } from "convex/server";
+import { getFunctionAddress } from "convex/server";
 import type { Value } from "convex/values";
 import { ConvexError } from "convex/values";
 import * as Effect from "effect/Effect";
@@ -18,6 +18,7 @@ import type * as FunctionProvenance from "./FunctionProvenance.js";
 import type * as FunctionSpec from "./FunctionSpec.js";
 import * as Lazy from "./Lazy.js";
 import * as MiddlewareSpec from "./MiddlewareSpec.js";
+import { getFunctionReference } from "./RefInternal.js";
 import type * as RuntimeAndFunctionType from "./RuntimeAndFunctionType.js";
 
 export const TypeId = "~@confect/core/Ref";
@@ -41,7 +42,9 @@ export interface Base<
     : (args: Args_) => void;
   readonly "~Returns": Returns_;
   readonly "~Error": Error_;
+  readonly functionType?: RuntimeAndFunctionType_["functionType"];
   readonly convexFunctionName: string;
+  readonly reservedArgument?: string;
   /**
    * Preserved for component references and function handles, which have no
    * local name.
@@ -447,14 +450,19 @@ export const make = <
         ({
           [TypeId]: TypeId,
           _tag: "Convex",
+          functionType: functionSpec.runtimeAndFunctionType.functionType,
           convexFunctionName,
         }) as Any,
     ),
     Match.tag("Confect", (provenance): Any =>
-      fromProvenance(convexFunctionName, provenance, [
-        ...groupMiddlewareAttachments,
-        ...functionSpec.middlewareAttachments,
-      ]),
+      fromProvenance(
+        convexFunctionName,
+        provenance,
+        [...groupMiddlewareAttachments, ...functionSpec.middlewareAttachments],
+        undefined,
+        functionSpec.runtimeAndFunctionType.functionType,
+        functionSpec.reservedArgument,
+      ),
     ),
     Match.exhaustive,
   ) as FromFunctionSpec<
@@ -476,11 +484,15 @@ export const fromProvenance = (
   provenance: FunctionProvenance.AnyConfect,
   middlewareAttachments: ReadonlyArray<MiddlewareAttachment.MiddlewareAttachment>,
   functionReference?: ConvexFunctionReference<any, any>,
+  functionType?: "query" | "mutation" | "action",
+  reservedArgument?: string,
 ): AnyConfect => {
   const ref = {
     [TypeId]: TypeId as TypeId,
     _tag: "Confect" as const,
+    ...(functionType === undefined ? {} : { functionType }),
     convexFunctionName,
+    ...(reservedArgument === undefined ? {} : { reservedArgument }),
     ...(functionReference === undefined ? {} : { functionReference }),
     kind: provenance.kind,
     middlewareAttachments,
@@ -501,27 +513,6 @@ export const fromProvenance = (
 export const getConvexFunctionName = (ref: Any): string =>
   ref.convexFunctionName;
 
-const functionReferenceCache = new Map<string, FunctionReference<Any>>();
-
-export const getFunctionReference = <Ref_ extends Any>(
-  ref: Ref_,
-): FunctionReference<Ref_> => {
-  if (ref.functionReference !== undefined) {
-    return ref.functionReference as FunctionReference<Ref_>;
-  }
-  const convexFunctionName = getConvexFunctionName(ref);
-
-  const cached = functionReferenceCache.get(convexFunctionName);
-  if (cached !== undefined) {
-    return cached as FunctionReference<Ref_>;
-  }
-
-  const functionReference = makeFunctionReference(convexFunctionName);
-  functionReferenceCache.set(convexFunctionName, functionReference);
-
-  return functionReference as FunctionReference<Ref_>;
-};
-
 /**
  * Adapt a native reference without assigning Confect codecs or typed errors.
  */
@@ -532,6 +523,7 @@ export const fromFunctionReference = <
   Returns_,
 >(
   functionReference: ConvexFunctionReference<Type, Visibility, Args_, Returns_>,
+  functionType?: NoInfer<Type>,
 ): ConvexRef<
   Extract<
     RuntimeAndFunctionType.RuntimeAndFunctionType,
@@ -545,6 +537,7 @@ export const fromFunctionReference = <
   return {
     [TypeId]: TypeId,
     _tag: "Convex",
+    ...(functionType === undefined ? {} : { functionType }),
     convexFunctionName:
       address.name ??
       address.reference ??

package/src/RefInternal.ts

@@ -0,0 +1,26 @@
+import { makeFunctionReference } from "convex/server";
+import type * as Ref from "./Ref.js";
+
+const functionReferenceCache = new Map<
+  string,
+  Ref.FunctionReference<Ref.Any>
+>();
+
+export const getFunctionReference = <Ref_ extends Ref.Any>(
+  ref: Ref_,
+): Ref.FunctionReference<Ref_> => {
+  if (ref.functionReference !== undefined) {
+    return ref.functionReference as Ref.FunctionReference<Ref_>;
+  }
+  const convexFunctionName = ref.convexFunctionName;
+
+  const cached = functionReferenceCache.get(convexFunctionName);
+  if (cached !== undefined) {
+    return cached as Ref.FunctionReference<Ref_>;
+  }
+
+  const functionReference = makeFunctionReference(convexFunctionName);
+  functionReferenceCache.set(convexFunctionName, functionReference);
+
+  return functionReference as Ref.FunctionReference<Ref_>;
+};

package/src/SchemaToValidator.ts

@@ -1,4 +1,6 @@
 import * as IdScope from "./IdScope.js";
+import type * as Callback from "./Callback.js";
+import { CallbackContract } from "./internal/annotations.js";
 import type {
   GenericId as ConvexGenericId,
   PropertyValidators,
@@ -46,10 +48,24 @@ import type {
 export const compileArgsSchema = <ConfectValue, ConvexValue>(
   argsSchema: Schema.Codec<ConfectValue, ConvexValue>,
   scope: IdScope.IdScope = IdScope.app,
+  reservedArgument?: string,
+  functionName?: string,
 ): PropertyValidators => {
   const ast = Schema.toEncoded(argsSchema).ast;
 
-  return pipe(
+  const validators = Effect.runSync(compileArgsAst(ast, scope));
+  if (reservedArgument === undefined) return validators;
+  if (Object.hasOwn(validators, reservedArgument)) {
+    throw new ReservedArgumentCollision({
+      functionName,
+      argument: reservedArgument,
+    });
+  }
+  return { ...validators, [reservedArgument]: v.optional(v.any()) };
+};
+
+const compileArgsAst = (ast: SchemaAST.AST, scope: IdScope.IdScope) =>
+  pipe(
     ast,
     Match.value,
     Match.tag("Objects", (objectsAst) =>
@@ -58,9 +74,18 @@ export const compileArgsSchema = <ConfectValue, ConvexValue>(
         : Effect.fail(new IndexSignaturesAreNotSupportedError()),
     ),
     Match.orElse(() => Effect.fail(new TopLevelMustBeObjectError())),
-    Effect.runSync,
   );
-};
+
+export class ReservedArgumentCollision extends Data.TaggedError(
+  "ReservedArgumentCollision",
+)<{
+  readonly functionName: string | undefined;
+  readonly argument: string;
+}> {
+  override get message() {
+    return `${this.functionName} declares the argument "${this.argument}", which its profile reserves. Rename the argument.`;
+  }
+}
 
 // Returns
 
@@ -313,6 +338,7 @@ export const compileAst = (
   scope: IdScope.IdScope = IdScope.app,
 ): Effect.Effect<
   Validator<any, any, any>,
+  | TopLevelMustBeObjectError
   | UnsupportedSchemaTypeError
   | UnsupportedPropertySignatureKeyTypeError
   | IndexSignaturesAreNotSupportedError
@@ -320,8 +346,23 @@ export const compileAst = (
   | OptionalTupleElementsAreNotSupportedError
   | EmptyTupleIsNotSupportedError
   | EmptyUnionIsNotSupportedError
-> =>
-  isRecursive(ast)
+> => {
+  const contract = SchemaAST.resolveAt<Callback.Any>(CallbackContract)(ast);
+  if (contract !== undefined) {
+    return Effect.gen(function* () {
+      const args = yield* compileArgsAst(
+        Schema.toEncoded(contract.functionProvenance.args).ast,
+        scope,
+      );
+      const returns = yield* compileAst(
+        Schema.toEncoded(contract.functionProvenance.returns).ast,
+        false,
+        scope,
+      );
+      return v.function({ fnType: contract.functionType, args, returns });
+    });
+  }
+  return isRecursive(ast)
     ? Effect.succeed(v.any())
     : pipe(
         ast,
@@ -400,6 +441,7 @@ export const compileAst = (
         ),
         Match.exhaustive,
       );
+};
 
 const handleUnion = (
   { types }: SchemaAST.Union,

package/src/index.ts

@@ -1,3 +1,4 @@
+export * as ActionCall from "./ActionCall.js";
 export * as Callback from "./Callback.js";
 export * as FunctionProvenance from "./FunctionProvenance.js";
 export * as FunctionSpec from "./FunctionSpec.js";
@@ -13,11 +14,13 @@ export * as GroupSpec from "./GroupSpec.js";
 export * as Identifier from "./Identifier.js";
 export * as Lazy from "./Lazy.js";
 export * as Manifest from "./Manifest.js";
+export * as ManifestSection from "./ManifestSection.js";
 export * as MiddlewareAttachment from "./MiddlewareAttachment.js";
 export * as MiddlewareSpec from "./MiddlewareSpec.js";
 export * as PaginationError from "./PaginationError.js";
 export * as PaginationOptions from "./PaginationOptions.js";
 export * as PaginationResult from "./PaginationResult.js";
+export * as Profile from "./Profile.js";
 export * as Ref from "./Ref.js";
 export * as Refs from "./Refs.js";
 export * as RuntimeAndFunctionType from "./RuntimeAndFunctionType.js";

package/src/internal/annotations.ts

@@ -0,0 +1 @@
+export const CallbackContract = "~@confect/core/Callback/Contract";

package/src/internal/scalarDocs.ts

@@ -0,0 +1,72 @@
+import * as Effect from "effect/Effect";
+import * as HttpRouter from "effect/http/HttpRouter";
+import * as HttpServerResponse from "effect/http/HttpServerResponse";
+import type * as HttpApi from "effect/http-api/HttpApi";
+import type * as HttpApiGroup from "effect/http-api/HttpApiGroup";
+import * as OpenApi from "effect/http-api/OpenApi";
+
+const escape = (value: string) =>
+  value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+
+const escapeAttribute = (value: string) =>
+  escape(value).replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+
+const escapeJson = (value: unknown) =>
+  JSON.stringify(value)
+    .replaceAll("<", "\\u003c")
+    .replaceAll("\u2028", "\\u2028")
+    .replaceAll("\u2029", "\\u2029");
+
+// WORKAROUND: Effect 4.0.6's HttpApiScalar module imports its inline Scalar
+// script dynamically, and Convex's bundler then splits a schema that reaches it
+// into an imported chunk, which Convex refuses. This copies `layerCdn`'s page
+// byte for byte. Remove when `checkSchemaBundle.mjs` passes with
+// `HttpApiScalar.layerCdn` restored.
+export const scalarDocs = <
+  Id extends string,
+  Groups extends HttpApiGroup.Constraint,
+>(
+  api: HttpApi.HttpApi<Id, Groups>,
+  path: `/${string}`,
+) =>
+  HttpRouter.use((router) => {
+    let response: HttpServerResponse.HttpServerResponse | undefined;
+    return router.add(
+      "GET",
+      path,
+      Effect.sync(() => {
+        if (response !== undefined) return response;
+        const spec = OpenApi.fromApi(api);
+        const description = (tag: string) =>
+          !spec.info.description
+            ? ""
+            : `<meta name="${tag}" content="${escapeAttribute(spec.info.description)}"/>`;
+        response = HttpServerResponse.html(`<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>${escape(spec.info.title)}</title>
+    ${description("description")}
+    ${description("og:description")}
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="api-reference-container"></div>
+    <script src="${escapeAttribute("https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest/dist/browser/standalone.min.js")}" crossorigin></script>
+    <script>
+      window.Scalar.createApiReference(document.getElementById('api-reference-container'), {
+        ...${escapeJson({ _integration: "html" })},
+        content: ${escapeJson(spec)}
+      })
+    </script>
+  </body>
+</html>`);
+        return response;
+      }),
+    );
+  });