bimplus-renderer 1.8.41-babel-webpack1.0 → 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.