bimplus-renderer 1.8.41-babel-webpack1.1 → 1.8.41

package/.github/instructions/es2019-webpack-compat.instructions.md

@@ -0,0 +1,14 @@
+---
+applyTo: "**/webpack*.js, **/package.json, **/scripts/**/*.js"
+---
+
+# ES2019 Bundle Compatibility
+
+Keep the published renderer bundle parseable by downstream Webpack 4 consumers, whose parser may stop at ES2020 syntax.
+
+- Babel 8 `@babel/preset-env` defaults to modern browser targets. Set explicit targets below the syntax level that downstream tooling supports; for the current renderer use Chrome 79, Firefox 72, Safari 13, and Edge 79.
+- Apply Babel to bundled dependencies that can contain newer syntax, especially `three` and `web-ifc`. Do not exclude these packages from the production Babel rule.
+- `target: ['web', 'es2019']` and Terser's `ecma: 2019` control Webpack output and minification; neither transpiles syntax already present in input modules. Keep the Babel transform as the source-syntax compatibility step.
+- Babel preset-env does not lower BigInt literal syntax. If a dependency introduces `1n` literals, rewrite only the literals to `BigInt("1")` calls so an ES2019 parser can read the bundle. This does not polyfill BigInt; runtime use still requires native BigInt support.
+- Keep an Acorn check using `ecmaVersion: 2019` on the generated `dist/bimplus-renderer.js` in every production build/publish path. It should run after Webpack emits the bundle and before copying or publishing artifacts.
+- Verify changes with the production Webpack build followed by `npm run check-es2019`. A successful Webpack/Terser build alone does not establish ES2019 compatibility.

package/.github/instructions/jsdoc-api-docs.instructions.md

@@ -0,0 +1,79 @@
+---
+description: "Use when writing or updating JSDoc comments, documenting renderer API classes/methods, or generating API documentation (build-doc, build-docMd, Confluence export). Covers required tags, visibility rules, and validation."
+applyTo: "src/**/*.js"
+---
+
+# JSDoc Usage for API Documentation
+
+The public API docs are generated from JSDoc comments in `src/` via JSDoc 4 (`jsdoc.json`) with the custom plugin `scripts/jsdoc-class-ownership-plugin.js` and `scripts/generate-api-markdown.js`. Follow these rules so symbols land correctly in `documentation/Bimplus_Renderer_doc.md` and the HTML docs.
+
+## What gets published
+
+A symbol only appears in generated API docs when **all** of these hold:
+
+- It has a JSDoc comment with a non-empty description.
+- It is not marked `@private` and its name does not start with `_` (both are excluded automatically).
+- Its kind is a container (`class`, `namespace`, `module`) or a member kind (`function`, `member`, `constant`, `event`, `typedef`, `callback`).
+- Member symbols belong to a documented container — document the class itself, or its methods will be dropped silently.
+
+## Required comment structure
+
+Start with a short description, then tags in this order: visibility, structural tags, `@param`, `@returns`.
+
+```js
+/**
+ * Set the dimension line visibility.
+ *
+ * @public
+ * @param {boolean} visible visible flag
+ * @returns {boolean} true when visibility changed
+ */
+```
+
+- Always state visibility explicitly: `@public` for API surface, `@private` for internals.
+- `@param {Type} name description` — type in braces, lowercase primitives (`boolean`, `number`, `string`), `Object` for plain objects; document every parameter including defaults.
+- `@returns {Type} description` whenever the method returns a value.
+- Mark superseded API with `@deprecated` instead of deleting the comment.
+- Name internal helpers with a leading underscore (`_getLineTexture`) — they are excluded from docs even without `@private`.
+- The `plugins/markdown` plugin is enabled, so Markdown is allowed in descriptions.
+
+## Class ownership — two styles
+
+**Default-exported ES classes (preferred, new code):** the class-ownership plugin resolves `memberof`, scope, and longname automatically. Do **not** add `@memberof`, `@name`, or `@instance` to class-body methods; a description plus visibility/param/returns tags is enough. Document the class head with `@class`/`@constructor` and visibility:
+
+```js
+/**
+ * Annotation class constructor.
+ *
+ * @constructor
+ * @private
+ */
+class Annotation extends AnnotationBase { ... }
+```
+
+**Legacy function-constructor classes (e.g., `Viewport3D` in `src/viewport3d.js`):** members assigned as `this.foo = function () {}` need the full explicit tag set, otherwise JSDoc treats them as globals:
+
+```js
+/**
+ * Check if renderer is in dev mode.
+ *
+ * @returns {boolean} true if renderer is in dev mode
+ * @public
+ * @function
+ * @name Viewport3D#isDevMode
+ * @memberof Viewport3D
+ * @instance
+ */
+```
+
+Use `Class#method` for instance members and `Class.method` for statics in `@name` and `{@link}` targets.
+
+## Links
+
+Use `{@link Class#method}` / `{@link Class.staticMethod}` for cross-references. The markdown generator fails the build on link targets without a matching anchor, so link only to documented, non-private symbols.
+
+## Validation
+
+- `npm run lint-doc` — fastest check; runs `jsdoc --explain` and fails on malformed comments. Run after any JSDoc change.
+- `npm run build-docMd` — regenerates the Markdown API doc and enforces anchor/link integrity; run when adding, renaming, or removing public symbols.
+- `npm run build-doc` (HTML), `build-docConf` (Confluence, needs Python), `build-docAll` — full outputs; only needed when publishing docs.

