@nestia/editor 14.0.0 → 14.0.2

package/lib/internal/NestiaEditorComposer.mjs

@@ -21,7 +21,8 @@ let NestiaEditorComposer;
 			data: {
 				files: props.files,
 				openFile: config.openFile,
-				startScript: config.startScript
+				startScript: config.startScript,
+				skipped: []
 			}
 		};
 		const result = await migrate.NestiaMigrateApplication.validate(props.document);
@@ -41,7 +42,12 @@ let NestiaEditorComposer;
 			data: {
 				files,
 				openFile: config.openFile,
-				startScript: config.startScript
+				startScript: config.startScript,
+				skipped: app.getData().errors.map((error) => ({
+					method: error.method.toUpperCase(),
+					path: error.path,
+					messages: error.messages
+				}))
 			}
 		};
 	};

package/lib/internal/NestiaEditorFileUploader.d.ts

@@ -1,7 +1,28 @@
 import { OpenApiV3, OpenApiV3_1, SwaggerV2 } from "@typia/interface";
+/**
+ * A file picker that reads an OpenAPI document from a JSON or YAML file.
+ *
+ * The last chosen file is read and parsed by its extension, and the result is passed to `onChange` with the parsed document, or with an error message when the content does not parse. Clearing the selection reports `null` for both.
+ *
+ * A file-reading failure rejects the uploader callback before parsing; it is not reported through `onChange`. Parsing reports content without validating its OpenAPI shape; the composer performs that validation.
+ *
+ * @evidence contracts/common.md#principled-implementation The file is decoded as UTF-8 text and parsed with `JSON.parse` for a `json` extension and with `js-yaml` otherwise; a parse failure is reported with the message for the format, and only the last chosen file is kept, matching the single-file picker.
+ * @evidence contracts/common.md#clear-and-simple-design One component wraps the third-party uploader and owns only reading and parsing; the form around it belongs to `NestiaEditorUploader`.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The parser is chosen by the file extension alone; no document name or content is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states which file is read, how it is parsed, and what `onChange` receives in each case.
+ */
 export declare function NestiaEditorFileUploader(props: NestiaEditorFileUploader.IProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Properties of {@link NestiaEditorFileUploader}.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the property type of the component with the same name.
+ * @evidence contracts/common.md#clear-and-simple-design It contains one interface with one callback.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It adds no behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment names the component the properties belong to.
+ */
 export declare namespace NestiaEditorFileUploader {
     interface IProps {
+        /** Receives parsed file content, parse failures, or null/null when cleared. */
         onChange: (swagger: SwaggerV2.IDocument | OpenApiV3.IDocument | OpenApiV3_1.IDocument | null, error: string | null) => void;
     }
 }

package/lib/internal/NestiaEditorFileUploader.js

@@ -17,6 +17,18 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const js_yaml_1 = require("js-yaml");
 const react_1 = __importDefault(require("react"));
 const react_mui_fileuploader_1 = __importDefault(require("react-mui-fileuploader"));
+/**
+ * A file picker that reads an OpenAPI document from a JSON or YAML file.
+ *
+ * The last chosen file is read and parsed by its extension, and the result is passed to `onChange` with the parsed document, or with an error message when the content does not parse. Clearing the selection reports `null` for both.
+ *
+ * A file-reading failure rejects the uploader callback before parsing; it is not reported through `onChange`. Parsing reports content without validating its OpenAPI shape; the composer performs that validation.
+ *
+ * @evidence contracts/common.md#principled-implementation The file is decoded as UTF-8 text and parsed with `JSON.parse` for a `json` extension and with `js-yaml` otherwise; a parse failure is reported with the message for the format, and only the last chosen file is kept, matching the single-file picker.
+ * @evidence contracts/common.md#clear-and-simple-design One component wraps the third-party uploader and owns only reading and parsing; the form around it belongs to `NestiaEditorUploader`.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The parser is chosen by the file extension alone; no document name or content is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states which file is read, how it is parsed, and what `onChange` receives in each case.
+ */
 function NestiaEditorFileUploader(props) {
     const [elements, setElements] = react_1.default.useState([]);
     const onChange = (array) => __awaiter(this, void 0, void 0, function* () {

package/lib/internal/NestiaEditorFileUploader.js.map

@@ -1 +1 @@
-{"version":3,"file":"NestiaEditorFileUploader.js","sourceRoot":"","sources":["../../src/internal/NestiaEditorFileUploader.tsx"],"names":[],"mappings":";;;;;;;;;;;;;;;;AACA,qCAA+B;AAC/B,kDAA0B;AAC1B,oFAA4E;AAE5E,kCACE,KAAsC;IAEtC,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,eAAK,CAAC,QAAQ,CAAsB,EAAE,CAAC,CAAC;IACxE,MAAM,QAAQ,GAAG,CAAO,KAA0B,EAAE,EAAE;QACpD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAsB,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;QACzD,MAAM,MAAM,GAAgB,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QACrD,MAAM,OAAO,GAAW,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACzD,MAAM,SAAS,GAAoB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAEjD,CAAC;QAEX,IAAI,CAAC;YACH,MAAM,IAAI,GAIR,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAA,cAAI,EAAC,OAAO,CAAC,CAAC;YAC7D,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC7B,CAAC;mBAAO,CAAC;YACP,KAAK,CAAC,QAAQ,CACZ,IAAI,EACJ,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,mBAAmB,CACjE,CAAC;YACF,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5C,CAAC,CAAA,CAAC;IACF,OAAO,CACL,uBAAC,gCAAU,IACT,YAAY,EAAE,QAAQ,EACtB,aAAa,EAAE,QAAQ,EACvB,YAAY,EAAC,cAAc,EAC3B,SAAS,EAAE,KAAK,EAChB,SAAS,EAAE,KAAK,EAChB,cAAc,EAAE,CAAC,EACjB,KAAK,EAAC,uBAAuB,EAC7B,MAAM,EAAC,mCAAmC,EAC1C,WAAW,EAAC,YAAY,EACxB,UAAU,EAAC,kCAAkC,EAC7C,iBAAiB,EAAC,OAAO,GACzB,CACH,CAAC;AACJ,CAAC"}
+{"version":3,"file":"NestiaEditorFileUploader.js","sourceRoot":"","sources":["../../src/internal/NestiaEditorFileUploader.tsx"],"names":[],"mappings":";;;;;;;;;;;;;;;;AACA,qCAA+B;AAC/B,kDAA0B;AAC1B,oFAA4E;AAE5E;;;;;;;;;;;GAWG;AACH,kCACE,KAAsC;IAEtC,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,eAAK,CAAC,QAAQ,CAAsB,EAAE,CAAC,CAAC;IACxE,MAAM,QAAQ,GAAG,CAAO,KAA0B,EAAE,EAAE;QACpD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAsB,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;QACzD,MAAM,MAAM,GAAgB,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QACrD,MAAM,OAAO,GAAW,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACzD,MAAM,SAAS,GAAoB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAEjD,CAAC;QAEX,IAAI,CAAC;YACH,MAAM,IAAI,GAIR,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAA,cAAI,EAAC,OAAO,CAAC,CAAC;YAC7D,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC7B,CAAC;mBAAO,CAAC;YACP,KAAK,CAAC,QAAQ,CACZ,IAAI,EACJ,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,mBAAmB,CACjE,CAAC;YACF,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5C,CAAC,CAAA,CAAC;IACF,OAAO,CACL,uBAAC,gCAAU,IACT,YAAY,EAAE,QAAQ,EACtB,aAAa,EAAE,QAAQ,EACvB,YAAY,EAAC,cAAc,EAC3B,SAAS,EAAE,KAAK,EAChB,SAAS,EAAE,KAAK,EAChB,cAAc,EAAE,CAAC,EACjB,KAAK,EAAC,uBAAuB,EAC7B,MAAM,EAAC,mCAAmC,EAC1C,WAAW,EAAC,YAAY,EACxB,UAAU,EAAC,kCAAkC,EAC7C,iBAAiB,EAAC,OAAO,GACzB,CACH,CAAC;AACJ,CAAC"}

package/lib/internal/NestiaEditorFileUploader.mjs

@@ -3,6 +3,18 @@ import { load } from "js-yaml";
 import { jsx } from "react/jsx-runtime";
 import FileUpload from "react-mui-fileuploader";
 //#region src/internal/NestiaEditorFileUploader.tsx
+/**
+* A file picker that reads an OpenAPI document from a JSON or YAML file.
+*
+* The last chosen file is read and parsed by its extension, and the result is passed to `onChange` with the parsed document, or with an error message when the content does not parse. Clearing the selection reports `null` for both.
+*
+* A file-reading failure rejects the uploader callback before parsing; it is not reported through `onChange`. Parsing reports content without validating its OpenAPI shape; the composer performs that validation.
+*
+* @evidence contracts/common.md#principled-implementation The file is decoded as UTF-8 text and parsed with `JSON.parse` for a `json` extension and with `js-yaml` otherwise; a parse failure is reported with the message for the format, and only the last chosen file is kept, matching the single-file picker.
+* @evidence contracts/common.md#clear-and-simple-design One component wraps the third-party uploader and owns only reading and parsing; the form around it belongs to `NestiaEditorUploader`.
+* @evidence contracts/common.md#prohibited-implementation-shortcuts The parser is chosen by the file extension alone; no document name or content is special-cased.
+* @evidence contracts/common.md#meaningful-documentation The comment states which file is read, how it is parsed, and what `onChange` receives in each case.
+*/
 function NestiaEditorFileUploader(props) {
 	const [elements, setElements] = React.useState([]);
 	const onChange = async (array) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/editor",
-  "version": "14.0.0",
+  "version": "14.0.2",
   "main": "lib/index.js",
   "exports": {
     ".": {
@@ -43,8 +43,8 @@
     "js-yaml": "^4.3.1",
     "prettier": "^3.8.1",
     "react-mui-fileuploader": "^0.5.2",
-    "typia": "^15.0.0",
-    "@nestia/migrate": "^14.0.0"
+    "typia": "15.0.0",
+    "@nestia/migrate": "^14.0.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.13.0",
@@ -82,10 +82,11 @@
   "scripts": {
     "build": "npm run build:static && npm run build:lib",
     "build:static": "rimraf dist && ttsc && vite build",
-    "build:lib": "rimraf lib && ttsc --project tsconfig.lib.json && tsc --project tsconfig.lib.json --emitDeclarationOnly && rolldown -c && node ../../deploy/verify-package-exports.cjs --esm-static",
+    "build:lib": "rimraf lib && ttsc --project tsconfig.lib.json && tsc --project tsconfig.lib.json --emitDeclarationOnly && rolldown -c",
     "dev": "vite",
     "lint": "eslint .",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "evidence": "evidence"
   },
   "types": "lib/index.d.ts",
   "module": "lib/index.mjs"

package/src/NestiaEditorApplication.tsx

@@ -2,8 +2,19 @@ import { Typography } from "@mui/material";
 import React from "react";
 
 import { NestiaEditorIframe } from "./NestiaEditorIframe";
+import { NESTIA_EDITOR_DEFAULT_PACKAGE } from "./internal/NestiaEditorDefaultPackage";
 import { NestiaEditorUploader } from "./NestiaEditorUploader";
 
+/**
+ * The static editor page: converts an OpenAPI document into a downloadable project.
+ *
+ * The page reads its settings from the query string (`url`, `mode`, `package`, `keyword`, `simulate`, `e2e`) and from `window` globals the served `index.html` sets. It renders the iframe flow when a document location is given, or when `swagger.json` or `swagger.yaml` is served beside the page, and the uploader otherwise. The `uploader` query key forces the uploader.
+ *
+ * @evidence contracts/common.md#principled-implementation An explicit query URL is forwarded to the iframe, which loads it and reports a fetch error. Without one, swagger.json and then swagger.yaml are probed for HTTP 200; absent or failed lookup falls back to the uploader. Parsed generation options, including keyword, are passed to the iframe rather than replaced by its direct-component defaults.
+ * @evidence contracts/common.md#clear-and-simple-design One component chooses between two existing components; the query and probing logic stays in the private `getAsset` and `findSwagger`, and option parsing lives in one place.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The package name default comes from the shared constant, and no document name, host, or fixture is special-cased; booleans accept only `true` and `1`, as the query contract states.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the page does, where each setting comes from, the lookup order, and the `uploader` override.
+ */
 export function NestiaEditorApplication() {
   const [ready, setReady] = React.useState(false);
   const [asset, setAsset] = React.useState<IAsset | null>(null);
@@ -24,6 +35,7 @@ export function NestiaEditorApplication() {
     <NestiaEditorIframe
       swagger={asset.url}
       package={asset.package}
+      keyword={asset.keyword}
       simulate={asset.simulate}
       e2e={asset.e2e}
       mode={asset.mode}
@@ -65,7 +77,7 @@ async function getAsset(): Promise<IAsset | null> {
   const e2e: boolean | string | null = query.get("e2e") ?? (window as any).e2e;
   return {
     mode: mode === "nest" ? "nest" : "sdk",
-    package: packageName ?? "@ORGANIZATION/PROJECT",
+    package: packageName ?? NESTIA_EDITOR_DEFAULT_PACKAGE,
     url,
     keyword:
       keyword !== null
@@ -80,8 +92,12 @@ async function getAsset(): Promise<IAsset | null> {
 }
 
 async function findSwagger(file: string): Promise<string | null> {
-  const response: Response = await fetch(file);
-  return response.status === 200 ? file : null;
+  try {
+    const response: Response = await fetch(file);
+    return response.status === 200 ? file : null;
+  } catch {
+    return null;
+  }
 }
 
 interface IAsset {

package/src/NestiaEditorIframe.tsx

@@ -16,7 +16,23 @@ import { IValidation } from "typia";
 
 import { NestiaEditorArchiver } from "./internal/NestiaEditorArchiver";
 import { NestiaEditorComposer } from "./internal/NestiaEditorComposer";
+import { NESTIA_EDITOR_DEFAULT_PACKAGE } from "./internal/NestiaEditorDefaultPackage";
 
+/**
+ * Composes a project from an OpenAPI document and offers it as a zip download.
+ *
+ * The component loads the document, from a URL or from the object given,
+ * generates the project in the browser, and shows the three stages as a
+ * stepper. A fetch failure or a composition failure is reported in place of the
+ * stage's progress, and the operations the composer could not convert are
+ * listed beside the download, so an incomplete project never passes for a
+ * complete one.
+ *
+ * @evidence contracts/common.md#principled-implementation The three stages run once, in order, from an effect: load the document, compose it with NestiaEditorComposer, and expose the files for download. Document-loading and composer failure results set their stage error states. Operations the composer skipped are listed with the download. Unexpected errors outside these operations are logged by the outer catch without setting an error state; only completed stages advance the stepper.
+ * @evidence contracts/common.md#clear-and-simple-design One component owns the stepper state; document loading and operation counting stay in the private `getDocument` and `aggregateOperation`, and archiving and composition are delegated to their own namespaces.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The option defaults (keyword, simulate, e2e enabled) are the documented product defaults, and the archive name comes from the shared default package constant, not from a fixture name.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the stages and how failures appear.
+ */
 export function NestiaEditorIframe(props: NestiaEditorIframe.IProps) {
   const [step, setStep] = React.useState(0);
   const [fetchError, setFetchError] = React.useState<string | null>(null);
@@ -25,8 +41,11 @@ export function NestiaEditorIframe(props: NestiaEditorIframe.IProps) {
   >({});
   const [composerError, setComposerError] = React.useState<any | null>(null);
   const [files, setFiles] = React.useState<Record<string, string> | null>(null);
+  const [skipped, setSkipped] = React.useState<NestiaEditorComposer.ISkipped[]>(
+    [],
+  );
   const archive: string = NestiaEditorArchiver.name(
-    props.package ?? "@ORGANIZATION/PROJECT",
+    props.package ?? NESTIA_EDITOR_DEFAULT_PACKAGE,
   );
 
   React.useEffect(() => {
@@ -56,7 +75,7 @@ export function NestiaEditorIframe(props: NestiaEditorIframe.IProps) {
               keyword: props.keyword ?? true,
               simulate: props.simulate ?? true,
               e2e: props.e2e ?? true,
-              package: props.package ?? "@ORGANIZATION/PROJECT",
+              package: props.package ?? NESTIA_EDITOR_DEFAULT_PACKAGE,
             });
           } catch (exp) {
             return {
@@ -73,6 +92,7 @@ export function NestiaEditorIframe(props: NestiaEditorIframe.IProps) {
 
       // READY TO DOWNLOAD
       setStep(2);
+      setSkipped(result.data.skipped);
       setFiles(result.data.files);
     })().catch((exp) => {
       console.error("unknown error", exp);
@@ -146,7 +166,7 @@ export function NestiaEditorIframe(props: NestiaEditorIframe.IProps) {
                     .toLocaleString()}
                 </li>
                 {Object.entries(operations).map(([method, count]) => (
-                  <li>
+                  <li key={method}>
                     {method}: #{count.toLocaleString()}
                   </li>
                 ))}
@@ -189,6 +209,24 @@ export function NestiaEditorIframe(props: NestiaEditorIframe.IProps) {
                   >
                     Download {archive}
                   </Button>
+                  {skipped.length !== 0 ? (
+                    <>
+                      <br />
+                      <br />
+                      <Alert severity="warning">
+                        <AlertTitle>Skipped Operations</AlertTitle>
+                        The project leaves out operations that could not be
+                        converted:
+                        <ul>
+                          {skipped.map((s) => (
+                            <li key={`${s.method} ${s.path}`}>
+                              {s.method} {s.path}: {s.messages.join(" ")}
+                            </li>
+                          ))}
+                        </ul>
+                      </Alert>
+                    </>
+                  ) : null}
                 </>
               ) : null}
             </StepContent>
@@ -198,23 +236,40 @@ export function NestiaEditorIframe(props: NestiaEditorIframe.IProps) {
     </div>
   );
 }
+/**
+ * Properties of {@link NestiaEditorIframe}.
+ *
+ * `swagger` is an OpenAPI document or the URL to fetch it from. The options
+ * mirror the generator options; `mode` is internal.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the property type of the component with the same name, so the component and its inputs are one public identity.
+ * @evidence contracts/common.md#clear-and-simple-design It contains one interface and nothing else.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It adds no behavior; the option defaults live in the component that reads them.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what `swagger` accepts and which members are internal.
+ */
 export namespace NestiaEditorIframe {
   export interface IProps {
+    /** Source document or URL loaded once when this component mounts. */
     swagger:
       | string
       | SwaggerV2.IDocument
       | OpenApiV3.IDocument
       | OpenApiV3_1.IDocument;
+
+    /** Generated package identity; defaults to @ORGANIZATION/PROJECT. */
     package?: string;
+
+    /** Enable keyword parameter objects; enabled when omitted. */
     keyword?: boolean;
+
+    /** Include SDK simulators; enabled when omitted. */
     simulate?: boolean;
+
+    /** Include generated E2E functions; enabled when omitted. */
     e2e?: boolean;
 
     /** @internal */
     mode?: "nest" | "sdk";
-
-    /** @internal */
-    files?: Record<string, string>;
   }
 }
 

package/src/NestiaEditorModule.ts

@@ -5,8 +5,57 @@ import type {
   SwaggerV2,
 } from "@typia/interface";
 import * as fs from "fs";
+import path from "path";
 
+import { NESTIA_EDITOR_DEFAULT_PACKAGE } from "./internal/NestiaEditorDefaultPackage";
+
+/**
+ * Serves the editor from a NestJS application.
+ *
+ * Call {@link setup} before `listen()` to expose the editor page, its bundle,
+ * and the OpenAPI document under a path of the application.
+ *
+ * @evidence contracts/common.md#principled-implementation The module registers static routes on the application's own HTTP adapter, so the editor needs no second server.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace with one entry point; asset reading and location resolution stay in module-private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The routes use the adapter's public `get` method, and the one read of NestJS internals is the global prefix, described at `setup`.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the entry point and that it must run before `listen()`.
+ */
 export namespace NestiaEditorModule {
+  /**
+   * Registers the editor routes on a NestJS application.
+   *
+   * The routes are `<prefix>/index.html`, the bundle under `<prefix>/assets/`,
+   * `<prefix>/swagger.json`, and redirects from `<prefix>` and `<prefix>/` to
+   * the page, where the prefix joins the application's global prefix and
+   * `path`. A document given as an object is served as is. A document given by
+   * location is fetched on the first request, after `listen()`, because a path
+   * is resolved against the address the application listens on, and the fetched
+   * document is cached; a failed fetch answers 502 and is not cached.
+   *
+   * Setup reads each page-referenced JavaScript asset once. Static setup work
+   * scales with page and asset bytes; later requests reuse the registered
+   * strings. A location-based document is fetched and serialized on demand.
+   *
+   * Each Swagger route shares one successful serialized document and one
+   * in-flight fetch. A failed fetch clears the pending promise so later
+   * requests can try again. The location and document remain fixed for that
+   * registration.
+   *
+   * The application adapter owns the registered closures and their strings for
+   * the route lifetime. Setup creates no process-global history. This API
+   * supplies no fetch cancellation or timeout, so an unresolved request remains
+   * pending until its transport settles.
+   *
+   * Built assets use Node filesystem APIs and native path joining from the
+   * installed module directory. Page script URLs are validated independently
+   * from filesystem paths. Swagger locations use URL resolution against
+   * application.getUrl.
+   *
+   * @evidence contracts/common.md#principled-implementation The prefix is built by joining the global prefix and the path and dropping empty segments, so slashes never double; the static files are read once at setup, and the swagger route is lazy for a location because the listening address, which relative locations need, does not exist before `listen()`.
+   * @evidence contracts/common.md#clear-and-simple-design One function performs the registration; reading the built page and bundle, reading the global prefix, and resolving a location are separate module-private helpers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts NestJS exposes no public getter for the global prefix, so `getGlobalPrefix` reads the internal `config.globalPrefix` and falls back to an empty prefix when it is absent; this is the single foreign-internal read, kept as a stated limitation rather than replaced by a shadow copy of the prefix.
+   * @evidence contracts/common.md#meaningful-documentation The comment lists the routes and prefix rule, explains setup versus request-time work and cached-document ownership, and states the absent timeout/cancellation limitation.
+   */
   export const setup = async (props: {
     path: string;
     application: INestApplication;
@@ -20,32 +69,21 @@ export namespace NestiaEditorModule {
     simulate?: boolean;
     e2e?: boolean;
   }): Promise<void> => {
-    const prefix: string =
-      "/" +
-      [getGlobalPrefix(props.application), props.path]
-        .join("/")
-        .split("/")
-        .filter((str) => str.length !== 0)
-        .join("/");
+    const prefix: string = [getGlobalPrefix(props.application), props.path]
+      .join("/")
+      .split("/")
+      .filter((str) => str.length !== 0)
+      .map((str) => "/" + str)
+      .join("");
     const adaptor: INestHttpAdaptor = props.application.getHttpAdapter();
+    const index: string = await getIndex(props);
     const staticFiles: IStaticFile[] = [
       {
         path: "/index.html",
         type: "text/html",
-        content: await getIndex(props),
-      },
-      {
-        path: "/swagger.json",
-        type: "application/json",
-        content: JSON.stringify(
-          typeof props.swagger === "string"
-            ? await getSwagger(props.swagger)
-            : props.swagger,
-          null,
-          2,
-        ),
+        content: index,
       },
-      await getJavaScript(),
+      ...(await getJavaScripts(index)),
     ];
     for (const f of staticFiles) {
       adaptor.get(prefix + f.path, (_: any, res: any) => {
@@ -53,7 +91,43 @@ export namespace NestiaEditorModule {
         return res.send(f.content);
       });
     }
-    for (const p of ["", "/"])
+
+    // A document given by location is read when the editor asks for it, not
+    // here: `setup()` runs before `listen()`, so the application's own path,
+    // such as `@nestjs/swagger`'s "/api-json", serves nothing yet, and a path
+    // is resolved against the address the application listens on.
+    let document: string | null =
+      typeof props.swagger === "string"
+        ? null
+        : JSON.stringify(props.swagger, null, 2);
+    let pending: Promise<string> | null = null;
+    adaptor.get(prefix + "/swagger.json", async (_: any, res: any) => {
+      try {
+        if (document === null) {
+          pending ??= (async () =>
+            JSON.stringify(
+              await getSwagger(
+                await resolveLocation(
+                  props.application,
+                  props.swagger as string,
+                ),
+              ),
+              null,
+              2,
+            ))().finally(() => {
+            pending = null;
+          });
+          document = await pending;
+        }
+      } catch (error) {
+        res.status(502);
+        res.type("text/plain");
+        return res.send(error instanceof Error ? error.message : String(error));
+      }
+      res.type("application/json");
+      return res.send(document);
+    });
+    for (const p of prefix.length === 0 ? ["/"] : ["", "/"])
       adaptor.get(prefix + p, (_: any, res: any) => {
         return res.redirect(prefix + "/index.html");
       });
@@ -98,32 +172,58 @@ const getIndex = async (props: {
     `${__dirname}/../dist/index.html`,
     "utf8",
   );
+  // Replacement functions, because a replacement string would read its dollar
+  // patterns, which a package name may legitimately contain.
   return content
+    .replace(JSON.stringify(NESTIA_EDITOR_DEFAULT_PACKAGE), () =>
+      JSON.stringify(props.package ?? NESTIA_EDITOR_DEFAULT_PACKAGE),
+    )
     .replace(
-      `"@ORGANIZATION/PROJECT"`,
-      JSON.stringify(props.package ?? "@ORGANIZATION/PROJECT"),
+      "window.simulate = false",
+      () => `window.simulate = ${!!props.simulate}`,
     )
-    .replace("window.simulate = false", `window.simulate = ${!!props.simulate}`)
-    .replace("window.e2e = false", `window.e2e = ${!!props.e2e}`);
+    .replace("window.e2e = false", () => `window.e2e = ${!!props.e2e}`);
 };
 
-const getJavaScript = async (): Promise<IStaticFile> => {
-  const directory: string[] = await fs.promises.readdir(
-    `${__dirname}/../dist/assets`,
+const getJavaScripts = async (index: string): Promise<IStaticFile[]> => {
+  const scripts: Set<string> = new Set();
+  for (const match of index.matchAll(
+    /<script\b[^>]*\bsrc\s*=\s*(["'])(.*?)\1[^>]*>/gi,
+  )) {
+    const url = new URL(match[2]!, "https://nestia.invalid/");
+    if (
+      url.origin !== "https://nestia.invalid" ||
+      url.pathname.startsWith("/assets/") === false ||
+      url.pathname.endsWith(".js") === false ||
+      url.search.length !== 0 ||
+      url.hash.length !== 0
+    )
+      throw new Error(`Unsupported editor script asset: ${match[2]}`);
+    scripts.add(url.pathname);
+  }
+  if (scripts.size === 0)
+    throw new Error("The editor page references no JavaScript asset.");
+  return Promise.all(
+    [...scripts].map(async (asset) => ({
+      path: asset,
+      type: "application/javascript",
+      content: await fs.promises.readFile(
+        path.join(__dirname, "../dist", asset.slice(1)),
+        "utf8",
+      ),
+    })),
   );
-  const path: string | undefined = directory[0];
-  if (path === undefined)
-    throw new Error("Unreachable code, no JS file exists.");
-  return {
-    path: `/assets/${path}`,
-    type: "application/javascript",
-    content: await fs.promises.readFile(
-      `${__dirname}/../dist/assets/${path}`,
-      "utf8",
-    ),
-  };
 };
 
+/** An absolute URL as is; a path of the application at its own address. */
+const resolveLocation = async (
+  application: INestApplication,
+  location: string,
+): Promise<string> =>
+  /^[a-z][a-z\d+\-.]*:/i.test(location)
+    ? location
+    : new URL(location, await application.getUrl()).href;
+
 const getSwagger = async (
   url: string,
 ): Promise<

package/src/NestiaEditorUploader.tsx

@@ -16,6 +16,16 @@ import { NestiaEditorComposer } from "./internal/NestiaEditorComposer";
 import { NESTIA_EDITOR_DEFAULT_PACKAGE } from "./internal/NestiaEditorDefaultPackage";
 import { NestiaEditorFileUploader } from "./internal/NestiaEditorFileUploader";
 
+/**
+ * The uploader form: reads a Swagger file, and downloads the generated project.
+ *
+ * The user picks a document, a package name, the mode (SDK or NestJS project), and the options. The project is generated in the browser and downloaded as a zip file. Operations the converter could not handle are reported, so an incomplete project is never presented as complete.
+ *
+ * @evidence contracts/common.md#principled-implementation The form keeps its inputs in component state, composes on request with `NestiaEditorComposer`, and hands the files to `NestiaEditorArchiver`. Composition and archive failures, file-parser errors reported by the picker, and skipped operations reach the error handler. File-reading rejection belongs to the picker callback and is not caught by this form.
+ * @evidence contracts/common.md#clear-and-simple-design One component owns the form state and delegates parsing the file, composing, and archiving to internal modules.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The defaults are the same product defaults as the iframe flow and the package name comes from the shared constant; an error goes to `onError` when given and to `alert` otherwise, with no fixture-specific path.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the inputs, the output, and how skipped operations are reported.
+ */
 export function NestiaEditorUploader(props: NestiaEditorUploader.IProps) {
   // PARAMETERS
   const [mode, setMode] = React.useState<"nest" | "sdk">("sdk");
@@ -63,6 +73,15 @@ export function NestiaEditorUploader(props: NestiaEditorUploader.IProps) {
           name: NestiaEditorArchiver.name(name),
           files: result.data.files,
         });
+        if (result.data.skipped.length !== 0)
+          handleError(
+            [
+              "The project leaves out operations that could not be converted:",
+              ...result.data.skipped.map(
+                (s) => `  - ${s.method} ${s.path}: ${s.messages.join(" ")}`,
+              ),
+            ].join("\n"),
+          );
       } else {
         handleError(JSON.stringify(result.errors, null, 2));
       }
@@ -140,8 +159,17 @@ export function NestiaEditorUploader(props: NestiaEditorUploader.IProps) {
     </>
   );
 }
+/**
+ * Properties of {@link NestiaEditorUploader}.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the property type of the component with the same name, so the component and its inputs are one public identity.
+ * @evidence contracts/common.md#clear-and-simple-design It contains one interface with one optional callback.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It adds no behavior; when the callback is absent the component reports errors with `alert`.
+ * @evidence contracts/common.md#meaningful-documentation The comment names the component the properties belong to.
+ */
 export namespace NestiaEditorUploader {
   export interface IProps {
+    /** Receives conversion errors and skipped-operation warnings; absent uses alert. */
     onError?: (error: string) => void;
   }
 }