@saschabrunnerch/arcgis-maps-sdk-js-ai-context 0.2.0 → 0.4.0

package/contexts/4.34/skills/arcgis-authentication/AGENTS.md

@@ -0,0 +1,109 @@
+# Agent Guide: arcgis-authentication
+
+Quick-reference decisions, checklists, and tables for authentication and authorization.
+
+## API Key vs OAuth vs Identity Manager Decision Tree
+
+1. **Does the app access only public basemaps, geocoding, or routing?**
+   - Yes --> **API Key** (simplest)
+
+2. **Does the app need to access the user's private content (web maps, feature services)?**
+   - Yes --> **OAuth 2.0** (user signs in)
+
+3. **Is this a server-side app with no user interaction?**
+   - Yes --> **App token** (client credentials OAuth flow, server-side only)
+
+4. **Is the app connecting to ArcGIS Enterprise (on-premise)?**
+   - Yes --> **OAuth 2.0** with custom `portalUrl`
+
+5. **Do you need to access multiple secured services and want automatic token management?**
+   - Yes --> **IdentityManager** handles this automatically with OAuth or registered tokens
+
+| Approach | User Sign-In | Setup Complexity | Use Case |
+|----------|-------------|-----------------|----------|
+| API Key | No | Low | Public apps with basemaps/services |
+| OAuth 2.0 (redirect) | Yes | Medium | Web apps needing user content |
+| OAuth 2.0 (popup) | Yes | Medium | SPAs that stay on page |
+| `<arcgis-oauth>` component | Yes | Low | Quick OAuth with Map Components |
+| Registered token | No | Low | Testing / known tokens |
+
+## OAuth Setup Checklist
+
+### Register your app
+- [ ] Go to [developers.arcgis.com](https://developers.arcgis.com) (or your Enterprise portal)
+- [ ] Create a new OAuth application
+- [ ] Note the **App ID** (client ID)
+- [ ] Add **redirect URIs** for your app (e.g., `http://localhost:5173`, `https://yourapp.com`)
+- [ ] For production: add **referrer restrictions** on the app registration
+
+### Implement in code
+- [ ] Import `OAuthInfo` and `esriId` (IdentityManager)
+- [ ] Create `OAuthInfo`: `new OAuthInfo({ appId: "YOUR_APP_ID" })`
+- [ ] Set `popup: false` for redirect flow, `popup: true` for popup window
+- [ ] Register: `esriId.registerOAuthInfos([oauthInfo])`
+- [ ] Check existing sign-in: `esriId.checkSignInStatus(portalUrl + "/sharing")`
+- [ ] Trigger sign-in: `esriId.getCredential(portalUrl + "/sharing")`
+- [ ] Load portal: `new Portal({ authMode: "immediate" })` then `await portal.load()`
+
+### For Enterprise Portal
+- [ ] Set `portalUrl` on OAuthInfo: `new OAuthInfo({ appId, portalUrl: "https://your-portal/portal" })`
+- [ ] Or set globally: `esriConfig.portalUrl = "https://your-portal/portal"`
+
+### Using the OAuth Component
+- [ ] Add `<arcgis-oauth app-id="YOUR_APP_ID">` to HTML
+- [ ] Listen for `arcgisSignIn` and `arcgisSignOut` events
+- [ ] Access credential from `event.detail.credential`
+
+## Security Checklist
+
+### Token handling
+- [ ] Never commit API keys or tokens to source control
+- [ ] Use environment variables (e.g., `VITE_ARCGIS_API_KEY`) for API keys
+- [ ] For OAuth: tokens are managed by IdentityManager (no manual storage needed)
+- [ ] Do not store tokens in `localStorage` for production apps
+
+### CORS and referrers
+- [ ] Configure `esriConfig.request.trustedServers` for servers that should receive credentials
+- [ ] Set up proxy (`esriConfig.request.proxyUrl`) for services that do not support CORS
+- [ ] Configure **allowed referrers** on your API key at developers.arcgis.com
+- [ ] For Enterprise: ensure CORS is enabled on the portal and services
+
+### OAuth security
+- [ ] Use HTTPS in production (OAuth redirects require it)
+- [ ] Register only the redirect URIs you actually use
+- [ ] Use `popup: false` (redirect flow) when popup blockers are a concern
+- [ ] Handle token expiration: IdentityManager auto-refreshes, but test edge cases
+
+### API Key scoping
+- [ ] Generate API keys with minimum required privileges (only basemaps, only geocoding, etc.)
+- [ ] Set referrer restrictions to limit where the key can be used
+- [ ] Use separate keys for development and production
+- [ ] Rotate keys periodically
+
+## Sign-In / Sign-Out Flow Summary
+
+```
+App loads
+  --> checkSignInStatus()
+    --> Signed in? Load Portal, display user info
+    --> Not signed in? Show sign-in button
+      --> User clicks sign-in
+        --> getCredential() triggers OAuth redirect/popup
+          --> User authenticates at ArcGIS
+            --> Redirect back with token
+              --> Load Portal, display user info
+
+Sign out:
+  --> esriId.destroyCredentials()
+  --> window.location.reload()
+```
+
+## Common Token Errors
+
+| Error | Likely Cause | Fix |
+|-------|-------------|-----|
+| `identity-manager:not-authorized` | Missing or expired token | Trigger re-authentication |
+| `403 Forbidden` | API key lacks required privilege | Add privilege at developers.arcgis.com |
+| `498 Invalid Token` | Token expired or revoked | Refresh or re-authenticate |
+| `499 Token Required` | Secured service, no token provided | Register OAuthInfo or set API key |
+| CORS error on token request | Portal not configured for CORS | Add to `trustedServers` or use proxy |

package/contexts/4.34/skills/arcgis-authentication/SKILL.md

@@ -292,11 +292,48 @@ esriConfig.request.proxyRules.push({
 
 1. **App ID registration**: App ID must be registered with correct redirect URIs
 
-2. **Popup blockers**: OAuth popups may be blocked - use redirect flow as fallback
+2. **Popup blockers**: OAuth popup-based sign-in fails on mobile browsers.
+
+   ```javascript
+   // Anti-pattern: using popup flow on mobile
+   OAuthInfo.create({
+     appId: "YOUR_APP_ID",
+     popup: true // Blocked by most mobile browsers
+   });
+   ```
+
+   ```javascript
+   // Correct: use redirect flow for mobile, popup for desktop
+   const isMobile = /iPhone|iPad|Android/i.test(navigator.userAgent);
+   OAuthInfo.create({
+     appId: "YOUR_APP_ID",
+     popup: !isMobile // Redirect flow on mobile, popup on desktop
+   });
+   ```
+
+   **Impact:** On mobile browsers (Safari, Chrome for iOS/Android), the OAuth popup is silently blocked. The user sees no sign-in dialog and cannot authenticate, with no error message explaining why.
 
 3. **Token expiration**: Tokens expire - handle refresh or re-authentication
 
 4. **CORS errors**: Configure trusted servers or use proxy for cross-origin
 
-5. **Portal URL mismatch**: Ensure portal URL matches exactly (trailing slashes matter)
+5. **Portal URL trailing slash**: A trailing slash in the portal URL causes token validation to fail.
+
+   ```javascript
+   // Anti-pattern: portal URL with trailing slash
+   const portal = new Portal({
+     url: "https://myorg.maps.arcgis.com/" // Trailing slash
+   });
+   await portal.load(); // Token validation may fail
+   ```
+
+   ```javascript
+   // Correct: portal URL without trailing slash
+   const portal = new Portal({
+     url: "https://myorg.maps.arcgis.com" // No trailing slash
+   });
+   await portal.load();
+   ```
+
+   **Impact:** The portal URL with a trailing slash does not match the token's server URL during validation. Authentication silently fails, or the user is prompted to sign in repeatedly because the token is never accepted.
 

package/contexts/4.34/skills/arcgis-core-maps/AGENTS.md

@@ -0,0 +1,86 @@
+# Agent Guide: arcgis-core-maps
+
+Quick-reference decisions, checklists, and tables for creating 2D/3D maps.
+
+## Map Components vs Core API Decision Tree
+
+1. **Are you starting a new project?**
+   - Yes --> Use Map Components (`<arcgis-map>` / `<arcgis-scene>`)
+   - No, maintaining existing Core API code --> Stay with Core API
+
+2. **Do you need programmatic control over view construction timing?**
+   - Yes (e.g., dynamic container, conditional rendering) --> Core API (`new MapView()`)
+   - No --> Map Components
+
+3. **Are you using a framework?**
+   - React 19 / Angular / Vue --> Map Components work as custom elements
+   - Older React (<19) --> Core API (custom element event handling is limited)
+
+4. **Do you need to embed the map inside a Calcite shell layout?**
+   - Yes --> Map Components with `reference-element` attribute for external widgets
+   - No --> Either approach works
+
+**Default:** Map Components unless you have a specific reason for Core API.
+
+## Setup Checklist
+
+### Map Components (npm)
+- [ ] `npm install @arcgis/map-components @esri/calcite-components`
+- [ ] Import components: `import "@arcgis/map-components/dist/components/arcgis-map"`
+- [ ] Set Calcite asset path: `setAssetPath("https://js.arcgis.com/calcite-components/3.3.3/assets")`
+- [ ] Set API key: `esriConfig.apiKey = "YOUR_KEY"`
+- [ ] Ensure `html, body { height: 100%; margin: 0; }` in CSS
+- [ ] Set `"moduleResolution": "bundler"` in tsconfig.json
+- [ ] Use `arcgisViewReadyChange` event before accessing `view`
+
+### Core API (npm)
+- [ ] `npm install @arcgis/core`
+- [ ] Import CSS: `@import "@arcgis/core/assets/esri/themes/light/main.css"`
+- [ ] Create container div with full height: `#viewDiv { height: 100%; }`
+- [ ] Import classes: `import Map from "@arcgis/core/Map.js"`
+- [ ] Set API key: `esriConfig.apiKey = "YOUR_KEY"`
+- [ ] Await `view.when()` before accessing view properties
+
+### Map Components (CDN)
+- [ ] Add Calcite script: `<script type="module" src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"></script>`
+- [ ] Add SDK script: `<script src="https://js.arcgis.com/4.34/"></script>`
+- [ ] Add components script: `<script type="module" src="https://js.arcgis.com/4.34/map-components/"></script>`
+- [ ] Use `<arcgis-map>` or `<arcgis-scene>` in HTML
+- [ ] Use `$arcgis.import()` for dynamic imports inside `<script type="module">`
+
+### Core API (CDN)
+- [ ] Add CSS: `<link rel="stylesheet" href="https://js.arcgis.com/4.34/esri/themes/light/main.css" />`
+- [ ] Add SDK script: `<script src="https://js.arcgis.com/4.34/"></script>`
+- [ ] Create `#viewDiv` with full height
+- [ ] Use `<script type="module">` for async/await support
+
+## CDN vs npm Comparison
+
+| Aspect | CDN | npm + Build Tool |
+|--------|-----|-----------------|
+| Setup speed | Fastest (3 script tags) | Requires project scaffolding |
+| Tree-shaking | No (loads full SDK) | Yes (smaller bundles) |
+| TypeScript | No type checking | Full type support |
+| Offline dev | No | Yes |
+| Production use | Prototypes and demos | Recommended |
+| Import style | `$arcgis.import()` | `import X from "@arcgis/core/..."` |
+| CSS handling | Manual link tag (Core API) | `@import` in CSS (Core API), automatic (Components) |
+| Versioning | URL-pinned (`/4.34/`) | `package.json` pinned |
+
+## Quick Reference: Coordinate Order
+
+ArcGIS uses **[longitude, latitude]**, not [latitude, longitude].
+
+```
+center: [-118.24, 34.05]  // Los Angeles: longitude first, latitude second
+```
+
+## Quick Reference: View Containers
+
+| Container | Dimension | Class |
+|-----------|-----------|-------|
+| `<arcgis-map>` | 2D | Web component (MapView internally) |
+| `<arcgis-scene>` | 3D | Web component (SceneView internally) |
+| `<arcgis-video>` | Video | Web component (VideoView internally) |
+| `new MapView()` | 2D | Core API |
+| `new SceneView()` | 3D | Core API |

package/contexts/4.34/skills/arcgis-core-maps/SKILL.md

@@ -733,18 +733,67 @@ reactiveUtils.when(
 
 ## Common Pitfalls
 
-1. **Missing CSS for Core API**: The Core API requires `main.css`:
+1. **Missing CSS for Core API**: The Core API requires `main.css` for widgets and popups to render correctly.
+
+   ```html
+   <!-- Anti-pattern: no CSS import -->
+   <script type="module">
+     import MapView from "@arcgis/core/views/MapView";
+     import Map from "@arcgis/core/Map";
+     const view = new MapView({ container: "viewDiv", map: new Map({ basemap: "topo-vector" }) });
+   </script>
+   ```
+
    ```html
+   <!-- Correct: include the CSS -->
    <link rel="stylesheet" href="https://js.arcgis.com/4.34/esri/themes/light/main.css" />
+   <script type="module">
+     import MapView from "@arcgis/core/views/MapView";
+     import Map from "@arcgis/core/Map";
+     const view = new MapView({ container: "viewDiv", map: new Map({ basemap: "topo-vector" }) });
+   </script>
    ```
 
-2. **Not awaiting viewOnReady()**: Always wait for the view before accessing properties:
+   **Impact:** The map itself renders, but widgets (Zoom, Legend, Search) and popups appear unstyled or completely broken. Layouts collapse and controls become unusable.
+
+2. **Not awaiting viewOnReady()**: View properties are not available until the view is ready.
+
    ```javascript
+   // Anti-pattern: accessing view before it is ready
+   const mapElement = document.querySelector("arcgis-map");
+   const view = mapElement.view; // undefined - view is not ready yet
+   view.goTo({ center: [-118, 34] }); // TypeError: Cannot read properties of undefined
+   ```
+
+   ```javascript
+   // Correct: wait for the view to be ready
+   const mapElement = document.querySelector("arcgis-map");
    await mapElement.viewOnReady();
-   const view = mapElement.view; // Safe to access now
+   const view = mapElement.view; // MapView instance, safe to use
+   view.goTo({ center: [-118, 34] });
+   ```
+
+   **Impact:** `view` is `null` or `undefined` before the component initializes, causing runtime errors on any property access or method call.
+
+3. **Coordinate order**: ArcGIS uses `[longitude, latitude]`, not `[latitude, longitude]`.
+
+   ```javascript
+   // Anti-pattern: lat/lng order (Google Maps convention)
+   const view = new MapView({
+     center: [34.05, -118.24], // lat first, lng second - WRONG
+     zoom: 12
+   });
+   ```
+
+   ```javascript
+   // Correct: lng/lat order (ArcGIS convention)
+   const view = new MapView({
+     center: [-118.24, 34.05], // lng first, lat second
+     zoom: 12
+   });
    ```
 
-3. **Coordinate order**: ArcGIS uses `[longitude, latitude]`, not `[latitude, longitude]`
+   **Impact:** The map centers on the wrong location, often in the middle of the ocean or on a different continent, with no error message to indicate the mistake.
 
 4. **Missing viewDiv height**: Ensure the container has height:
    ```css

package/contexts/4.34/skills/arcgis-editing/AGENTS.md

@@ -0,0 +1,98 @@
+# Agent Guide: arcgis-editing
+
+Quick-reference decisions, checklists, and tables for feature editing and versioning.
+
+## Editor Component vs Core API Decision
+
+1. **Do you need a basic editing UI with default behavior?**
+   - Yes --> `<arcgis-editor slot="top-right">` (Map Component)
+   - No, need custom form layout or logic --> Core API `Editor` widget or `FeatureForm`
+
+2. **Do you need a standalone form (not inside the Editor panel)?**
+   - Yes --> `FeatureForm` widget or `<arcgis-feature-form>` component
+   - No --> Editor handles forms internally
+
+3. **Do you need programmatic edits without any UI?**
+   - Yes --> `featureLayer.applyEdits()` directly
+
+4. **Do you need version management?**
+   - Yes --> `VersionManagementService` + `<arcgis-version-management>` component
+
+| Approach | UI Provided | Geometry Editing | Form Editing | Flexibility |
+|----------|------------|-----------------|--------------|-------------|
+| `<arcgis-editor>` component | Full | Yes | Yes | Low (defaults) |
+| `Editor` widget (Core API) | Full | Yes | Yes | High (layerInfos config) |
+| `FeatureForm` widget | Form only | No | Yes | High (custom form layout) |
+| `applyEdits()` | None | Via code | Via code | Maximum |
+
+## Edit Workflow Steps
+
+### Interactive editing (Editor widget)
+1. **Setup** -- Add Editor to view with `layerInfos` config
+2. **Create** -- User selects template, draws geometry, fills form
+3. **Update** -- User clicks feature, modifies geometry or attributes
+4. **Delete** -- User selects feature and deletes
+
+### Programmatic editing (applyEdits)
+1. **Create Graphic** -- Build `Graphic` with geometry and attributes
+2. **Call applyEdits** -- `layer.applyEdits({ addFeatures: [graphic] })`
+3. **Handle result** -- Check `result.addFeatureResults` for success/errors
+4. **Refresh** -- Layer auto-refreshes; call `layer.refresh()` if needed
+
+### Form-based editing (FeatureForm)
+1. **Create form** -- `new FeatureForm({ layer, formTemplate })`
+2. **Set feature** -- `form.feature = graphic`
+3. **User edits** -- Form fields are populated and editable
+4. **Validate** -- Check `form.valid` before proceeding
+5. **Get values** -- `form.getValues()` returns updated attributes
+6. **Apply** -- `layer.applyEdits({ updateFeatures: [graphic] })`
+
+## Version Management Checklist
+
+### Setup
+- [ ] Have a branch-versioned feature service
+- [ ] Create `VersionManagementService` with the service URL
+- [ ] Await `vms.load()`
+
+### Create and edit in a version
+- [ ] Create version: `vms.createVersion({ versionName, access: "private" })`
+- [ ] Switch layer: `featureLayer.gdbVersion = version.versionName`
+- [ ] Refresh layer: `await featureLayer.refresh()`
+- [ ] Start edit session: `await vms.startEditing({ versionIdentifier })`
+- [ ] Apply edits: `await featureLayer.applyEdits(edits)`
+- [ ] Reconcile: `await vms.reconcile({ versionIdentifier, conflictResolution: "favorEditVersion" })`
+- [ ] Check for conflicts: `reconcileResult.hasConflicts`
+- [ ] Post to parent: `await vms.post({ versionIdentifier })`
+- [ ] Stop editing: `await vms.stopEditing({ versionIdentifier, saveEdits: true })`
+
+### Cleanup
+- [ ] Switch layer back: `featureLayer.gdbVersion = vms.defaultVersionIdentifier`
+- [ ] Delete temp version: `await vms.deleteVersion({ versionName })`
+
+## Form Element Types
+
+| Type | Purpose |
+|------|---------|
+| `field` | Single editable field |
+| `group` | Group of fields under a heading |
+
+### Field Element Expression Types
+
+| Expression Property | Controls |
+|-------------------|----------|
+| `visibilityExpression` | Whether the field is visible |
+| `editableExpression` | Whether the field is editable |
+| `requiredExpression` | Whether the field is required |
+| `valueExpression` | Computed default value |
+
+All expressions use Arcade syntax and must return `true`/`false`.
+
+## applyEdits Operations
+
+| Operation | Property | Value |
+|-----------|----------|-------|
+| Add features | `addFeatures` | Array of Graphics |
+| Update features | `updateFeatures` | Array of Graphics (with existing OID) |
+| Delete features | `deleteFeatures` | Array of Graphics or `[{ objectId: N }]` |
+
+All three can be combined in a single `applyEdits()` call.

package/contexts/4.34/skills/arcgis-editing/SKILL.md

@@ -517,6 +517,42 @@ if (form.valid) {
 
 ## Complete Example
 
+### Map Components (Recommended)
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="module" src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"></script>
+  <script src="https://js.arcgis.com/4.34/"></script>
+  <script type="module" src="https://js.arcgis.com/4.34/map-components/"></script>
+  <style>
+    html, body { height: 100%; margin: 0; }
+  </style>
+</head>
+<body>
+  <arcgis-map basemap="streets-navigation-vector">
+    <arcgis-zoom slot="top-left"></arcgis-zoom>
+    <arcgis-editor slot="top-right"></arcgis-editor>
+  </arcgis-map>
+
+  <script type="module">
+    import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";
+
+    const mapElement = document.querySelector("arcgis-map");
+    await mapElement.viewOnReady();
+
+    const layer = new FeatureLayer({
+      url: "https://services.arcgis.com/.../FeatureServer/0"
+    });
+    mapElement.map.add(layer);
+  </script>
+</body>
+</html>
+```
+
+### Core API
+
 ```html
 <!DOCTYPE html>
 <html>
@@ -525,7 +561,6 @@ if (form.valid) {
   <script src="https://js.arcgis.com/4.34/"></script>
   <style>
     html, body, #viewDiv { height: 100%; margin: 0; }
-    #formPanel { position: absolute; top: 10px; right: 10px; width: 300px; }
   </style>
   <script type="module">
     import Map from "@arcgis/core/Map.js";
@@ -617,11 +652,63 @@ const editor = new Editor({
 
 ## Common Pitfalls
 
-1. **Editing permissions**: User must have edit permissions on the layer
+1. **Editing permissions**: Calling `applyEdits` on a layer without checking edit capabilities causes silent failures.
+
+   ```javascript
+   // Anti-pattern: calling applyEdits without checking capabilities
+   const layer = new FeatureLayer({ url: "https://services.arcgis.com/.../FeatureServer/0" });
+   await layer.applyEdits({
+     addFeatures: [newFeature]
+   });
+   // May fail silently or throw a cryptic server error
+   ```
+
+   ```javascript
+   // Correct: check capabilities before editing
+   const layer = new FeatureLayer({ url: "https://services.arcgis.com/.../FeatureServer/0" });
+   await layer.load();
+   if (layer.editingEnabled && layer.capabilities?.editing?.supportsAddingFeatures) {
+     await layer.applyEdits({
+       addFeatures: [newFeature]
+     });
+   } else {
+     console.error("Layer does not support adding features");
+   }
+   ```
+
+   **Impact:** The `applyEdits` call fails with a cryptic server error or silently returns an error result that is easy to miss, leaving the user believing the edit was saved when it was not.
 
 2. **Subtype field**: Must match the subtype configuration in the service
 
-3. **Version locking**: Branch versions may lock during editing sessions
+3. **Version locking**: Editing branch-versioned data without proper session management causes version locks.
+
+   ```javascript
+   // Anti-pattern: editing without version management session
+   const layer = new FeatureLayer({ url: "https://services.arcgis.com/.../FeatureServer/0" });
+   layer.gdbVersion = "editor1.design_v1";
+   await layer.applyEdits({ updateFeatures: [updatedFeature] });
+   // Version remains locked, blocking other users
+   ```
+
+   ```javascript
+   // Correct: start and stop version management session
+   const versionManagement = new VersionManagementService({
+     url: "https://services.arcgis.com/.../VersionManagementServer"
+   });
+   const versionName = "editor1.design_v1";
+
+   // Start editing session
+   await versionManagement.startEditing(versionName);
+
+   const layer = new FeatureLayer({ url: "https://services.arcgis.com/.../FeatureServer/0" });
+   layer.gdbVersion = versionName;
+   await layer.applyEdits({ updateFeatures: [updatedFeature] });
+
+   // Stop editing session to release the lock
+   await versionManagement.stopEditing(versionName, true); // true = save edits
+   ```
+
+   **Impact:** The version stays locked after editing, preventing other users from accessing or editing it. Accumulated locks require administrator intervention to release.
 
 4. **Validation expressions**: Must return true/false or error object
 

package/contexts/4.34/skills/arcgis-interaction/AGENTS.md

@@ -0,0 +1,108 @@
+# Agent Guide: arcgis-interaction
+
+Quick-reference decisions, checklists, and tables for user interaction patterns.
+
+## Hit Test vs Query vs Popup Decision Matrix
+
+| Need | Approach | Method |
+|------|----------|--------|
+| User clicks a feature and sees info | Popup (built-in) | Set `popupTemplate` on layer, it works automatically |
+| User clicks and you run custom logic | Hit test | `view.hitTest(event)` in a click handler |
+| Find all features in an area | Spatial query | `featureLayer.queryFeatures(query)` |
+| Highlight features by attribute | Attribute query + highlight | `queryObjectIds()` then `layerView.highlight(oids)` |
+| Show a cursor change on hover | Hit test on pointer-move | `view.hitTest(event)` in a pointer-move handler |
+| Draw a shape and select features in it | Sketch + spatial query | Sketch widget for drawing, then query with the geometry |
+
+### When to use each:
+
+- **Popup** -- Simplest. Just configure `popupTemplate` on the layer. No code for the interaction itself.
+- **Hit test** -- Returns the graphic at a screen point. Use when you need the actual feature object for custom behavior (not just a popup).
+- **Server query** -- Returns features matching SQL/spatial criteria from the service. Use for bulk operations or features not visible on screen.
+- **Client query** -- `layerView.queryFeatures()` queries only loaded features. Faster but limited to what is in the view.
+
+## Click-to-Select Implementation Checklist
+
+- [ ] Get a reference to the target `FeatureLayer`
+- [ ] Get the LayerView: `const layerView = await view.whenLayerView(featureLayer)`
+- [ ] Store a highlight handle variable: `let highlightHandle = null`
+- [ ] Add click handler: `view.on("click", async (event) => { ... })`
+- [ ] Inside handler, run hit test: `const response = await view.hitTest(event, { include: [featureLayer] })`
+- [ ] Remove previous highlight: `highlightHandle?.remove()`
+- [ ] If results found, highlight: `highlightHandle = layerView.highlight(graphic)`
+- [ ] Optionally open popup or update side panel with feature attributes
+
+## Cleanup Pattern
+
+Always clean up handles and event listeners to prevent memory leaks.
+
+### Handle-based cleanup (highlight, watch)
+```
+const handle = layerView.highlight(graphic);
+// Later:
+handle.remove();
+```
+
+### Event listener cleanup
+```
+const handle = view.on("click", handler);
+// Later:
+handle.remove();
+```
+
+### reactiveUtils cleanup
+```
+const handle = reactiveUtils.watch(() => view.zoom, callback);
+// Later:
+handle.remove();
+```
+
+### Destroy pattern (widgets)
+```
+widget.destroy();  // Removes from DOM and cleans up
+```
+
+### Checklist for cleanup
+- [ ] Store all `view.on()` return handles
+- [ ] Store all `reactiveUtils.watch()` / `when()` / `once()` return handles
+- [ ] Store all `layerView.highlight()` return handles
+- [ ] Call `.remove()` on handles when the interaction is no longer needed
+- [ ] Call `.destroy()` on widgets when removing them
+- [ ] In frameworks (React/Angular): clean up in unmount/destroy lifecycle hooks
+
+## Event Types Quick Reference
+
+| Event | Fires when | Common use |
+|-------|-----------|------------|
+| `click` | User clicks the map | Feature selection, custom popups |
+| `double-click` | User double-clicks | Override default zoom behavior |
+| `pointer-move` | Mouse moves over map | Hover highlighting, coordinate display |
+| `pointer-down` / `pointer-up` | Mouse button pressed/released | Custom drag interactions |
+| `drag` | User drags the map | Custom pan behavior |
+| `key-down` / `key-up` | Keyboard input while map focused | Keyboard shortcuts |
+| `hold` | Long press | Mobile context menu |
+
+### Preventing Default Behavior
+```
+view.on("double-click", (event) => {
+  event.stopPropagation();  // Prevents default zoom-in
+});
+```
+
+## Coordinate Conversion Quick Reference
+
+| Direction | Method |
+|-----------|--------|
+| Screen (pixels) to Map (geographic) | `view.toMap({ x, y })` |
+| Map (geographic) to Screen (pixels) | `view.toScreen(mapPoint)` |
+| Click event to Map point | `event.mapPoint` (already available) |
+| Pointer event to Map point | `view.toMap(event)` (must convert) |
+
+## Highlight Options
+
+| Property | Default | Purpose |
+|----------|---------|---------|
+| `color` | `[0, 255, 255, 1]` (cyan) | Highlight outline/halo color |
+| `haloOpacity` | `1` | Opacity of the halo around features |
+| `fillOpacity` | `0.25` | Opacity of the fill inside features |
+
+Set on `layerView.highlightOptions` or at the `MapView` / `SceneView` level.