@nestia/editor 14.0.1 → 14.0.3

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.1",
+  "version": "14.0.3",
   "main": "lib/index.js",
   "exports": {
     ".": {
@@ -44,14 +44,14 @@
     "prettier": "^3.8.1",
     "react-mui-fileuploader": "^0.5.2",
     "typia": "15.0.0",
-    "@nestia/migrate": "^14.0.1"
+    "@nestia/migrate": "^14.0.3"
   },
   "devDependencies": {
     "@eslint/js": "^9.13.0",
-    "@nestjs/common": "^11.1.6",
-    "@nestjs/core": "^11.1.6",
-    "@nestjs/platform-express": "^11.1.6",
-    "@nestjs/platform-fastify": "^11.1.6",
+    "@nestjs/common": "^12.1.2",
+    "@nestjs/core": "^12.1.2",
+    "@nestjs/platform-express": "^12.1.2",
+    "@nestjs/platform-fastify": "^12.1.2",
     "@ttsc/unplugin": "^0.28.1",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.3.3",
@@ -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 && 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,21 +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),
+        content: index,
       },
-      await getJavaScript(),
+      ...(await getJavaScripts(index)),
     ];
     for (const f of staticFiles) {
       adaptor.get(prefix + f.path, (_: any, res: any) => {
@@ -51,15 +100,25 @@ export namespace NestiaEditorModule {
       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 {
-        document ??= JSON.stringify(
-          await getSwagger(
-            await resolveLocation(props.application, props.swagger as string),
-          ),
-          null,
-          2,
-        );
+        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");
@@ -68,7 +127,7 @@ export namespace NestiaEditorModule {
       res.type("application/json");
       return res.send(document);
     });
-    for (const p of ["", "/"])
+    for (const p of prefix.length === 0 ? ["/"] : ["", "/"])
       adaptor.get(prefix + p, (_: any, res: any) => {
         return res.redirect(prefix + "/index.html");
       });
@@ -113,30 +172,47 @@ 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. */

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");
@@ -149,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;
   }
 }

package/src/internal/NestiaEditorArchiver.ts

@@ -1,4 +1,6 @@
-import { strToU8, zipSync } from "fflate";
+import { Zip, ZipDeflate, strToU8 } from "fflate";
+
+import { NESTIA_EDITOR_DEFAULT_PACKAGE } from "./NestiaEditorDefaultPackage";
 
 /**
  * Archives a composed project into a zip file and hands it to the browser.
@@ -8,21 +10,74 @@ import { strToU8, zipSync } from "fflate";
  * WebContainer cannot execute. The editor therefore delivers the composed
  * project as a downloadable zip archive instead of an embedded StackBlitz
  * workspace.
+ *
+ * @evidence contracts/common.md#principled-implementation Packing is a synchronous zip of UTF-8 encoded entries through `fflate`, naming derives from the package name with a fixed character whitelist, and the download creates an object URL, clicks an anchor, and revokes the URL later.
+ * @evidence contracts/common.md#clear-and-simple-design Three operations, each one browser or zip concern, in one namespace with no shared state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The archive is built with the library's public functions and the download uses the standard anchor mechanism; nothing is patched.
+ * @evidence contracts/common.md#meaningful-documentation The namespace prose explains why the editor delivers a zip archive rather than an embedded workspace.
  */
 export namespace NestiaEditorArchiver {
-  /** Pack the composed project files into a zip archive. */
+  /**
+   * Pack the composed project files into a zip archive.
+   *
+   * @evidence contracts/common.md#principled-implementation Each own file key names a synchronous ZipDeflate stream added to Zip. Filenames are values rather than dictionary properties, preserving prototype-related names without changing an object's prototype. UTF-8 encoding preserves text; ending the archive emits its directory, including for an empty project.
+   * @evidence contracts/common.md#clear-and-simple-design One loop supplies files to the public synchronous compression streams; the callback collects chunks which are copied once into the returned archive.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It archives exactly the given files; no entry is added, filtered, or renamed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the input and output.
+   */
   export const pack = (files: Record<string, string>): Uint8Array => {
-    const entries: Record<string, Uint8Array> = {};
-    for (const [key, value] of Object.entries(files))
-      entries[key] = strToU8(value);
-    return zipSync(entries);
+    const chunks: Uint8Array[] = [];
+    const archive = new Zip((error, chunk) => {
+      if (error) throw error;
+      chunks.push(chunk);
+    });
+    for (const [key, value] of Object.entries(files)) {
+      const entry = new ZipDeflate(key);
+      archive.add(entry);
+      entry.push(strToU8(value), true);
+    }
+    archive.end();
+    const output = new Uint8Array(
+      chunks.reduce((length, chunk) => length + chunk.length, 0),
+    );
+    let offset = 0;
+    for (const chunk of chunks) {
+      output.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return output;
+  };
+
+  /**
+   * Compose a safe archive file name from a package name.
+   *
+   * A leading `@` is dropped and every run of characters outside letters,
+   * digits, `.`, `_`, and `-` becomes one `-`. A name with nothing left but
+   * dots, such as an empty package name, has no usable base for the archive, so
+   * the default package name is used instead. Other names retain their dots,
+   * including a leading dot.
+   *
+   * @evidence contracts/common.md#principled-implementation Dropping the `@` and replacing runs of characters outside the whitelist with one `-` yields a file name without path separators. Empty or dots-only bases use the default package name; otherwise dots are retained, so this is not a general rejection of hidden filenames or a validator of npm package names.
+   * @evidence contracts/common.md#clear-and-simple-design One private helper applies the character rule to the package name and to the default, so the rule exists once.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule applies to every input; the only special case is the empty-name guard, which follows from the safe-name requirement.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the character rule and the dots-only fallback.
+   */
+  export const name = (packageName: string): string => {
+    const base: string = compose(packageName);
+    return `${/^\.*$/.test(base) ? compose(NESTIA_EDITOR_DEFAULT_PACKAGE) : base}.zip`;
   };
 
-  /** Compose a safe archive file name from a package name. */
-  export const name = (packageName: string): string =>
-    `${packageName.replace(/^@/, "").replace(/[^A-Za-z0-9._-]+/g, "-")}.zip`;
+  const compose = (packageName: string): string =>
+    packageName.replace(/^@/, "").replace(/[^A-Za-z0-9._-]+/g, "-");
 
-  /** Trigger a browser download of the packed archive. */
+  /**
+   * Trigger a browser download of the packed archive.
+   *
+   * @evidence contracts/common.md#principled-implementation A Blob of the packed bytes is exposed through an object URL and an anchor with the `download` attribute is clicked, which is the browser's standard way to save generated content; the URL is revoked after 30 seconds so its memory is released.
+   * @evidence contracts/common.md#clear-and-simple-design One function, kept apart from `pack` so packing stays testable outside a browser.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It uses the standard DOM and URL APIs; the delayed revocation is not a retry or a compensation.
+   * @evidence contracts/common.md#meaningful-documentation The comment states that it triggers a browser download of the packed archive.
+   */
   export const download = (props: {
     name: string;
     files: Record<string, string>;