bimplus-webclient 0.1.70 → 0.1.71

package/.github/documentation.instructions.md

@@ -1,13 +1,13 @@
 ---
-applyTo: "src/**/*.js, doc_config.yml, documentation/**"
+applyTo: "src/**/*.js, scripts/generate-api-markdown.js, jsdoc.json, documentation/**"
 ---
 
 # Generating API Documentation
 
-This project uses the [`documentation`](https://github.com/documentationjs/documentation) npm package (JSDoc-based) to generate API docs from the JSDoc comments in `src/*.js`. Output is written to `./documentation`.
+This project uses [`jsdoc`](https://jsdoc.app/) to generate HTML API docs and parse doclets. The repository-owned `scripts/generate-api-markdown.js` renders those doclets into Markdown without a separate Markdown-generation dependency. `jsdoc.json` controls source discovery and HTML output to `./documentation`; the default JSDoc template creates `index.html` and API pages there, using `README.md` as landing-page content.
 
 ## Prerequisites
-- Node dependencies installed (`npm install`) — `documentation` is a devDependency.
+- Node dependencies installed (`npm install`) — `jsdoc` is a devDependency.
 - Python 3 available on PATH (only required for the Confluence conversion step, which runs `documentation/convert_to_confluence_md.py`).
 - All exported functions/classes in `src/*.js` should have valid JSDoc comments; `lint-doc` will fail the build on invalid JSDoc.
 
@@ -15,11 +15,11 @@ This project uses the [`documentation`](https://github.com/documentationjs/docum
 
 | Script | Purpose |
 | --- | --- |
-| `npm run lint-doc` | Runs `documentation lint ./src/*.js` to validate JSDoc comments before generating docs. |
-| `npm run build-doc` | Lints, then builds **HTML** docs into `./documentation` using `doc_config.yml` (defines the table of contents). |
-| `npm run build-docMd` | Lints, then builds a single **Markdown** file at `./documentation/Bimplus_WebClient_doc.md`. |
+| `npm run lint-doc` | Runs `jsdoc --pedantic --configure jsdoc.json --explain` to parse source and validate JSDoc comments. |
+| `npm run build-doc` | Lints, then generates **HTML** docs into `./documentation` with `jsdoc.json`. |
+| `npm run build-docMd` | Lints, then renders JSDoc doclets into `./documentation/Bimplus_WebClient_doc.md` with the repository-owned generator. |
 | `npm run build-docConf` | Runs `build-docMd`, then runs `documentation/convert_to_confluence_md.py` to produce `Bimplus_WebClient_doc_confluence.md`, a Confluence-friendly variant with fixed anchor links and an injected version header. |
-| `npm run build-docAll` | Runs `build-doc`, `build-docConf`, `build-docMd`, `build-doc` in sequence — regenerates HTML, Markdown, and Confluence docs together. |
+| `npm run build-docAll` | Runs `build-doc`, `build-docMd`, and `build-docConf` to regenerate HTML, Markdown, and Confluence docs. |
 
 ## Typical Workflow
 
@@ -28,14 +28,18 @@ This project uses the [`documentation`](https://github.com/documentationjs/docum
 3. Run `npm run build-docAll` to regenerate all doc formats at once (recommended before a release/publish).
    - Or run an individual script (`build-doc`, `build-docMd`, `build-docConf`) if you only need one output format.
 4. Review generated output:
-   - `./documentation/index.html` (and per-file `.html` pages) for the HTML site.
+   - `./documentation/index.html` and the generated API pages for the HTML site.
    - `./documentation/Bimplus_WebClient_doc.md` for the raw Markdown API doc.
    - `./documentation/Bimplus_WebClient_doc_confluence.md` for the Confluence-paste-ready version.
 5. Commit the regenerated files under `./documentation` along with your source changes.
 
-## Notes on `doc_config.yml`
-- Controls the HTML build's table of contents (`toc:` entries map to sections/pages).
-- Add a new `toc` entry here when introducing a new top-level `src/*.js` module you want listed separately in the HTML docs.
+## Notes on `jsdoc.json`
+- Controls recursive JavaScript source discovery, ES module parsing, HTML destination, and README landing-page content.
+- Update this configuration if the source layout or generated HTML destination changes.
+
+## Notes on the Markdown renderer
+- `scripts/generate-api-markdown.js` consumes JSDoc's structured `--explain` output and renders documented namespaces, methods, callbacks, parameters, returns, and explicit ID anchors. It fails if an internal link has no matching ID.
+- The generator checks that each documented symbol has an anchor. Preserve the `BimExplorer.BimObjectProperties+load` anchor convention because Confluence links depend on it.
 
 ## Notes on the Confluence conversion (`convert_to_confluence_md.py`)
 - Reads `./Bimplus_WebClient_doc.md` (must be generated first via `build-docMd`) and writes `./Bimplus_WebClient_doc_confluence.md`.
@@ -47,3 +51,5 @@ This project uses the [`documentation`](https://github.com/documentationjs/docum
 - **`lint-doc` fails**: fix the JSDoc syntax/tag errors it reports; the `build-*` scripts depend on it succeeding first.
 - **Confluence conversion fails with "file not found"**: run `npm run build-docMd` first, or use `npm run build-docConf` which does it automatically.
 - **Python not found**: only `build-docConf`/`build-docAll` need Python; ensure `python` resolves on PATH (or update the script invocation to `python3` if needed on your OS).
+
+Generated HTML and Markdown must be regenerated after changing source JSDoc comments, then reviewed and committed with the source changes.

package/JSDOC_MIGRATION_PLAN.md

@@ -18,15 +18,23 @@ Files expected to change:
 - `package.json`
 - `package-lock.json`
 - New root-level `jsdoc.json` configuration
+- New `scripts/generate-api-markdown.js` renderer
 - `.github/documentation.instructions.md`
+- `README.md`
+- `documentation/convert_to_confluence_md.py`
 - Generated files under `documentation/`
 
 The following should remain functionally unchanged:
 
 - JSDoc comments in `src/*.js`
-- `documentation/convert_to_confluence_md.py`
 - Application source, build, and test configuration
 
+## Porting This Plan to Other Projects
+
+Use this file as a migration template for each repository, not as a blind file-copy checklist. Before implementation, record the current source glob, generated output paths, existing `build-doc*` script names, Markdown heading/anchor conventions, and any downstream Confluence or publishing workflow. Preserve established output names and script interfaces when consumers depend on them; adapt paths and symbol grouping to that repository's JSDoc conventions.
+
+The reference custom renderer in [scripts/generate-api-markdown.js](scripts/generate-api-markdown.js) is the implementation model. Copy it only after checking that the other repository's doclets use compatible `kind`, `memberof`, `scope`, and `longname` values. Add project-specific filters or display rules only when required by its documented public API.
+
 ## Implementation Steps
 
 ### 1. Replace development dependencies
@@ -34,14 +42,17 @@ The following should remain functionally unchanged:
 Remove `documentation` from `devDependencies` and add:
 
 - `jsdoc` for parsing source comments and generating HTML
-- `jsdoc-to-markdown` for Markdown API output
+- A repository-owned Markdown renderer using JSDoc's structured doclets
 
-Install the dependencies with:
+Remove any old generator dependencies and install JSDoc:
 
 ```powershell
-npm install --save-dev jsdoc jsdoc-to-markdown
+npm uninstall documentation jsdoc-to-markdown
+npm install --save-dev jsdoc
 ```
 
+Do not add a third-party Markdown generator. `scripts/generate-api-markdown.js` renders JSDoc doclets directly and validates symbol anchors.
+
 Do not run `npm audit fix --force`; it may apply a breaking downgrade and does not provide a patched version of the vulnerable Vue 2 package.
 
 ### 2. Add `jsdoc.json`
@@ -53,7 +64,7 @@ Create a root-level JSDoc configuration with these requirements:
 - Parse ES module syntax
 - Write HTML output to `./documentation`
 - Use `README.md` as the documentation landing-page content when supported
-- Enable Markdown processing and recursive source discovery
+- Enable JSDoc's Markdown plugin and recursive source discovery
 
 Proposed configuration:
 
@@ -74,13 +85,12 @@ Proposed configuration:
     "monospaceLinks": true
   },
   "plugins": [
-    "plugins/markdown",
-    "plugins/recurse"
+    "plugins/markdown"
   ]
 }
 ```
 
-Validate the exact configuration against the installed JSDoc version before committing it.
+`opts.recurse: true` enables recursion. Do not add `plugins/recurse`: it is not shipped by JSDoc 4 and makes the command fail with "Unable to find the plugin". Validate the exact configuration against the installed JSDoc version before committing it.
 
 ### 3. Update npm scripts
 
@@ -90,13 +100,24 @@ Replace the current `documentation` commands with JSDoc equivalents while retain
 {
   "lint-doc": "jsdoc --pedantic --configure jsdoc.json --explain",
   "build-doc": "npm run lint-doc && jsdoc --configure jsdoc.json",
-  "build-docMd": "npm run lint-doc && jsdoc2md --files \"src/*.js\" > documentation/Bimplus_WebClient_doc.md",
+  "build-docMd": "npm run lint-doc && node scripts/generate-api-markdown.js",
   "build-docConf": "npm run build-docMd && cd ./documentation && python convert_to_confluence_md.py",
   "build-docAll": "npm run build-doc && npm run build-docMd && npm run build-docConf"
 }
 ```
 
-The `lint-doc` command should be tested with the installed JSDoc CLI. If JSDoc does not support the selected validation flags, replace it with the supported parse-only validation command while keeping the script name.
+`scripts/generate-api-markdown.js` replaces `jsdoc2md`; do not add a third-party Markdown renderer. The renderer should:
+
+1. Invoke the installed JSDoc CLI with `process.execPath`, the local `node_modules/jsdoc/jsdoc.js` entrypoint, `--configure jsdoc.json`, and `--explain`. Run with the repository root as `cwd`, capture stdout/stderr, and fail clearly on a non-zero exit or invalid JSON.
+2. Parse the JSON doclets and include documented public namespaces and supported API doclets only. Exclude undocumented, private, anonymous, and implementation-only symbols. Deduplicate repeated doclets by `longname`; group members by `memberof`; retain documented global functions.
+3. Render the information present on doclets: namespace parameters, method signatures, descriptions, parameter tables, return values, callbacks/properties, types/defaults, deprecation/since/throws/see tags, and examples where present. Preserve the Markdown/HTML descriptions produced by JSDoc.
+4. Emit both a useful API index and a section for each documented symbol. Escape values placed in code or Markdown tables without altering trusted JSDoc description markup.
+5. Emit explicit `<a id="…" name="…"></a>` targets. Keep each fragment used in a Markdown link identical to an emitted ID. Normalize instance-method `#` separators to the existing `+` anchor form; preserve dots for static members/callbacks. For example, `BimExplorer#getUrl` maps to `BimExplorer+getUrl`, while `BimExplorer.this.onObjectSelected` keeps its dotted name. Handle nested names such as `BimExplorer.BimObjectProperties#load` explicitly.
+6. Before writing the file, fail if a rendered API symbol has no anchor or if any generated `](#target)` link has no matching anchor ID. Create the destination directory if needed and write UTF-8.
+
+The checks in the renderer protect the source Markdown structure. They do not replace rendering the Markdown and testing real click navigation in the target preview/browser.
+
+The `lint-doc` command should be tested with the installed JSDoc CLI. `--explain` emits a large doclet JSON report; suppress or capture that output in automated logs if it becomes unwieldy, while preserving the command's exit status.
 
 ### 4. Regenerate documentation
 
@@ -115,7 +136,14 @@ Then run the complete workflow:
 npm run build-docAll
 ```
 
-The Confluence converter should continue reading the generated Markdown from its current location. No Python changes are expected unless the new Markdown headings or anchors expose a compatibility issue.
+The Confluence converter should continue reading the generated Markdown from its current location. It must:
+
+- Read and write UTF-8 explicitly so Unicode output works on Windows.
+- Rewrite links case-insensitively when JSDoc preserves case in fragments.
+- When rewriting a target to `WebClientApidescription-{fragment}`, emit a matching `<a id="WebClientApidescription-{fragment}" name="WebClientApidescription-{fragment}"></a>` alias. Rewriting links without creating matching targets leaves the converted document's links dead.
+- Validate every converted internal Markdown link against an emitted ID before writing the final Confluence file.
+
+Keep the raw Markdown IDs and Confluence aliases separate: the raw file uses the API fragments; only the Confluence variant uses the required `WebClientApidescription-` prefix.
 
 ### 5. Review generated output
 
@@ -124,32 +152,38 @@ Check the following:
 - `documentation/index.html` opens successfully
 - HTML assets load without missing-file errors
 - All public classes, methods, namespaces, callbacks, parameters, and return values are represented
+- Every rendered API symbol has a generated Markdown anchor, and internal Markdown links resolve
 - Markdown headings and links are readable
 - Confluence anchors contain the expected `WebClientApidescription-` prefix
+- Confluence-prefixed links have matching prefixed target IDs
 - No stale files from the previous generator remain in the generated output
 
+Do not treat matching fragment strings in source files as proof of working links. Render both Markdown files with the parser/preview used by their consumers, inspect the resulting `href` and `id` values, and click representative links: a namespace, an instance method containing `+`, a static callback containing `.`, and the nested `BimObjectProperties` method. If the consumer is VS Code Markdown Preview, test there; if the Confluence Markdown is pasted into Confluence, verify links in Confluence's preview/page because its anchor generation rules differ from local Markdown renderers.
+
 JSDoc will produce a different HTML structure and may use different anchor names than documentation.js. This is expected, but no public API should disappear.
 
 ### 6. Update repository guidance
 
-Update `.github/documentation.instructions.md` to describe:
+Update `.github/documentation.instructions.md` and `README.md` to describe:
 
 - `jsdoc.json`
-- `jsdoc` and `jsdoc-to-markdown`
+- `jsdoc` and the repository-owned Markdown renderer
 - The revised npm scripts
 - The new HTML output structure
 - The continued Markdown-to-Confluence conversion
 - The fact that generated output must be regenerated after source JSDoc changes
+- The repository-owned Markdown renderer and its symbol/link validation
+- The distinction between raw Markdown IDs and Confluence-prefixed alias IDs
 
 ### 7. Remove obsolete dependency output
 
 After a successful install, verify that the old packages are gone:
 
 ```powershell
-npm ls documentation vue-template-compiler
+npm ls documentation jsdoc-to-markdown vue-template-compiler
 ```
 
-The command should report that neither package is installed, or that they are not found in the dependency tree.
+The command should report that none of these packages is installed, or that they are not found in the dependency tree. Search scripts, instructions, READMEs, and the lockfile for stale `jsdoc2md`/`jsdoc-to-markdown` references; a removal-check command in this plan may name the package intentionally.
 
 Review `package-lock.json` for removal of the obsolete dependency chain. Do not remove unrelated lockfile changes produced by the package manager.
 
@@ -166,6 +200,12 @@ npm test
 npm audit
 ```
 
+Also lint the renderer directly if the repository ESLint script does not include it:
+
+```powershell
+npx eslint scripts/generate-api-markdown.js
+```
+
 Expected results:
 
 - Documentation commands complete successfully
@@ -173,6 +213,8 @@ Expected results:
 - The application build remains successful
 - Existing tests remain successful
 - The `vue-template-compiler` audit finding is no longer introduced by this documentation toolchain
+- `jsdoc-to-markdown` is absent from the manifest, lockfile dependency tree, and generation scripts
+- Rendered raw Markdown and Confluence Markdown links navigate to their intended targets in their actual consumers
 
 `npm audit` may still report unrelated vulnerabilities. Record those separately instead of applying a forced dependency downgrade.
 
@@ -181,9 +223,9 @@ Expected results:
 If the generated output loses API content or the Confluence conversion cannot be adapted safely:
 
 1. Restore the previous `package.json` and `package-lock.json` documentation dependencies.
-2. Remove `jsdoc.json`.
+2. Remove `jsdoc.json` and `scripts/generate-api-markdown.js`.
 3. Restore the previous generated `documentation/` output.
-4. Reassess the JSDoc configuration and Markdown template before retrying.
+4. Reassess the JSDoc configuration and renderer before retrying.
 
 Do not modify application source code as part of rollback.
 
@@ -193,7 +235,7 @@ The migration is complete when:
 
 - `documentation` is no longer a development dependency
 - JSDoc generates readable HTML from `src/*.js`
-- `jsdoc-to-markdown` generates the API Markdown file
+- The repository-owned renderer generates the API Markdown file
 - The existing Confluence conversion succeeds
 - `build-doc`, `build-docMd`, `build-docConf`, and `build-docAll` all work
 - Generated documentation is reviewed and committed

package/README.md

@@ -74,19 +74,22 @@ goto your application folder which uses the webclient
     npm install
 
 ### Unit testing
-The unit tests run with Vitest and jsdom. Run them with coverage using:
+The tests run with Vitest in jsdom, Chromium, and Firefox. Install the browser
+binaries with `npx playwright install` before the first run. Run the tests
+with coverage using:
 
-    npm test
+    npm run test
+
+The browser test API binds to `127.0.0.1`, starting at port `41315`, outside the
+Windows default dynamic port range. If the port is in use, Vitest selects the
+next available port so multiple test runs can execute concurrently.
 
 Run Vitest in watch mode during development with:
 
     npm run test-watch
 
 ### Documentation
-Bimplus webclient uses npm documentation plugin for easy documentation generation.
-To generate a documentation please install documentation plugin via npm :
-
-    npm install -g documentation
+Bimplus webclient uses JSDoc for HTML documentation and a repository-owned renderer for Markdown API documentation. Install project dependencies with `npm install` before generating docs.
 
 To create documentation in html format go to your webclient folder and run :
 
@@ -98,7 +101,7 @@ To create documentation in markdown format go to your webclient folder and run :
 
     npm run build-docMd
 
-Documentation output will be in webclient/documentation/Bimplus_WebSDK_doc.md file.
+Documentation output will be in `webclient/documentation/Bimplus_WebClient_doc.md`.
 
 To create a markdown suitable for Confluence run script:
 

package/jsdoc.json

@@ -0,0 +1,19 @@
+{
+  "source": {
+    "include": ["src"],
+    "includePattern": ".*\\.js$",
+    "excludePattern": "(^|[\\\\/])node_modules[\\\\/]"
+  },
+  "opts": {
+    "destination": "./documentation",
+    "recurse": true,
+    "readme": "./README.md"
+  },
+  "templates": {
+    "cleverLinks": false,
+    "monospaceLinks": true
+  },
+  "plugins": [
+    "plugins/markdown"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bimplus-webclient",
-  "version": "0.1.70",
+  "version": "0.1.71",
   "description": "bim+ web client",
   "types": "types/bimplus-webclient.d.ts",
   "keywords": [
@@ -24,28 +24,28 @@
     "bump": "npm run bump:patch",
     "bump:patch": "npm version patch --no-git-tag-version",
     "npm-pack": "npm run build-prod && npm pack",
-    "lint-doc": "documentation lint ./src/*.js",
-    "build-doc": "npm run lint-doc && documentation build ./src/*.js --config doc_config.yml -f html -o ./documentation",
-    "build-docMd": "npm run lint-doc && documentation build ./src/*.js -f md -o ./documentation/Bimplus_WebClient_doc.md",
+    "lint-doc": "jsdoc --pedantic --configure jsdoc.json --explain",
+    "build-doc": "npm run lint-doc && jsdoc --configure jsdoc.json",
+    "build-docMd": "npm run lint-doc && node scripts/generate-api-markdown.js",
     "build-docConf": "npm run build-docMd && cd ./documentation && python convert_to_confluence_md.py",
-    "build-docAll": "npm run build-doc && npm run build-docConf && npm run build-docMd && npm run build-doc",
+    "build-docAll": "npm run build-doc && npm run build-docMd && npm run build-docConf",
     "test": "vitest run --coverage",
     "test-watch": "vitest"
   },
   "devDependencies": {
-    "@babel/core": "^8.0.6",
-    "@babel/preset-env": "^8.0.6",
+    "@babel/core": "^8.0.7",
+    "@babel/preset-env": "^8.0.7",
     "@eslint/js": "^10.0.1",
-    "@vitest/browser-playwright": "^5.0.3",
-    "@vitest/coverage-istanbul": "^5.0.3",
+    "@vitest/browser-playwright": "^5.0.4",
+    "@vitest/coverage-istanbul": "^5.0.4",
     "babel-loader": "^10.1.1",
-    "documentation": "^14.0.3",
     "eslint": "^10.12.0",
     "globals": "17.13.0",
+    "jsdoc": "^4.0.5",
     "jsdom": "^30.1.2",
-    "playwright": "^1.63.0",
+    "playwright": "^1.64.0",
     "terser-webpack-plugin": "^5.6.1",
-    "vitest": "^5.0.3",
+    "vitest": "^5.0.4",
     "webpack": "^5.111.1",
     "webpack-cli": "^7.2.3",
     "webpack-merge": "^6.0.1"
@@ -59,5 +59,5 @@
       "version": "^22.22.2 || ^24.15.0 || >=26.0.0",
       "onFail": "error"
     }
-  }  
+  }
 }

package/scripts/generate-api-markdown.js

@@ -0,0 +1,344 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const process = require("node:process");
+
+const rootDirectory = path.resolve(__dirname, "..");
+const outputPath = path.join(rootDirectory, "documentation", "Bimplus_WebClient_doc.md");
+const namespaceKinds = new Set(["function", "member", "constant", "event", "typedef"]);
+
+function escapeCode(value) {
+  return String(value).replace(/[&<>]/g, character => ({
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;"
+  })[character]);
+}
+
+function formatType(type) {
+  const names = type && type.names ? type.names : [];
+  return names.map(name => `<code>${escapeCode(name)}</code>`).join(" | ") || "";
+}
+
+function formatSignature(doclet) {
+  const parameters = (doclet.params || []).map(parameter => parameter.name).filter(Boolean);
+  return `(${parameters.join(", ")})`;
+}
+
+function getAnchor(doclet) {
+  if (doclet.kind !== "function" || !doclet.longname.includes("#")) {
+    return doclet.longname || doclet.name;
+  }
+
+  const parts = doclet.longname.split("#");
+  if (parts.length === 2) {
+    return `${parts[0]}+${parts[1]}`;
+  }
+
+  return `${parts.slice(0, -1).join(".")}+${parts.at(-1)}`;
+}
+
+function getDisplayName(doclet) {
+  if (doclet.kind !== "function") {
+    return doclet.longname || doclet.name;
+  }
+
+  const signature = formatSignature(doclet);
+  const owner = doclet.memberof;
+  const name = doclet.name || doclet.longname;
+
+  if (!owner) {
+    return `${name}${signature}`;
+  }
+
+  if (name.includes("#")) {
+    return `${owner}.${name}${signature}`;
+  }
+
+  if (doclet.scope === "instance") {
+    return `${owner[0].toLowerCase()}${owner.slice(1)}.${name}${signature}`;
+  }
+
+  return `${doclet.longname}${signature}`;
+}
+
+function getTocLabel(doclet) {
+  if (doclet.kind === "function" && doclet.scope === "instance") {
+    return `.${doclet.name.split("#").at(-1)}${formatSignature(doclet)}`;
+  }
+
+  if (doclet.kind === "member" && doclet.scope === "static") {
+    return `.${doclet.name}`;
+  }
+
+  return getDisplayName(doclet);
+}
+
+function renderParameterTable(parameters) {
+  if (!parameters || parameters.length === 0) {
+    return "";
+  }
+
+  const rows = parameters.map(parameter => {
+    const name = String(parameter.name || "").replace(/\|/g, "\\|");
+    const description = String(parameter.description || "").replace(/\|/g, "\\|");
+    return `| ${name} | ${formatType(parameter.type)} | ${description} |`;
+  });
+
+  return [
+    "| Param | Type | Description |",
+    "| --- | --- | --- |",
+    ...rows
+  ].join("\n");
+}
+
+function renderReturnValues(returns) {
+  return (returns || []).map(result => {
+    const type = formatType(result.type);
+    const description = result.description ? ` - ${result.description}` : "";
+    return `**Returns**: ${type}${description}`;
+  }).join("\n\n");
+}
+
+function renderExamples(examples) {
+  return (examples || []).map(example => `\`\`\`js\n${example}\n\`\`\``).join("\n\n");
+}
+
+function renderExceptions(exceptions) {
+  return (exceptions || []).map(exception => {
+    const type = formatType(exception.type);
+    const description = exception.description ? ` - ${exception.description}` : "";
+    return `- ${type}${description}`;
+  }).join("\n");
+}
+
+function renderKind(doclet, owner) {
+  if (!owner) {
+    return "";
+  }
+
+  const target = `[<code>${owner}</code>](#${owner})`;
+  if (doclet.kind === "function" && doclet.scope === "instance") {
+    return `**Kind**: instance method of ${target}`;
+  }
+  if (doclet.kind === "function" && doclet.scope === "static") {
+    return `**Kind**: static method of ${target}`;
+  }
+  if (doclet.kind === "member" && doclet.scope === "static") {
+    return `**Kind**: static property of ${target}`;
+  }
+  return `**Kind**: ${doclet.kind} of ${target}`;
+}
+
+function renderEntry(doclet, owner) {
+  const anchor = getAnchor(doclet);
+  const sections = [`<a id="${anchor}" name="${anchor}"></a>`, `### ${getDisplayName(doclet)}`];
+
+  if (doclet.description) {
+    sections.push(doclet.description);
+  }
+
+  const kind = renderKind(doclet, owner);
+  if (kind) {
+    sections.push(kind);
+  }
+
+  if (doclet.type) {
+    sections.push(`**Type**: ${formatType(doclet.type)}`);
+  }
+
+  if (doclet.defaultvalue !== undefined) {
+    const value = typeof doclet.defaultvalue === "string"
+      ? doclet.defaultvalue
+      : JSON.stringify(doclet.defaultvalue);
+    sections.push(`**Default**: <code>${escapeCode(value)}</code>`);
+  }
+
+  if (doclet.readonly) {
+    sections.push("**Read-only**: Yes");
+  }
+
+  const returns = renderReturnValues(doclet.returns);
+  if (returns) {
+    sections.push(returns);
+  }
+
+  const parameters = renderParameterTable(doclet.params);
+  if (parameters) {
+    sections.push(parameters);
+  }
+
+  if (doclet.deprecated) {
+    sections.push(`**Deprecated**: ${typeof doclet.deprecated === "string" ? doclet.deprecated : "Yes"}`);
+  }
+
+  if (doclet.since) {
+    sections.push(`**Since**: ${doclet.since}`);
+  }
+
+  const exceptions = renderExceptions(doclet.exceptions);
+  if (exceptions) {
+    sections.push(`**Throws**:\n\n${exceptions}`);
+  }
+
+  const examples = renderExamples(doclet.examples);
+  if (examples) {
+    sections.push(`**Example**:\n\n${examples}`);
+  }
+
+  if (doclet.see && doclet.see.length) {
+    sections.push(`**See**: ${doclet.see.join(", ")}`);
+  }
+
+  return sections.join("\n\n");
+}
+
+function renderNamespaceIndex(namespace, symbols) {
+  const instanceSymbols = symbols.filter(symbol => symbol.kind === "function" && symbol.scope === "instance");
+  const staticSymbols = symbols.filter(symbol => !instanceSymbols.includes(symbol));
+  const lines = [`- [${namespace.name}](#${namespace.name}) : <code>object</code>`];
+
+  if (instanceSymbols.length) {
+    lines.push("  - _instance_");
+    for (const symbol of instanceSymbols) {
+      lines.push(`    - [${getTocLabel(symbol)}](#${getAnchor(symbol)})`);
+    }
+  }
+
+  if (staticSymbols.length) {
+    lines.push("  - _static_");
+    for (const symbol of staticSymbols) {
+      lines.push(`    - [${getTocLabel(symbol)}](#${getAnchor(symbol)})`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function renderNamespace(namespace, symbols) {
+  const sections = [
+    `<a id="${namespace.name}" name="${namespace.name}"></a>`,
+    `## ${namespace.name} : <code>object</code>`,
+    "**Kind**: global namespace"
+  ];
+
+  if (namespace.description) {
+    sections.push(namespace.description);
+  }
+
+  const parameters = renderParameterTable(namespace.params);
+  if (parameters) {
+    sections.push(parameters);
+  }
+
+  for (const symbol of symbols) {
+    sections.push(renderEntry(symbol, namespace.name));
+  }
+
+  return sections.join("\n\n");
+}
+
+function getDoclets() {
+  const jsdocCliPath = path.join(rootDirectory, "node_modules", "jsdoc", "jsdoc.js");
+  const result = spawnSync(process.execPath, [jsdocCliPath, "--configure", "jsdoc.json", "--explain"], {
+    cwd: rootDirectory,
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `JSDoc exited with status ${result.status}`);
+  }
+
+  return JSON.parse(result.stdout);
+}
+
+function renderMarkdown(doclets) {
+  const namespaces = [];
+  const namespaceNames = new Set();
+
+  for (const doclet of doclets) {
+    if (doclet.kind === "namespace" && doclet.name && !namespaceNames.has(doclet.name)) {
+      namespaces.push(doclet);
+      namespaceNames.add(doclet.name);
+    }
+  }
+
+  const symbols = doclets.filter(doclet => {
+    const documented = doclet.comment && doclet.comment.trim() && !doclet.undocumented;
+    const supportedKind = namespaceKinds.has(doclet.kind);
+    const supportedOwner = namespaceNames.has(doclet.memberof) || (!doclet.memberof && doclet.kind === "function");
+    return documented && supportedKind && supportedOwner;
+  });
+
+  const symbolsByNamespace = new Map(namespaces.map(namespace => [namespace.name, []]));
+  const globalFunctions = [];
+  const uniqueSymbols = new Map();
+
+  for (const symbol of symbols) {
+    const key = symbol.longname || `${symbol.kind}:${symbol.name}`;
+    if (uniqueSymbols.has(key)) {
+      continue;
+    }
+    uniqueSymbols.set(key, symbol);
+
+    if (symbol.memberof) {
+      symbolsByNamespace.get(symbol.memberof).push(symbol);
+    } else {
+      globalFunctions.push(symbol);
+    }
+  }
+
+  const output = ["## Objects", namespaces.map(namespace =>
+    renderNamespaceIndex(namespace, symbolsByNamespace.get(namespace.name))
+  ).join("\n")];
+
+  if (globalFunctions.length) {
+    output.push("## Functions", globalFunctions.map(symbol =>
+      `- [${getTocLabel(symbol)}](#${getAnchor(symbol)})`
+    ).join("\n"));
+  }
+
+  for (const namespace of namespaces) {
+    output.push(renderNamespace(namespace, symbolsByNamespace.get(namespace.name)));
+  }
+
+  for (const symbol of globalFunctions) {
+    output.push(renderEntry(symbol));
+  }
+
+  const markdown = `${output.join("\n\n")}\n`;
+  const anchors = [...markdown.matchAll(/<a id="([^"]+)" name="\1"><\/a>/g)].map(match => match[1]);
+  const anchorSet = new Set(anchors);
+
+  for (const symbol of uniqueSymbols.values()) {
+    if (!anchorSet.has(getAnchor(symbol))) {
+      throw new Error(`Missing Markdown anchor for ${symbol.longname}`);
+    }
+  }
+
+  const linkTargets = [...markdown.matchAll(/\]\(#([^)]+)\)/g)].map(match => match[1]);
+  const missingTargets = linkTargets.filter(target => !anchorSet.has(target));
+  if (missingTargets.length) {
+    throw new Error(`Markdown link target has no ID anchor: ${missingTargets[0]}`);
+  }
+
+  if (namespaceNames.size !== namespaces.length) {
+    throw new Error("Namespace deduplication failed");
+  }
+
+  return { markdown, namespaceCount: namespaces.length, symbolCount: uniqueSymbols.size };
+}
+
+try {
+  const result = renderMarkdown(getDoclets());
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, result.markdown, "utf8");
+  console.log(`Generated Markdown for ${result.namespaceCount} namespaces and ${result.symbolCount} API symbols.`);
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/vitest.config.mjs

@@ -4,6 +4,11 @@ import { playwright } from '@vitest/browser-playwright';
 export default defineConfig({
   test: {
     globals: true,
+    api: {
+      host: '127.0.0.1',
+      port: 41315,
+      strictPort: false,
+    },
     silent: 'passed-only',
     restoreMocks: true,
     setupFiles: ['./test/vitest.setup.js'],