@saschabrunnerch/arcgis-maps-sdk-js-ai-context 0.0.1 → 0.1.0

package/contexts/4.34/{claude → skills}/arcgis-core-maps/SKILL.md

@@ -1,739 +1,739 @@
----
-name: arcgis-core-maps
-description: Create 2D and 3D maps using ArcGIS Maps SDK for JavaScript. Use for initializing maps, scenes, views, and navigation. Supports both Map Components (web components) and Core API approaches.
----
-
-# ArcGIS Core Maps
-
-Use this skill when creating 2D maps (MapView) or 3D scenes (SceneView) with the ArcGIS Maps SDK for JavaScript.
-
-## Import Patterns
-
-### Direct ESM Imports (Recommended for Build Tools)
-Use with Vite, webpack, Rollup, or other build tools:
-```javascript
-import Map from "@arcgis/core/Map.js";
-import MapView from "@arcgis/core/views/MapView.js";
-import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";
-```
-- Tree-shakeable
-- Standard JavaScript modules
-- Best for production applications
-
-### Dynamic Imports (CDN / No Build Tools)
-Use with CDN script tags when no build step is available:
-```javascript
-const Map = await $arcgis.import("@arcgis/core/Map.js");
-const MapView = await $arcgis.import("@arcgis/core/views/MapView.js");
-
-// Multiple imports
-const [FeatureLayer, Graphic] = await $arcgis.import([
-  "@arcgis/core/layers/FeatureLayer.js",
-  "@arcgis/core/Graphic.js"
-]);
-```
-- Works with Map Components (web components)
-- No build step required
-- Good for quick prototypes and demos
-- Requires `<script src="https://js.arcgis.com/4.34/"></script>` in HTML
-
-> **Note:** The examples in this skill use Direct ESM imports. For CDN usage, replace `import X from "path"` with `const X = await $arcgis.import("path")`.
-
-## Autocasting vs Explicit Classes (TypeScript)
-
-The ArcGIS SDK supports [autocasting](https://developers.arcgis.com/javascript/latest/autocasting/) - passing plain objects instead of class instances. Understanding when to use each approach is important for TypeScript projects.
-
-### When to Use Explicit Classes (Non-Autocast)
-
-Use `new SimpleRenderer()`, `new Point()`, etc. when:
-
-- **You need instance methods or `instanceof` checks**
-- **Building shared internal libraries** - constructor APIs surface breaking changes at compile time
-- **You want strong editor discoverability** - `new SimpleRenderer({ ... })` exposes properties clearly
-- **You mutate objects incrementally** - long-lived instances are clearer as real classes
-
-```typescript
-import SimpleRenderer from "@arcgis/core/renderers/SimpleRenderer.js";
-import SimpleMarkerSymbol from "@arcgis/core/symbols/SimpleMarkerSymbol.js";
-
-const renderer = new SimpleRenderer({
-  symbol: new SimpleMarkerSymbol({
-    color: [226, 119, 40],
-    size: 8
-  })
-});
-```
-
-### When to Use Autocasting
-
-Use plain objects with `type` property when:
-
-- **Configuration-heavy code** - renderers, symbols, popups are usually data, not behavior
-- **UI-driven configuration** - React state → plain objects → SDK properties is simpler
-- **Serialization and reuse matter** - configs can be stored, diffed, tested, reused
-- **Property updates after creation** - `layer.renderer = { ... }` works cleanly in React `useEffect`
-
-```typescript
-// Use 'as const' or 'satisfies' to keep discriminated unions narrow
-const renderer = {
-  type: "simple",
-  symbol: {
-    type: "simple-marker",
-    color: [226, 119, 40],
-    size: 8
-  }
-} as const;
-
-// Or with satisfies for better type inference
-import type { SimpleRenderer } from "@arcgis/core/renderers/SimpleRenderer.js";
-
-const renderer = {
-  type: "simple",
-  symbol: {
-    type: "simple-marker",
-    color: [226, 119, 40],
-    size: 8
-  }
-} satisfies __esri.SimpleRendererProperties;
-```
-
-### TypeScript Best Practices
-
-The real TypeScript concern is keeping discriminated unions narrow:
-
-```typescript
-// ❌ BAD - type widens to string
-const symbol = { type: "simple-marker", color: "red" };
-
-// ✅ GOOD - type stays literal
-const symbol = { type: "simple-marker", color: "red" } as const;
-
-// ✅ GOOD - explicit type annotation
-const symbol: __esri.SimpleMarkerSymbolProperties = {
-  type: "simple-marker",
-  color: "red"
-};
-```
-
-### Recommended Default
-
-- **Autocast for configuration** (renderers, symbols, popups, labels)
-- **Explicit classes for behavior** (when you need methods or instanceof)
-- **Use `as const` or `satisfies`** to maintain type safety with autocasting
-
-## Two Approaches
-
-### 1. Map Components (Modern - Recommended)
-Web components approach using `<arcgis-map>` and `<arcgis-scene>`.
-
-### 2. Core API
-Traditional JavaScript approach using `Map`, `MapView`, and `SceneView` classes.
-
-## CDN Setup
-
-### Map Components Approach
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>ArcGIS Map</title>
-  <style>
-    html, body { height: 100%; margin: 0; }
-  </style>
-  <!-- Load Calcite components -->
-  <script type="module" src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"></script>
-  <!-- Load ArcGIS Maps SDK -->
-  <script src="https://js.arcgis.com/4.34/"></script>
-  <!-- Load Map components -->
-  <script type="module" src="https://js.arcgis.com/4.34/map-components/"></script>
-</head>
-<body>
-  <arcgis-map basemap="topo-vector" center="-118.24,34.05" zoom="12">
-    <arcgis-zoom slot="top-left"></arcgis-zoom>
-  </arcgis-map>
-</body>
-</html>
-```
-
-### Core API Approach
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>ArcGIS Map</title>
-  <style>
-    html, body, #viewDiv { height: 100%; margin: 0; }
-  </style>
-  <!-- REQUIRED: main.css for Core API -->
-  <link rel="stylesheet" href="https://js.arcgis.com/4.34/esri/themes/light/main.css" />
-  <script src="https://js.arcgis.com/4.34/"></script>
-</head>
-<body>
-  <div id="viewDiv"></div>
-  <script type="module">
-    import Map from "@arcgis/core/Map.js";
-    import MapView from "@arcgis/core/views/MapView.js";
-
-    const map = new Map({ basemap: "topo-vector" });
-    const view = new MapView({
-      container: "viewDiv",
-      map: map,
-      center: [-118.24, 34.05], // [longitude, latitude]
-      zoom: 12
-    });
-  </script>
-</body>
-</html>
-```
-
-## 2D Maps
-
-### Map Components
-```html
-<arcgis-map basemap="topo-vector" center="-118.24,34.05" zoom="12">
-  <arcgis-zoom slot="top-left"></arcgis-zoom>
-  <arcgis-compass slot="top-left"></arcgis-compass>
-  <arcgis-home slot="top-left"></arcgis-home>
-  <arcgis-locate slot="top-left"></arcgis-locate>
-</arcgis-map>
-
-<script type="module">
-  const mapElement = document.querySelector("arcgis-map");
-  await mapElement.viewOnReady(); // Wait for view to be ready
-  const view = mapElement.view;   // Access the MapView
-  const map = mapElement.map;     // Access the Map
-</script>
-```
-
-### Core API
-```javascript
-import Map from "@arcgis/core/Map.js";
-import MapView from "@arcgis/core/views/MapView.js";
-
-const map = new Map({ basemap: "streets-vector" });
-
-const view = new MapView({
-  container: "viewDiv",
-  map: map,
-  center: [-118.24, 34.05],
-  zoom: 12,
-  // Optional constraints
-  constraints: {
-    minZoom: 5,
-    maxZoom: 18,
-    rotationEnabled: false
-  }
-});
-```
-
-## 3D Scenes
-
-### Map Components
-```html
-<arcgis-scene basemap="topo-3d" ground="world-elevation">
-  <arcgis-zoom slot="top-left"></arcgis-zoom>
-  <arcgis-navigation-toggle slot="top-left"></arcgis-navigation-toggle>
-</arcgis-scene>
-
-<script type="module">
-  const sceneElement = document.querySelector("arcgis-scene");
-  await sceneElement.viewOnReady();
-  const view = sceneElement.view; // SceneView
-</script>
-```
-
-### Core API
-```javascript
-import Map from "@arcgis/core/Map.js";
-import SceneView from "@arcgis/core/views/SceneView.js";
-
-const map = new Map({
-  basemap: "topo-3d",
-  ground: "world-elevation"
-});
-
-const view = new SceneView({
-  container: "viewDiv",
-  map: map,
-  camera: {
-    position: {
-      longitude: -118.24,
-      latitude: 34.05,
-      z: 25000 // altitude in meters
-    },
-    heading: 0,   // compass direction
-    tilt: 45      // 0 = straight down, 90 = horizon
-  }
-});
-```
-
-## Loading WebMaps and WebScenes
-
-### WebMap (2D)
-```html
-<!-- Map Components -->
-<arcgis-map item-id="f2e9b762544945f390ca4ac3671cfa72">
-  <arcgis-zoom slot="top-left"></arcgis-zoom>
-</arcgis-map>
-```
-
-```javascript
-// Core API
-import MapView from "@arcgis/core/views/MapView.js";
-import WebMap from "@arcgis/core/WebMap.js";
-
-const webmap = new WebMap({
-  portalItem: { id: "f2e9b762544945f390ca4ac3671cfa72" }
-});
-
-const view = new MapView({
-  map: webmap,
-  container: "viewDiv"
-});
-```
-
-### WebScene (3D)
-```html
-<!-- Map Components -->
-<arcgis-scene item-id="YOUR_WEBSCENE_ID">
-  <arcgis-zoom slot="top-left"></arcgis-zoom>
-</arcgis-scene>
-```
-
-```javascript
-// Core API
-import SceneView from "@arcgis/core/views/SceneView.js";
-import WebScene from "@arcgis/core/WebScene.js";
-
-const webscene = new WebScene({
-  portalItem: { id: "YOUR_WEBSCENE_ID" }
-});
-
-const view = new SceneView({
-  map: webscene,
-  container: "viewDiv"
-});
-```
-
-## Navigation Components
-
-| Component | Purpose |
-|-----------|---------|
-| `arcgis-zoom` | Zoom in/out buttons |
-| `arcgis-compass` | Orientation indicator, click to reset north |
-| `arcgis-home` | Return to initial extent |
-| `arcgis-locate` | Find user's location |
-| `arcgis-navigation-toggle` | Switch between pan/rotate modes (3D) |
-| `arcgis-fullscreen` | Toggle fullscreen mode |
-| `arcgis-scale-bar` | Display map scale |
-
-### Slot Positions
-```html
-<arcgis-map basemap="streets-vector">
-  <arcgis-zoom slot="top-left"></arcgis-zoom>
-  <arcgis-home slot="top-left"></arcgis-home>
-  <arcgis-search slot="top-right"></arcgis-search>
-  <arcgis-legend slot="bottom-left"></arcgis-legend>
-  <arcgis-scale-bar slot="bottom-right"></arcgis-scale-bar>
-</arcgis-map>
-```
-
-Available slots: `top-left`, `top-right`, `bottom-left`, `bottom-right`, `manual`
-
-## View Configuration
-
-### Setting Initial Extent
-```javascript
-// By center and zoom
-const view = new MapView({
-  container: "viewDiv",
-  map: map,
-  center: [-118.24, 34.05],
-  zoom: 12
-});
-
-// By scale
-const view = new MapView({
-  container: "viewDiv",
-  map: map,
-  center: [-118.24, 34.05],
-  scale: 50000 // 1:50,000
-});
-
-// By extent
-const view = new MapView({
-  container: "viewDiv",
-  map: map,
-  extent: {
-    xmin: -118.5,
-    ymin: 33.8,
-    xmax: -117.9,
-    ymax: 34.3,
-    spatialReference: { wkid: 4326 }
-  }
-});
-```
-
-### Programmatic Navigation
-```javascript
-// Go to location
-await view.goTo({
-  center: [-118.24, 34.05],
-  zoom: 15
-});
-
-// Animated navigation
-await view.goTo(
-  { center: [-118.24, 34.05], zoom: 15 },
-  { duration: 2000, easing: "ease-in-out" }
-);
-
-// Go to extent
-await view.goTo(layer.fullExtent);
-
-// Go to features
-await view.goTo(featureSet.features);
-```
-
-### View Constraints
-```javascript
-// Constrain zoom levels
-view.constraints = {
-  minZoom: 5,
-  maxZoom: 18
-};
-
-// Constrain to area
-view.constraints = {
-  geometry: layer.fullExtent,
-  minScale: 500000
-};
-
-// Disable rotation
-view.constraints = {
-  rotationEnabled: false
-};
-```
-
-## Event Handling
-
-```javascript
-// View ready
-view.when(() => {
-  console.log("View is ready");
-});
-
-// Click event
-view.on("click", (event) => {
-  console.log("Clicked at:", event.mapPoint);
-});
-
-// Pointer move
-view.on("pointer-move", (event) => {
-  const point = view.toMap(event);
-  console.log("Mouse at:", point.longitude, point.latitude);
-});
-
-// Extent change
-view.watch("extent", (extent) => {
-  console.log("Extent changed:", extent);
-});
-
-// Stationary (after pan/zoom completes)
-view.watch("stationary", (isStationary) => {
-  if (isStationary) {
-    console.log("Navigation complete");
-  }
-});
-```
-
-## Module Imports
-
-```javascript
-// Single import
-import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";
-
-// Multiple imports
-import Map from "@arcgis/core/Map.js";
-import MapView from "@arcgis/core/views/MapView.js";
-import Graphic from "@arcgis/core/Graphic.js";
-```
-
-## Common Basemaps
-
-| Basemap ID | Description |
-|------------|-------------|
-| `streets-vector` | Street map |
-| `topo-vector` | Topographic |
-| `satellite` | Satellite imagery |
-| `hybrid` | Satellite with labels |
-| `dark-gray-vector` | Dark gray canvas |
-| `gray-vector` | Light gray canvas |
-| `osm` | OpenStreetMap |
-| `topo-3d` | 3D topographic (SceneView) |
-
-## esriRequest (HTTP Requests)
-
-### Basic Request
-```javascript
-import esriRequest from "@arcgis/core/request.js";
-
-// GET request with JSON response
-const response = await esriRequest(url, {
-  query: { f: "json" },
-  responseType: "json"
-});
-
-console.log("Status:", response.httpStatus);
-console.log("Data:", response.data);
-```
-
-### Request with Options
-```javascript
-const response = await esriRequest(url, {
-  query: {
-    f: "json",
-    param1: "value1"
-  },
-  responseType: "json",  // "json", "text", "array-buffer", "blob", "image"
-  method: "post",        // "auto", "get", "post"
-  body: formData,        // For POST requests
-  timeout: 30000,        // Timeout in ms
-  headers: {
-    "X-Custom-Header": "value"
-  }
-});
-```
-
-### Download Binary Data
-```javascript
-// Image response
-const imageResponse = await esriRequest(imageUrl, {
-  responseType: "image"
-});
-const imageElement = imageResponse.data;
-
-// Binary data
-const binaryResponse = await esriRequest(fileUrl, {
-  responseType: "array-buffer"
-});
-const arrayBuffer = binaryResponse.data;
-```
-
-## Planetary Visualization (Mars)
-
-### Mars Scene
-```html
-<arcgis-scene>
-  <arcgis-zoom slot="top-left"></arcgis-zoom>
-  <arcgis-navigation-toggle slot="top-left"></arcgis-navigation-toggle>
-</arcgis-scene>
-
-<script type="module">
-  import ElevationLayer from "@arcgis/core/layers/ElevationLayer.js";
-  import TileLayer from "@arcgis/core/layers/TileLayer.js";
-  import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";
-
-  const viewElement = document.querySelector("arcgis-scene");
-
-  // Set Mars spatial reference
-  viewElement.spatialReference = { wkid: 104971 }; // Mars 2000
-
-  // Configure camera for Mars
-  viewElement.camera = {
-    position: {
-      x: 27.63423,
-      y: -6.34466,
-      z: 1281525,
-      spatialReference: { wkid: 104971 }
-    },
-    heading: 332,
-    tilt: 37
-  };
-
-  await viewElement.viewOnReady();
-
-  // Mars elevation
-  const marsElevation = new ElevationLayer({
-    url: "https://astro.arcgis.com/arcgis/rest/services/OnMars/MDEM200M/ImageServer"
-  });
-  viewElement.ground = { layers: [marsElevation] };
-
-  // Mars imagery
-  const marsImagery = new TileLayer({
-    url: "https://astro.arcgis.com/arcgis/rest/services/OnMars/MDIM/MapServer",
-    title: "Mars Imagery"
-  });
-  viewElement.map.add(marsImagery);
-</script>
-```
-
-## Overview Map (Synchronized Views)
-
-### Overview Map with Scene
-```html
-<arcgis-scene basemap="hybrid" ground="world-elevation">
-  <arcgis-zoom slot="top-left"></arcgis-zoom>
-  <!-- Embed overview map inside scene -->
-  <arcgis-map basemap="topo-vector" id="overviewDiv" slot="top-right"></arcgis-map>
-</arcgis-scene>
-
-<style>
-  #overviewDiv { width: 300px; height: 200px; border: 1px solid black; }
-</style>
-
-<script type="module">
-  import Graphic from "@arcgis/core/Graphic.js";
-  import reactiveUtils from "@arcgis/core/core/reactiveUtils.js";
-
-  const sceneElement = document.querySelector("arcgis-scene");
-  const overviewElement = document.querySelector("arcgis-map");
-
-  await sceneElement.viewOnReady();
-  await overviewElement.viewOnReady();
-
-  // Disable rotation on overview
-  overviewElement.constraints.rotationEnabled = false;
-  overviewElement.view.ui.components = [];
-
-  // Add visible area graphic
-  const visibleAreaGraphic = new Graphic({
-    symbol: {
-      type: "simple-fill",
-      color: [0, 0, 0, 0.5],
-      outline: null
-    }
-  });
-  overviewElement.graphics.add(visibleAreaGraphic);
-
-  // Sync overview with main scene
-  reactiveUtils.watch(
-    () => sceneElement.visibleArea,
-    async (visibleArea) => {
-      visibleAreaGraphic.geometry = visibleArea;
-      await overviewElement.goTo(visibleArea);
-    },
-    { initial: true }
-  );
-</script>
-```
-
-## promiseUtils (Async Utilities)
-
-### Debounce
-```javascript
-import promiseUtils from "@arcgis/core/core/promiseUtils.js";
-
-// Create debounced function
-const debouncedUpdate = promiseUtils.debounce(async () => {
-  // This only runs after 300ms of no calls
-  await updateFeatures();
-});
-
-view.on("pointer-move", () => {
-  debouncedUpdate();
-});
-```
-
-### Abort Error Handling
-```javascript
-import promiseUtils from "@arcgis/core/core/promiseUtils.js";
-
-const abortController = new AbortController();
-
-try {
-  await someAsyncOperation({ signal: abortController.signal });
-} catch (error) {
-  if (promiseUtils.isAbortError(error)) {
-    // Operation was intentionally cancelled
-    console.log("Operation cancelled");
-  } else {
-    // Real error
-    throw error;
-  }
-}
-
-// Cancel the operation
-abortController.abort();
-```
-
-### Create Resolver
-```javascript
-import promiseUtils from "@arcgis/core/core/promiseUtils.js";
-
-// Create a promise that can be resolved/rejected externally
-const { promise, resolve, reject } = promiseUtils.createResolver();
-
-// Later, resolve or reject
-resolve(result);
-// or
-reject(error);
-
-// Use the promise
-const result = await promise;
-```
-
-## reactiveUtils (Property Watching)
-
-### Watch Properties
-```javascript
-import reactiveUtils from "@arcgis/core/core/reactiveUtils.js";
-
-// Watch single property
-reactiveUtils.watch(
-  () => view.scale,
-  (scale) => console.log("Scale:", scale)
-);
-
-// Watch with initial value
-reactiveUtils.watch(
-  () => view.extent,
-  (extent) => console.log("Extent:", extent),
-  { initial: true }
-);
-
-// Watch once
-reactiveUtils.once(
-  () => view.stationary === true
-).then(() => {
-  console.log("View became stationary");
-});
-
-// When condition becomes true
-reactiveUtils.when(
-  () => layer.loaded,
-  () => console.log("Layer loaded")
-);
-```
-
-## Common Pitfalls
-
-1. **Missing CSS for Core API**: The Core API requires `main.css`:
-   ```html
-   <link rel="stylesheet" href="https://js.arcgis.com/4.34/esri/themes/light/main.css" />
-   ```
-
-2. **Not awaiting viewOnReady()**: Always wait for the view before accessing properties:
-   ```javascript
-   await mapElement.viewOnReady();
-   const view = mapElement.view; // Safe to access now
-   ```
-
-3. **Coordinate order**: ArcGIS uses `[longitude, latitude]`, not `[latitude, longitude]`
-
-4. **Missing viewDiv height**: Ensure the container has height:
-   ```css
-   html, body, #viewDiv { height: 100%; margin: 0; }
-   ```
-
-5. **Script type**: Use `type="module"` for async/await support:
-   ```html
-   <script type="module">
-     // async/await works here
-   </script>
-   ```
-
+---
+name: arcgis-core-maps
+description: Create 2D and 3D maps using ArcGIS Maps SDK for JavaScript. Use for initializing maps, scenes, views, and navigation. Supports both Map Components (web components) and Core API approaches.
+---
+
+# ArcGIS Core Maps
+
+Use this skill when creating 2D maps (MapView) or 3D scenes (SceneView) with the ArcGIS Maps SDK for JavaScript.
+
+## Import Patterns
+
+### Direct ESM Imports (Recommended for Build Tools)
+Use with Vite, webpack, Rollup, or other build tools:
+```javascript
+import Map from "@arcgis/core/Map.js";
+import MapView from "@arcgis/core/views/MapView.js";
+import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";
+```
+- Tree-shakeable
+- Standard JavaScript modules
+- Best for production applications
+
+### Dynamic Imports (CDN / No Build Tools)
+Use with CDN script tags when no build step is available:
+```javascript
+const Map = await $arcgis.import("@arcgis/core/Map.js");
+const MapView = await $arcgis.import("@arcgis/core/views/MapView.js");
+
+// Multiple imports
+const [FeatureLayer, Graphic] = await $arcgis.import([
+  "@arcgis/core/layers/FeatureLayer.js",
+  "@arcgis/core/Graphic.js"
+]);
+```
+- Works with Map Components (web components)
+- No build step required
+- Good for quick prototypes and demos
+- Requires `<script src="https://js.arcgis.com/4.34/"></script>` in HTML
+
+> **Note:** The examples in this skill use Direct ESM imports. For CDN usage, replace `import X from "path"` with `const X = await $arcgis.import("path")`.
+
+## Autocasting vs Explicit Classes (TypeScript)
+
+The ArcGIS SDK supports [autocasting](https://developers.arcgis.com/javascript/latest/autocasting/) - passing plain objects instead of class instances. Understanding when to use each approach is important for TypeScript projects.
+
+### When to Use Explicit Classes (Non-Autocast)
+
+Use `new SimpleRenderer()`, `new Point()`, etc. when:
+
+- **You need instance methods or `instanceof` checks**
+- **Building shared internal libraries** - constructor APIs surface breaking changes at compile time
+- **You want strong editor discoverability** - `new SimpleRenderer({ ... })` exposes properties clearly
+- **You mutate objects incrementally** - long-lived instances are clearer as real classes
+
+```typescript
+import SimpleRenderer from "@arcgis/core/renderers/SimpleRenderer.js";
+import SimpleMarkerSymbol from "@arcgis/core/symbols/SimpleMarkerSymbol.js";
+
+const renderer = new SimpleRenderer({
+  symbol: new SimpleMarkerSymbol({
+    color: [226, 119, 40],
+    size: 8
+  })
+});
+```
+
+### When to Use Autocasting
+
+Use plain objects with `type` property when:
+
+- **Configuration-heavy code** - renderers, symbols, popups are usually data, not behavior
+- **UI-driven configuration** - React state → plain objects → SDK properties is simpler
+- **Serialization and reuse matter** - configs can be stored, diffed, tested, reused
+- **Property updates after creation** - `layer.renderer = { ... }` works cleanly in React `useEffect`
+
+```typescript
+// Use 'as const' or 'satisfies' to keep discriminated unions narrow
+const renderer = {
+  type: "simple",
+  symbol: {
+    type: "simple-marker",
+    color: [226, 119, 40],
+    size: 8
+  }
+} as const;
+
+// Or with satisfies for better type inference
+import type { SimpleRenderer } from "@arcgis/core/renderers/SimpleRenderer.js";
+
+const renderer = {
+  type: "simple",
+  symbol: {
+    type: "simple-marker",
+    color: [226, 119, 40],
+    size: 8
+  }
+} satisfies __esri.SimpleRendererProperties;
+```
+
+### TypeScript Best Practices
+
+The real TypeScript concern is keeping discriminated unions narrow:
+
+```typescript
+// ❌ BAD - type widens to string
+const symbol = { type: "simple-marker", color: "red" };
+
+// ✅ GOOD - type stays literal
+const symbol = { type: "simple-marker", color: "red" } as const;
+
+// ✅ GOOD - explicit type annotation
+const symbol: __esri.SimpleMarkerSymbolProperties = {
+  type: "simple-marker",
+  color: "red"
+};
+```
+
+### Recommended Default
+
+- **Autocast for configuration** (renderers, symbols, popups, labels)
+- **Explicit classes for behavior** (when you need methods or instanceof)
+- **Use `as const` or `satisfies`** to maintain type safety with autocasting
+
+## Two Approaches
+
+### 1. Map Components (Modern - Recommended)
+Web components approach using `<arcgis-map>` and `<arcgis-scene>`.
+
+### 2. Core API
+Traditional JavaScript approach using `Map`, `MapView`, and `SceneView` classes.
+
+## CDN Setup
+
+### Map Components Approach
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>ArcGIS Map</title>
+  <style>
+    html, body { height: 100%; margin: 0; }
+  </style>
+  <!-- Load Calcite components -->
+  <script type="module" src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"></script>
+  <!-- Load ArcGIS Maps SDK -->
+  <script src="https://js.arcgis.com/4.34/"></script>
+  <!-- Load Map components -->
+  <script type="module" src="https://js.arcgis.com/4.34/map-components/"></script>
+</head>
+<body>
+  <arcgis-map basemap="topo-vector" center="-118.24,34.05" zoom="12">
+    <arcgis-zoom slot="top-left"></arcgis-zoom>
+  </arcgis-map>
+</body>
+</html>
+```
+
+### Core API Approach
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>ArcGIS Map</title>
+  <style>
+    html, body, #viewDiv { height: 100%; margin: 0; }
+  </style>
+  <!-- REQUIRED: main.css for Core API -->
+  <link rel="stylesheet" href="https://js.arcgis.com/4.34/esri/themes/light/main.css" />
+  <script src="https://js.arcgis.com/4.34/"></script>
+</head>
+<body>
+  <div id="viewDiv"></div>
+  <script type="module">
+    import Map from "@arcgis/core/Map.js";
+    import MapView from "@arcgis/core/views/MapView.js";
+
+    const map = new Map({ basemap: "topo-vector" });
+    const view = new MapView({
+      container: "viewDiv",
+      map: map,
+      center: [-118.24, 34.05], // [longitude, latitude]
+      zoom: 12
+    });
+  </script>
+</body>
+</html>
+```
+
+## 2D Maps
+
+### Map Components
+```html
+<arcgis-map basemap="topo-vector" center="-118.24,34.05" zoom="12">
+  <arcgis-zoom slot="top-left"></arcgis-zoom>
+  <arcgis-compass slot="top-left"></arcgis-compass>
+  <arcgis-home slot="top-left"></arcgis-home>
+  <arcgis-locate slot="top-left"></arcgis-locate>
+</arcgis-map>
+
+<script type="module">
+  const mapElement = document.querySelector("arcgis-map");
+  await mapElement.viewOnReady(); // Wait for view to be ready
+  const view = mapElement.view;   // Access the MapView
+  const map = mapElement.map;     // Access the Map
+</script>
+```
+
+### Core API
+```javascript
+import Map from "@arcgis/core/Map.js";
+import MapView from "@arcgis/core/views/MapView.js";
+
+const map = new Map({ basemap: "streets-vector" });
+
+const view = new MapView({
+  container: "viewDiv",
+  map: map,
+  center: [-118.24, 34.05],
+  zoom: 12,
+  // Optional constraints
+  constraints: {
+    minZoom: 5,
+    maxZoom: 18,
+    rotationEnabled: false
+  }
+});
+```
+
+## 3D Scenes
+
+### Map Components
+```html
+<arcgis-scene basemap="topo-3d" ground="world-elevation">
+  <arcgis-zoom slot="top-left"></arcgis-zoom>
+  <arcgis-navigation-toggle slot="top-left"></arcgis-navigation-toggle>
+</arcgis-scene>
+
+<script type="module">
+  const sceneElement = document.querySelector("arcgis-scene");
+  await sceneElement.viewOnReady();
+  const view = sceneElement.view; // SceneView
+</script>
+```
+
+### Core API
+```javascript
+import Map from "@arcgis/core/Map.js";
+import SceneView from "@arcgis/core/views/SceneView.js";
+
+const map = new Map({
+  basemap: "topo-3d",
+  ground: "world-elevation"
+});
+
+const view = new SceneView({
+  container: "viewDiv",
+  map: map,
+  camera: {
+    position: {
+      longitude: -118.24,
+      latitude: 34.05,
+      z: 25000 // altitude in meters
+    },
+    heading: 0,   // compass direction
+    tilt: 45      // 0 = straight down, 90 = horizon
+  }
+});
+```
+
+## Loading WebMaps and WebScenes
+
+### WebMap (2D)
+```html
+<!-- Map Components -->
+<arcgis-map item-id="f2e9b762544945f390ca4ac3671cfa72">
+  <arcgis-zoom slot="top-left"></arcgis-zoom>
+</arcgis-map>
+```
+
+```javascript
+// Core API
+import MapView from "@arcgis/core/views/MapView.js";
+import WebMap from "@arcgis/core/WebMap.js";
+
+const webmap = new WebMap({
+  portalItem: { id: "f2e9b762544945f390ca4ac3671cfa72" }
+});
+
+const view = new MapView({
+  map: webmap,
+  container: "viewDiv"
+});
+```
+
+### WebScene (3D)
+```html
+<!-- Map Components -->
+<arcgis-scene item-id="YOUR_WEBSCENE_ID">
+  <arcgis-zoom slot="top-left"></arcgis-zoom>
+</arcgis-scene>
+```
+
+```javascript
+// Core API
+import SceneView from "@arcgis/core/views/SceneView.js";
+import WebScene from "@arcgis/core/WebScene.js";
+
+const webscene = new WebScene({
+  portalItem: { id: "YOUR_WEBSCENE_ID" }
+});
+
+const view = new SceneView({
+  map: webscene,
+  container: "viewDiv"
+});
+```
+
+## Navigation Components
+
+| Component | Purpose |
+|-----------|---------|
+| `arcgis-zoom` | Zoom in/out buttons |
+| `arcgis-compass` | Orientation indicator, click to reset north |
+| `arcgis-home` | Return to initial extent |
+| `arcgis-locate` | Find user's location |
+| `arcgis-navigation-toggle` | Switch between pan/rotate modes (3D) |
+| `arcgis-fullscreen` | Toggle fullscreen mode |
+| `arcgis-scale-bar` | Display map scale |
+
+### Slot Positions
+```html
+<arcgis-map basemap="streets-vector">
+  <arcgis-zoom slot="top-left"></arcgis-zoom>
+  <arcgis-home slot="top-left"></arcgis-home>
+  <arcgis-search slot="top-right"></arcgis-search>
+  <arcgis-legend slot="bottom-left"></arcgis-legend>
+  <arcgis-scale-bar slot="bottom-right"></arcgis-scale-bar>
+</arcgis-map>
+```
+
+Available slots: `top-left`, `top-right`, `bottom-left`, `bottom-right`, `manual`
+
+## View Configuration
+
+### Setting Initial Extent
+```javascript
+// By center and zoom
+const view = new MapView({
+  container: "viewDiv",
+  map: map,
+  center: [-118.24, 34.05],
+  zoom: 12
+});
+
+// By scale
+const view = new MapView({
+  container: "viewDiv",
+  map: map,
+  center: [-118.24, 34.05],
+  scale: 50000 // 1:50,000
+});
+
+// By extent
+const view = new MapView({
+  container: "viewDiv",
+  map: map,
+  extent: {
+    xmin: -118.5,
+    ymin: 33.8,
+    xmax: -117.9,
+    ymax: 34.3,
+    spatialReference: { wkid: 4326 }
+  }
+});
+```
+
+### Programmatic Navigation
+```javascript
+// Go to location
+await view.goTo({
+  center: [-118.24, 34.05],
+  zoom: 15
+});
+
+// Animated navigation
+await view.goTo(
+  { center: [-118.24, 34.05], zoom: 15 },
+  { duration: 2000, easing: "ease-in-out" }
+);
+
+// Go to extent
+await view.goTo(layer.fullExtent);
+
+// Go to features
+await view.goTo(featureSet.features);
+```
+
+### View Constraints
+```javascript
+// Constrain zoom levels
+view.constraints = {
+  minZoom: 5,
+  maxZoom: 18
+};
+
+// Constrain to area
+view.constraints = {
+  geometry: layer.fullExtent,
+  minScale: 500000
+};
+
+// Disable rotation
+view.constraints = {
+  rotationEnabled: false
+};
+```
+
+## Event Handling
+
+```javascript
+// View ready
+view.when(() => {
+  console.log("View is ready");
+});
+
+// Click event
+view.on("click", (event) => {
+  console.log("Clicked at:", event.mapPoint);
+});
+
+// Pointer move
+view.on("pointer-move", (event) => {
+  const point = view.toMap(event);
+  console.log("Mouse at:", point.longitude, point.latitude);
+});
+
+// Extent change
+view.watch("extent", (extent) => {
+  console.log("Extent changed:", extent);
+});
+
+// Stationary (after pan/zoom completes)
+view.watch("stationary", (isStationary) => {
+  if (isStationary) {
+    console.log("Navigation complete");
+  }
+});
+```
+
+## Module Imports
+
+```javascript
+// Single import
+import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";
+
+// Multiple imports
+import Map from "@arcgis/core/Map.js";
+import MapView from "@arcgis/core/views/MapView.js";
+import Graphic from "@arcgis/core/Graphic.js";
+```
+
+## Common Basemaps
+
+| Basemap ID | Description |
+|------------|-------------|
+| `streets-vector` | Street map |
+| `topo-vector` | Topographic |
+| `satellite` | Satellite imagery |
+| `hybrid` | Satellite with labels |
+| `dark-gray-vector` | Dark gray canvas |
+| `gray-vector` | Light gray canvas |
+| `osm` | OpenStreetMap |
+| `topo-3d` | 3D topographic (SceneView) |
+
+## esriRequest (HTTP Requests)
+
+### Basic Request
+```javascript
+import esriRequest from "@arcgis/core/request.js";
+
+// GET request with JSON response
+const response = await esriRequest(url, {
+  query: { f: "json" },
+  responseType: "json"
+});
+
+console.log("Status:", response.httpStatus);
+console.log("Data:", response.data);
+```
+
+### Request with Options
+```javascript
+const response = await esriRequest(url, {
+  query: {
+    f: "json",
+    param1: "value1"
+  },
+  responseType: "json",  // "json", "text", "array-buffer", "blob", "image"
+  method: "post",        // "auto", "get", "post"
+  body: formData,        // For POST requests
+  timeout: 30000,        // Timeout in ms
+  headers: {
+    "X-Custom-Header": "value"
+  }
+});
+```
+
+### Download Binary Data
+```javascript
+// Image response
+const imageResponse = await esriRequest(imageUrl, {
+  responseType: "image"
+});
+const imageElement = imageResponse.data;
+
+// Binary data
+const binaryResponse = await esriRequest(fileUrl, {
+  responseType: "array-buffer"
+});
+const arrayBuffer = binaryResponse.data;
+```
+
+## Planetary Visualization (Mars)
+
+### Mars Scene
+```html
+<arcgis-scene>
+  <arcgis-zoom slot="top-left"></arcgis-zoom>
+  <arcgis-navigation-toggle slot="top-left"></arcgis-navigation-toggle>
+</arcgis-scene>
+
+<script type="module">
+  import ElevationLayer from "@arcgis/core/layers/ElevationLayer.js";
+  import TileLayer from "@arcgis/core/layers/TileLayer.js";
+  import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";
+
+  const viewElement = document.querySelector("arcgis-scene");
+
+  // Set Mars spatial reference
+  viewElement.spatialReference = { wkid: 104971 }; // Mars 2000
+
+  // Configure camera for Mars
+  viewElement.camera = {
+    position: {
+      x: 27.63423,
+      y: -6.34466,
+      z: 1281525,
+      spatialReference: { wkid: 104971 }
+    },
+    heading: 332,
+    tilt: 37
+  };
+
+  await viewElement.viewOnReady();
+
+  // Mars elevation
+  const marsElevation = new ElevationLayer({
+    url: "https://astro.arcgis.com/arcgis/rest/services/OnMars/MDEM200M/ImageServer"
+  });
+  viewElement.ground = { layers: [marsElevation] };
+
+  // Mars imagery
+  const marsImagery = new TileLayer({
+    url: "https://astro.arcgis.com/arcgis/rest/services/OnMars/MDIM/MapServer",
+    title: "Mars Imagery"
+  });
+  viewElement.map.add(marsImagery);
+</script>
+```
+
+## Overview Map (Synchronized Views)
+
+### Overview Map with Scene
+```html
+<arcgis-scene basemap="hybrid" ground="world-elevation">
+  <arcgis-zoom slot="top-left"></arcgis-zoom>
+  <!-- Embed overview map inside scene -->
+  <arcgis-map basemap="topo-vector" id="overviewDiv" slot="top-right"></arcgis-map>
+</arcgis-scene>
+
+<style>
+  #overviewDiv { width: 300px; height: 200px; border: 1px solid black; }
+</style>
+
+<script type="module">
+  import Graphic from "@arcgis/core/Graphic.js";
+  import reactiveUtils from "@arcgis/core/core/reactiveUtils.js";
+
+  const sceneElement = document.querySelector("arcgis-scene");
+  const overviewElement = document.querySelector("arcgis-map");
+
+  await sceneElement.viewOnReady();
+  await overviewElement.viewOnReady();
+
+  // Disable rotation on overview
+  overviewElement.constraints.rotationEnabled = false;
+  overviewElement.view.ui.components = [];
+
+  // Add visible area graphic
+  const visibleAreaGraphic = new Graphic({
+    symbol: {
+      type: "simple-fill",
+      color: [0, 0, 0, 0.5],
+      outline: null
+    }
+  });
+  overviewElement.graphics.add(visibleAreaGraphic);
+
+  // Sync overview with main scene
+  reactiveUtils.watch(
+    () => sceneElement.visibleArea,
+    async (visibleArea) => {
+      visibleAreaGraphic.geometry = visibleArea;
+      await overviewElement.goTo(visibleArea);
+    },
+    { initial: true }
+  );
+</script>
+```
+
+## promiseUtils (Async Utilities)
+
+### Debounce
+```javascript
+import promiseUtils from "@arcgis/core/core/promiseUtils.js";
+
+// Create debounced function
+const debouncedUpdate = promiseUtils.debounce(async () => {
+  // This only runs after 300ms of no calls
+  await updateFeatures();
+});
+
+view.on("pointer-move", () => {
+  debouncedUpdate();
+});
+```
+
+### Abort Error Handling
+```javascript
+import promiseUtils from "@arcgis/core/core/promiseUtils.js";
+
+const abortController = new AbortController();
+
+try {
+  await someAsyncOperation({ signal: abortController.signal });
+} catch (error) {
+  if (promiseUtils.isAbortError(error)) {
+    // Operation was intentionally cancelled
+    console.log("Operation cancelled");
+  } else {
+    // Real error
+    throw error;
+  }
+}
+
+// Cancel the operation
+abortController.abort();
+```
+
+### Create Resolver
+```javascript
+import promiseUtils from "@arcgis/core/core/promiseUtils.js";
+
+// Create a promise that can be resolved/rejected externally
+const { promise, resolve, reject } = promiseUtils.createResolver();
+
+// Later, resolve or reject
+resolve(result);
+// or
+reject(error);
+
+// Use the promise
+const result = await promise;
+```
+
+## reactiveUtils (Property Watching)
+
+### Watch Properties
+```javascript
+import reactiveUtils from "@arcgis/core/core/reactiveUtils.js";
+
+// Watch single property
+reactiveUtils.watch(
+  () => view.scale,
+  (scale) => console.log("Scale:", scale)
+);
+
+// Watch with initial value
+reactiveUtils.watch(
+  () => view.extent,
+  (extent) => console.log("Extent:", extent),
+  { initial: true }
+);
+
+// Watch once
+reactiveUtils.once(
+  () => view.stationary === true
+).then(() => {
+  console.log("View became stationary");
+});
+
+// When condition becomes true
+reactiveUtils.when(
+  () => layer.loaded,
+  () => console.log("Layer loaded")
+);
+```
+
+## Common Pitfalls
+
+1. **Missing CSS for Core API**: The Core API requires `main.css`:
+   ```html
+   <link rel="stylesheet" href="https://js.arcgis.com/4.34/esri/themes/light/main.css" />
+   ```
+
+2. **Not awaiting viewOnReady()**: Always wait for the view before accessing properties:
+   ```javascript
+   await mapElement.viewOnReady();
+   const view = mapElement.view; // Safe to access now
+   ```
+
+3. **Coordinate order**: ArcGIS uses `[longitude, latitude]`, not `[latitude, longitude]`
+
+4. **Missing viewDiv height**: Ensure the container has height:
+   ```css
+   html, body, #viewDiv { height: 100%; margin: 0; }
+   ```
+
+5. **Script type**: Use `type="module"` for async/await support:
+   ```html
+   <script type="module">
+     // async/await works here
+   </script>
+   ```
+