package/.github/instructions/moment-timezone-integration.instructions.md

@@ -0,0 +1,37 @@
+---
+description: "Use when changing moment-timezone usage, sun-position calculations, renderer dependency declarations, or their tests. Explains the test-only dependency and web-app injection requirement."
+applyTo: "src/utils/momentTimezoneInjector.js, src/viewport3d.js, src/exports.js, test/**, package.json"
+---
+
+# Moment-Timezone Integration
+
+- `moment-timezone` is a renderer development dependency used by local tests. The Vitest browser setup provides it to tests through the `moment` and `MomentTZ` globals.
+- Do not treat the renderer's development dependency or test setup as making `moment-timezone` available to consuming web applications. Keep it out of renderer production bundles unless the dependency strategy is intentionally changed.
+- Web applications using features that require timezone data, such as `setSunPosition`, must provide `moment-timezone` themselves and inject it into the renderer with the exported `injectMomentTimezone` function before using those features.
+- Consumers can provide the library through their own npm dependency, a CDN, or another application-managed mechanism. Existing applications that already expose a compatible `window.moment` can continue to use it.
+- Use the exported `hasMomentTimezone` helper to check availability before injecting when needed:
+
+  ```javascript
+  import { injectMomentTimezone, hasMomentTimezone } from 'bimplus-renderer';
+  import moment from 'moment-timezone';
+
+  if (!hasMomentTimezone()) {
+    injectMomentTimezone(moment);
+  }
+
+  viewport3D.setSunPosition({
+    northDirection: 0,
+    year: 2024,
+    month: 6,
+    day: 21,
+    hours: 12,
+    minutes: 0,
+    timezone: 'Europe/Berlin',
+    latitude: 52.52,
+    longitude: 13.405,
+    showSky: true
+  });
+  ```
+
+- Preserve the runtime availability check and its clear error when required timezone support has not been provided.
+- When changing this integration, keep the local test setup and the consuming-application injection path consistent.

package/.github/instructions/vitest-playwright-testing.instructions.md

