Canadian-Geospatial-Platform · jolevesq · Mar 2, 2026 · Feb 26, 2026 · Feb 26, 2026 · Feb 27, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -193,7 +193,7 @@ JSDoc should NOT:
 
 - `@param` - Parameter descriptions
 - `@returns` - Return value descriptions
-- `@throws` - Document thrown exceptions
+- `@throws` - Document thrown exceptions (@throws {TheErrorType} (description)  e.g. @throws {LayerNotGeoJsonError} When ...)
 - `@example` - Usage examples
 - `@deprecated` - Mark deprecated APIs
 - `@see` - Reference related code

diff --git a/docs/programming/best-practices.md b/docs/programming/best-practices.md
@@ -165,6 +165,7 @@ It should NOT:
  * @param geoviewLayerId - UUID of the GeoView layer.
  * @param signal - Optional abort signal for request cancellation.
  * @returns Parsed layer metadata object.
+ * @throws {LayerNotGeoJsonError} When an error to ...
  */
 async function fetchMetadata(
   geoviewLayerId: string,
@@ -175,7 +176,7 @@ async function fetchMetadata(
 Tags Worth Using
 - @param
 - @returns
-- @throws
+- @throws (@throws {TheErrorType} (description)  e.g. @throws {LayerNotGeoJsonError} When...)
 - @example
 - @deprecated
 - @see

diff --git a/docs/programming/troubleshooting.md b/docs/programming/troubleshooting.md
@@ -0,0 +1,89 @@
+# Troubleshooting & Service-Specific Fixes
+
+Known issues and fixes for specific service types. Document non-obvious errors here so the team doesn't re-investigate.
+
+---
+
+## How to Use This Document
+
+Each entry has four parts: **Problem** → **Root Cause** → **Fix** → **Takeaways**.
+
+<details>
+<summary><strong>Template for New Entries</strong> (click to expand)</summary>
+
+### [Short Title]
+
+> [GitHub Issue #XXXX](https://github.com/Canadian-Geospatial-Platform/geoview/issues/XXXX)
+
+**Problem:** What happens / error message.
+
+**Root Cause:** Why it happens.
+
+**Fix:** What was changed and where.
+
+**Takeaways:**
+
+- Reusable lessons.
+
+</details>
+
+---
+
+## GeoTIFF
+
+### Embedded Color Map / Palette Rendering
+
+> [GitHub Issue #3166](https://github.com/Canadian-Geospatial-Platform/geoview/issues/3166)
+
+**Problem:** GeoTIFF layers with embedded color palettes (e.g., land cover classification) render as a solid black square, show opaque black outside the data extent, and display color fringes at pixel boundaries when zoomed in.
+
+**Root Cause:**
+
+| Symptom               | Cause                                                                                               |
+| --------------------- | --------------------------------------------------------------------------------------------------- |
+| Solid black           | OL normalizes pixel values to `0–1`, so raw value `10` becomes `0.039` → palette index `0` (black). |
+| Opaque outside pixels | Palette index `0` (nodata) has no transparency.                                                     |
+| Color fringes         | Bilinear interpolation blends adjacent palette indices, producing unrelated colors.                 |
+
+**Fix:**
+
+1. Extract color map before layer creation — `extractGeotiffColorMap()` in `onProcessLayerMetadata()`, stored on `layerConfig.embeddedColorMap`.
+2. `normalize: false` on the source so `['band', 1]` returns raw integers.
+3. `interpolate: false` (nearest-neighbor) to prevent blending between class indices.
+4. Palette index `0` → `rgba(0,0,0,0)` for transparent nodata.
+5. Convert tuples to CSS `rgba()` strings — OL palette expressions expect color strings, not number arrays.
+
+Files: `geotiff.ts` (`createGeoTIFFSource`, `onProcessLayerMetadata`), `gv-geotiff.ts` (`#applyColorMapStyle`), `geotiff-layer-entry-config.ts` (`embeddedColorMap`), `utilities.ts` (`extractGeotiffColorMap`).
+
+**Takeaways:**
+
+- Never replace an OL source at runtime if events are already bound — configure it correctly from the start.
+- Use `normalize: false` when pixel values have semantic meaning (indices, classes).
+- Use `interpolate: false` for categorical rasters; bilinear is only for continuous data.
+
+---
+
+## WMS
+
+### Inherited TIME Dimension Breaks GetFeatureInfo
+
+> [GitHub Issue #3234](https://github.com/Canadian-Geospatial-Platform/geoview/issues/3234)
+
+**Problem:** `GetFeatureInfo` fails with `LayerNotDefined` when `TIME` is included for child layers that inherit a time dimension from a parent group but don't actually support it (e.g., `dsm-hillshade` under `elevation-hrdem-mosaic`). Removing `TIME` makes the request succeed.
+
+**Root Cause:** WMS child layers inherit `<Dimension>` from parent groups per spec. But derived layers (hillshade, slope, RGB composites) are mosaics — the server doesn't support temporal slicing for them. GeoView sees time on the ancestor and appends `TIME`, which the server rejects.
+
+**Fix:** Fixed at the **service level** — time dimensions were removed from layers that don't support them.
+
+Recommended client-side approach for robustness:
+
+- Treat a layer as time-enabled only if it has its **own** `<Extent>` or discrete time values (not just an inherited `<Dimension>`).
+- **Fallback**: if `GetFeatureInfo` fails with `TIME`, retry without it. If retry succeeds, mark the layer as non-time-enabled.
+
+**Takeaways:**
+
+- WMS dimension inheritance is unreliable — inherited `<Dimension>` doesn't guarantee the child supports that dimension.
+- Derived/mosaic layers (hillshade, slope, aspect) typically don't support temporal queries.
+- Validate time support per-layer, not per-service.
+
+---
diff --git a/docs/sidebar.md b/docs/sidebar.md
@@ -2,48 +2,40 @@
 - [Getting Started](README.md)
 
 - **Getting Started**
-
   - [Documentation Overview](README.md)
 
 - **Configuration**
-
   - [Creating Maps](app/config/create-map.md)
   - [Configuration Reference](app/config/configuration-reference.md)
 
 - **API Reference**
-
   - [CGPV API](app/api/cgpv.md)
   - [MapViewer API](app/api/map-viewer-api.md)
   - [Layer API](app/api/layer-api.md)
   - [Geometry API](app/api/geometry-api.md)
   - [Utilities](app/api/utilities.md)
 
 - **Layers**
-
   - [Layers Guide](app/layers/layers.md)
   - [LayerSets](app/layers/layersets.md)
 
 - **Events**
-
   - [Event System](app/events/event-system.md)
   - [Map Events](app/events/map-events.md)
   - [Layer Events](app/events/layer-events.md)
   - [Event Processors](app/events/event-processors.md)
 
 - **Packages**
-
   - [Packages Overview](app/packages/README.md)
   - [Core Packages](app/packages/geoview-core-packages.md)
   - [Package Development](app/packages/core-packages.md)
 
 - **Testing**
-
   - [Test Suite Guide](app/testing/README.md)
   - [Using Tests](app/testing/using-test-suite.md)
   - [Creating Tests](app/testing/creating-tests.md)
 
 - **Developer Documentation**
-
   - [Best Practices](programming/best-practices.md)
   - [Event Processor Architecture](programming/event-processor-architecture.md)
   - [LayerSet Architecture](programming/layerset-architecture.md)
@@ -52,6 +44,7 @@
   - [Using Types](programming/using-type.md)
   - [Logging](programming/logging.md)
   - [Object Oriented](programming/object-oriented.md)
+  - [Troubleshooting](programming/troubleshooting.md)
 
 - **TypeDoc API**
   - [TypeScript API Reference](../docs/typedoc/index.html ":ignore")
diff --git a/packages/geoview-core/package.json b/packages/geoview-core/package.json
@@ -28,7 +28,7 @@
   "scripts": {
     "serve": "npm run format && npm run fix && webpack serve --progress --color --config webpack.dev.js",
     "build": "npm run format && npm run fix && npm run doc && webpack --progress --color --config webpack.prod.js && npm run generate.d.ts",
-    "doc": "typedoc src/app.tsx --logLevel Error --out public/typeDocAPI",
+    "doc": "typedoc src/app.tsx --logLevel Error --out public/typeDocAPI --includeVersion --entryPointStrategy expand",
     "deploy": "gh-pages -d dist -verbose",
     "test": "jest",
     "update_test": "jest --updateSnapshot",

diff --git a/packages/geoview-core/public/configs/navigator/demos/23-initial-settings.json b/packages/geoview-core/public/configs/navigator/demos/23-initial-settings.json
@@ -22,7 +22,8 @@
             "zoom": false
           },
           "states": {
-            "visible": false
+            "visible": false,
+            "opacity": 0.5
           }
         },
         "listOfLayerEntryConfig": [

diff --git a/packages/geoview-core/public/configs/navigator/layers/esri-dynamic.json b/packages/geoview-core/public/configs/navigator/layers/esri-dynamic.json
@@ -25,7 +25,8 @@
               },
               "states": {
                 "queryable": false,
-                "hoverable": false
+                "hoverable": false,
+                "opacity": 0.5
               }
             }
           }

diff --git a/packages/geoview-core/public/configs/navigator/layers/geotiff.json b/packages/geoview-core/public/configs/navigator/layers/geotiff.json
@@ -26,7 +26,7 @@
       },
       {
         "geoviewLayerId": "datacube-vegetation",
-        "geoviewLayerName": "Datacube Vegetation - Github Issue #3166",
+        "geoviewLayerName": "Datacube Vegetation",
         "metadataAccessPath": "https://datacube.services.geo.ca/stac/api/collections/vegetation/items/vegetation-2020",
         "geoviewLayerType": "GeoTIFF",
         "listOfLayerEntryConfig": [

diff --git a/packages/geoview-core/public/datasets/geojson/metadata-blank.meta b/packages/geoview-core/public/datasets/geojson/metadata-blank.meta
@@ -31,7 +31,7 @@
               "values": [],
               "settings": {
                 "type": "simpleSymbol",
-                "symbol": "star"
+                "symbol": "square"
               }
             }
           ]