@@ -0,0 +1,99 @@
+---
+description: "Use when adding, running, or debugging renderer Vitest browser tests, modelviewer IFC DDT, Playwright image comparisons, screenshot baselines, or named report images."
+applyTo: "**/vitest.config.mjs, **/playwright.config.mjs, **/test/**/*.js, **/modelviewer-data-driven-tests/tests/**/*.js, **/modelviewer-data-driven-tests/playwright/**/*.js, **/modelviewer-data-driven-tests/playwright/**/*.mjs, **/modelviewer-data-driven-tests/playwright/**/*.html, **/package.json"
+---
+
+# Renderer testing: Vitest and Playwright image comparison
+
+Run commands from the renderer directory. Follow the existing configurations
+and helpers; do not introduce another test runner or restore Karma/Jasmine.
+See [README testing documentation](../../README.md#unit-testing) for setup and
+the full command reference.
+
+## Keep the suites separate
+
+- Use Vitest for renderer unit/performance tests and IFC geometry DDT.
+  Import test APIs from `vitest`. These tests run in real browsers using the
+  Playwright provider, not a simulated DOM.
+- Use standalone Playwright Test for IFC image comparisons. Import its APIs
+  from `@playwright/test`; keep visual entry points as `*.spec.mjs` under
+  `modelviewer-data-driven-tests/playwright/`.
+- Keep Node reporter regression tests as `*.test.mjs`, outside Playwright test
+  discovery. Run them with `node --test`.
+- Keep browser execution serial to limit WebGL and model-loading memory use.
+  Do not change production rendering behavior to make a screenshot pass.
+
+## Vitest conventions
+
+- Reuse `test/setup/vitestBrowser.setup.js` for renderer globals, custom
+  assertions, and the per-test `#vitest-fixture`.
+- Reuse existing viewer/viewport helpers and dispose viewers and WebGL contexts.
+- Preserve Vite shader handling, binary IFC/OBJ imports, WASM MIME handling,
+  `/data/` fixture routes, and Polly recording compatibility.
+- Unit/performance commands start Polly; geometry DDT commands start the
+  sibling `simple-ddt-server`. Do not conflate geometry references in
+  `Results.db` with visual PNG baselines.
+- Keep CI recording disabled: missing Polly recordings must fail rather than
+  silently request live services.
+
+## Visual comparison conventions
+
+- Discover IFC files from the selected short or long dataset. Reuse the
+  viewer harness and the shared renderer Vite asset/shader configuration.
+- Await IFC loading and camera setup before comparison. Keep diagnostic,
+  non-empty model, and WebGL context checks.
+- Compare only `#viewport-container` using the fixed perspective view without
+  camera flight. Preserve fixed viewport/device scale and deterministic options.
+- Use Playwright's stable screenshot comparison, not arbitrary sleeps.
+  Current settings are threshold `0.2`, zero pixels above that threshold,
+  and a 15-second screenshot timeout.
+- Loading is covered by the separate 100-minute per-test timeout. A missing
+  snapshot is not a loading timeout; inspect the error before changing limits.
+- Visual tests must not write geometry references to `Results.db`.
+
+## Baseline safety
+
+- Normal runs must not create or replace baselines automatically.
+- Create only missing Firefox baselines with
+  `npm run test-modelviewer-ddt-visual-init` or
+  `npm run test-modelviewer-ddt-visual-long-init`.
+- Use `-- --update-snapshots` only for an intentional, reviewed visual change;
+  never update baselines merely to hide a regression.
+- Preserve baseline separation by browser, dataset, and OS. Generate and
+  compare on the same OS/GPU environment; review PNG changes before committing.
+
+## Reports and filenames
+
+- Keep HTML output in `playwright-report/`, comparison artifacts in
+  `test-results/modelviewer-visual/`, and visual JUnit output in
+  `test-results/playwright-modelviewer-visual.xml`.
+- Keep Playwright's internal hashed files so the HTML image viewer works.
+- The custom reporter exports only actual comparison images directly into
+  `playwright-report/data/named/`: no subfolders, `-actual` suffix, expected
+  images, diff images, or full-page failure screenshots.
+- Use the matching expected attachment's baseline filename, including its
+  full long name. Never derive that name solely from the actual artifact:
+  Playwright may shorten it and insert a hash.
+- The flat folder cannot distinguish identical names across browsers/retries.
+  The last result in report order wins; run one browser at a time when needed.
+- Test naming changes against both short names and the long Allplan filename.
+
+## Targeted validation
+
+```sh
+npm run test-firefox-headless
+npm run test-chrome-headless
+npm run test-modelviewer-ddt
+npm run test-modelviewer-ddt-long
+npm run test-modelviewer-ddt-visual -- --grep "BasicProject.ifc"
+npm run test-modelviewer-ddt-visual-long -- --grep "AssemblyElement.ifc"
+node --test modelviewer-data-driven-tests/playwright/namedImagesReporter.test.mjs
+npm run eslint
+```
+
+Select the smallest relevant suite/filter rather than running every command.
+`npm test` runs Firefox with Istanbul coverage. Chromium visual projects are
+available through `npx playwright test --project=chromium` and
+`--project=chromium-long`. For comparison/reporting changes, verify a passing
+comparison and a controlled mismatch, inspect the exact exported filenames,
+and remove any temporary visual modification without updating baselines.

package/package.json

@@ -6,7 +6,7 @@
   "                 set there the full version string!                                              ": "",
   "                 e.g.: semverRange: '1.8.20-my-tag-name-01'                                      ": "",
   "================================================================================================-": "",
-  "version": "1.8.41-babel-webpack1.1",
+  "version": "1.8.41",
   "description": "bim+ renderer",
   "types": "types/bimplus-renderer.d.ts",
   "keywords": [
@@ -58,6 +58,7 @@
     "npm-publish-branch-lls": "npm run build-prod-lls && npm run publish --tag",
     "npm-pack-lls": "npm run build-prod-lls && npm pack",
     "profile": "webpack --config webpack.prod.js --profile --json > stats.json && webpack-bundle-analyzer stats.json",
+    "check-es2019": "node scripts/check-es2019.js",
     "//=============================================================================================": "",
     "// 1.)                   JUnit TESTS         Scripts starting test runs                        ": "",
     "//===================================================================================-=-=======": "",
@@ -94,7 +95,6 @@
     "test-vitest-modelviewer-firefox-long-watch": "start-server-and-test ddt-long-server-task tcp:localhost:3456 test-vitest-modelviewer-firefox-watch-task",
     "test-vitest-modelviewer-chrome-long-watch": "start-server-and-test ddt-long-server-task tcp:localhost:3456 test-vitest-modelviewer-chrome-watch-task",
     "test-polly-listen-task": "polly listen",
-    "check-es2019": "node scripts/check-es2019.js",
     "//===================== Test helpers to run test for one file                                  ": "",
     "test-one-file-chrome": "start-server-and-test test-polly-listen-task tcp:localhost:3000 \"npm run test-chrome-watch-task -- test/tests/OverlayPollyTests.js\"",
     "test-one-file-firefox": "start-server-and-test test-polly-listen-task tcp:localhost:3000 \"npm run test-firefox-watch-task -- test/tests/OverlayPollyTests.js\"",
@@ -145,7 +145,7 @@
     "file-loader": "6.2.0",
     "globals": "17.13.0",
     "jsdoc": "^4.0.5",
-    "moment-timezone": "^0.6.4",
+    "moment-timezone": "^0.6.5",
     "object-hash": "^3.0.0",
     "playwright": "1.64.1",
     "raw-loader": "4.0.2",

package/JSDOC_MIGRATION_PLAN.md

@@ -1,244 +0,0 @@
-# JSDoc Migration Plan
-
-## Goal
-
-Replace the `documentation` package with JSDoc tooling while preserving the existing documentation workflows:
-
-- HTML documentation in `./documentation`
-- Markdown API documentation in `./documentation/Bimplus_Renderer_doc.md`
-- Confluence-compatible Markdown in `./documentation/Bimplus_Renderer_doc_confluence.md`
-- The existing `build-doc*` npm script interface
-
-The migration should also remove the vulnerable transitive `vue-template-compiler` dependency.
-
-## Scope
-
-Files expected to change:
-
-- `package.json`
-- `package-lock.json`
-- New root-level `jsdoc.json` configuration
-- Existing `scripts/generate-api-markdown.js` renderer
-- `eslint.config.mjs` for scoped Node.js globals when linting the renderer
-- `README.md`
-- `documentation/Bimplus Renderer basics.md` as the HTML landing-page source
-- `documentation/convert_to_confluence_md.py`
-- Remove obsolete `doc_config.yml`
-- Generated files under `documentation/`
-
-The following should remain functionally unchanged:
-
-- JSDoc comments in `src/*.js`
-- 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
-
-Remove `documentation` from `devDependencies` and add:
-
-- `jsdoc` for parsing source comments and generating HTML
-- A repository-owned Markdown renderer using JSDoc's structured doclets
-
-Remove any old generator dependencies and install JSDoc:
-
-```powershell
-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`
-
-Create a root-level JSDoc configuration with these requirements:
-
-- Include JavaScript files under `src/`
-- Recurse through the source directory
-- Parse ES module syntax
-- Write HTML output to `./documentation`
-- Use `documentation/Bimplus Renderer basics.md` as the documentation landing-page content when supported
-- Enable JSDoc's Markdown plugin and recursive source discovery
-
-Proposed configuration:
-
-```json
-{
-  "source": {
-    "include": ["src"],
-    "includePattern": ".*\\.js$",
-    "excludePattern": "(^|[\\\\/])node_modules[\\\\/]"
-  },
-  "opts": {
-    "destination": "./documentation",
-    "recurse": true,
-    "readme": "./documentation/Bimplus Renderer basics.md"
-  },
-  "templates": {
-    "cleverLinks": false,
-    "monospaceLinks": true
-  },
-  "plugins": [
-    "plugins/markdown"
-  ]
-}
-```
-
-`opts.recurse: true` includes deeper source directories than the previous shallow globs. Review the additional doclets and exclude non-public implementation modules as needed. 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 configuration against the installed JSDoc version.
-
-### 3. Update npm scripts
-
-Replace the current `documentation` commands with JSDoc equivalents while retaining the existing script names:
-
-```json
-{
-  "lint-doc": "jsdoc --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"
-}
-```
-
-`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 classes, modules, 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: container 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. Existing `@private` tags with values warn under JSDoc; do not use `--pedantic` unless those source comments are corrected. `--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
-
-Run the formats individually first:
-
-```powershell
-npm run lint-doc
-npm run build-doc
-npm run build-docMd
-npm run build-docConf
-```
-
-Then run the complete workflow:
-
-```powershell
-npm run build-docAll
-```
-
-The Confluence converter should continue reading `Bimplus_Renderer_doc.md` from `documentation/` and writing `Bimplus_Renderer_doc_confluence.md`. 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 `RendererApidescription-{fragment}`, emit a matching `<a id="RendererApidescription-{fragment}" name="RendererApidescription-{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 `RendererApidescription-` prefix.
-
-### 5. Review generated output
-
-Check the following:
-
-- `documentation/index.html` opens successfully
-- HTML assets load without missing-file errors
-- All documented public classes, modules, namespaces, methods, 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 `RendererApidescription-` 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 class/module, an instance method containing `+`, a dotted member, and a nested 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 `README.md` to describe:
-
-- `jsdoc.json`
-- `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 jsdoc-to-markdown vue-template-compiler
-```
-
-The command should report that none of these packages is installed, or that they are not found in the dependency tree. Search scripts, READMEs, and the lockfile for stale `jsdoc2md`/`jsdoc-to-markdown` references; the 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.
-
-## Verification Checklist
-
-Run the documentation workflow and existing project checks:
-
-```powershell
-npm install
-npm run lint-doc
-npm run build-docAll
-npm run build
-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
-- Generated HTML, Markdown, and Confluence files exist
-- 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.
-
-## Rollback
-
-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` and restore `scripts/generate-api-markdown.js` to its pre-migration contents if rollback is required.
-3. Restore the previous generated `documentation/` output.
-4. Reassess the JSDoc configuration and renderer before retrying.
-
-Do not modify application source code as part of rollback.
-
-## Acceptance Criteria
-
-The migration is complete when:
-
-- `documentation` is no longer a development dependency
-- JSDoc generates readable HTML from the reviewed JavaScript files under `src/`
-- 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
-- Application build and tests remain unaffected

package/MOMENT_TIMEZONE_INTEGRATION.md

@@ -1,38 +0,0 @@
-# Moment Timezone Integration
-
-The `setSunPosition` function now supports optional moment-timezone integration. Here are the different ways to use it:
-
-## Inject programmatically
-
-```javascript
-import { injectMomentTimezone, hasMomentTimezone } from 'bimplus-renderer';
-
-// If you have moment-timezone available in your application
-import moment from 'moment-timezone';
-
-// You can check if moment-timezone is available before calling the function:
-if (!hasMomentTimezone()) {
-  console.log('Injecting moment-timezone for sun positioning features');
-  injectMomentTimezone(moment);
-}
-
-// Now you can use setSunPosition
-viewport3D.setSunPosition({
-  northDirection: 0,
-  year: 2024,
-  month: 6,
-  day: 21,
-  hours: 12,
-  minutes: 0,
-  timezone: 'Europe/Berlin',
-  latitude: 52.5200,
-  longitude: 13.4050,
-  showSky: true
-});
-```
-
-This approach allows:
-- Backward compatibility for existing users who have moment-timezone
-- Forward compatibility for new users who don't want the dependency
-- Clear error messages when the functionality is used without the required library
-- Flexibility in how the library is provided (npm, CDN, injection)

package/MOMENT_TIMEZONE_INTEGRATION_FOR_TEST.md

@@ -1,57 +0,0 @@
-# Test-Only Moment-Timezone Integration
-
-## Overview
-
-This solution successfully implements moment-timezone dependency injection specifically for tests while keeping the production code completely free of the dependency.
-
-## Implementation
-
-### 1. Production Code (Optional Dependency)
-- **[src/viewport3d.js](src/viewport3d.js)**: Contains optional moment-timezone detection
-- **[src/utils/momentTimezoneInjector.js](src/utils/momentTimezoneInjector.js)**: Utility for external injection (for BimExplorer app)
-- Production builds work without moment-timezone installed
-- Runtime errors provide clear instructions when moment-timezone features are needed
-
-### 2. Test-Only Injection
-- **[test/setup/momentTimezoneInjector.js](test/setup/momentTimezoneInjector.js)**: Test setup that injects moment-timezone globally
-- **package.json**: moment-timezone installed as `devDependency` only
-- **[test/setup/vitestBrowser.setup.js](test/setup/vitestBrowser.setup.js)**: Imports and injects moment-timezone before test modules
-
-### 3. Test Configuration
-```javascript
-// In test/setup/vitestBrowser.setup.js
-import momentTimezone from 'moment-timezone';
-globalThis.MomentTZ = globalThis.moment = momentTimezone;
-```
-
-## How It Works
-
-### For Tests
-1. Vitest loads the browser setup before test modules
-2. The setup imports moment-timezone (available as a dev dependency)
-3. Injects it into global scope (`window.moment`)
-4. All tests run with moment-timezone available
-5. Sun calculation tests pass with accurate timezone handling
-
-### For Production
-1. Production code uses optional detection: `getMomentTZ()`
-2. If moment-timezone isn't found, production code either:
-   - Throws descriptive error for features requiring it (`setSunPosition`)
-3. Build process excludes moment-timezone from production bundle
-4. Users can inject moment-timezone via BimExplorer app if needed
-
-## File Changes
-
-### New Files
-- `test/setup/momentTimezoneInjector.js` - Test environment setup
-
-### Modified Files  
-- `test/setup/vitestBrowser.setup.js` - Imports and injects moment-timezone before test modules
-- `package.json` - Added moment-timezone as devDependency
-
-### Existing Files (Unchanged)
-- `src/viewport3d.js` - Already has optional moment-timezone detection
-- `src/utils/momentTimezoneInjector.js` - Already provides injection utilities
-- All test files - Work seamlessly with injected moment-timezone
-
-This solution provides the best of both worlds: comprehensive test coverage with accurate timezone calculations, while maintaining a lean production build without unnecessary dependencies.