Tech Debt and Fixes

.github/copilot-instructions.md

@@ -0,0 +1,51 @@
+# PLSS Cloud-Agent Guide
+
+## Project at a glance
+
+This is the Utah GIS Public Lands Survey System (PLSS) application: a React map for viewing PLSS monuments and submitting monument records. It is a pnpm workspace with two Node 24 packages:
+
+- The root package is a React 19, Vite 8, Tailwind 4, ArcGIS JavaScript SDK web app. It deploys as Firebase Hosting.
+- `functions/` contains ESM Firebase Functions v2 (HTTP callables plus Auth, Firestore, and Storage triggers). Firebase Hosting and Functions both target Node 24 (`firebase.json`, `package.json`, and `functions/package.json`).
+
+The repository is small application source plus a large generated/installed ArcGIS asset surface. Do not inspect or edit `public/assets/`, `dist/`, coverage output, `node_modules/`, or `.emulator-data/`; they are generated or local data. Trust this guide and search only when it is incomplete or demonstrably wrong.
+
+## Bootstrap and commands
+
+Always use pnpm 11 and Node 24. CI installs Java 21 for Firebase emulators; a Java 21-or-newer runtime is required locally for storage-rules tests. From the repository root, run:
+
+```sh
+pnpm install --frozen-lockfile
+```
+
+This is the CI bootstrap and succeeds with the committed lockfile. `pnpm-workspace.yaml` has strict package-age and approved-build policies; do not use another package manager or rewrite the lockfile unless the task changes dependencies.
+
+Run validation in this order after relevant changes:
+
+```sh
+CI=1 pnpm test:ci
+pnpm lint
+pnpm check
+pnpm build
+```
+
+- `test:ci` starts a temporary Firebase Storage emulator on port 9199 and runs all Vitest suites, including Functions, shared schemas, state machines, UI utilities, and `storage.rules.test.mjs`. It passed locally with 9 files / 323 tests in about 17 seconds after emulator startup. `CI=1` is essential locally because `pnpm test` includes `--ui --open`; without CI it opens the Vitest UI and remains interactive. Firebase may report a nonfatal Java `Unsafe` deprecation warning or use logging port 4501 if 4500 is occupied.
+- `lint` is the PR gate: root ESLint uses `@ugrc/eslint-config` and fails on any warning. The Functions package has a legacy local lint script, but root `pnpm lint` covers repository CI.
+- `build` runs Vite and writes the deployable Firebase Hosting bundle to `dist/`, including copied ArcGIS assets. The production build passed locally. A generated-CSS pseudo-class warning can appear and is currently nonfatal.
+- `pnpm format` modifies files. Run `pnpm exec prettier --write <modified-files>` as appropriate for changed files that Prettier supports. Use `pnpm exec prettier --check <changed-files>` when a formatting-only validation is needed; Prettier organizes imports and Tailwind classes.
+
+For interactive development, first authenticate with Firebase, copy `.env` to `.env.local`, and copy `functions/.secret` to `functions/.secret.local`; populate the existing placeholders with authorized development values. Never commit either local file or secrets. Then run `pnpm start` and use `http://localhost:5173/`. It starts Vite and Auth/Functions/Firestore/Storage emulators; it waits for the Firebase emulator UI at port 4000. It is a long-running command, not a PR validation. `pnpm dev:firebase-state` imports and exports `.emulator-data`; use it only when persistent emulator data is wanted. Deploy commands require repository/cloud credentials and should not be run by a cloud agent.
+
+## Architecture and change locations
+
+- `src/main.jsx` configures Firebase and React Query providers, then renders `src/components/app/App.jsx`. Firebase configuration is parsed from `VITE_FIREBASE_CONFIG`; other browser-visible variables must use the `VITE_` prefix.
+- `src/components/pageElements/` contains map-oriented screens and the corner-submission wizard; `formElements/` contains reusable inputs; `layoutElements/` has navigation/drawer; `machines/` contains XState logic; `reducers/AppReducer.js` owns app-level UI/map state. Add or update nearby `*.test.js` / `*.stories.jsx` using existing patterns.
+- `functions/index.js` is the Functions export and authorization boundary. Keep its lazy imports and v2 trigger/callable conventions; implement endpoint bodies in `functions/https/`, document-trigger code in `functions/database/submissions/`, and reusable validation/formatting in `functions/shared/`. Sensitive integrations use `defineSecret` (`SENDGRID_API_KEY`, `SHARED_DRIVE_ID`), not client environment variables.
+- `functions/firebase.js` intentionally configures localhost and the dev Firebase project for `NODE_ENV=development` or `test`.
+- `firestore.rules`, `storage.rules`, and `firestore.indexes.json` are deployed Firebase configuration. Storage rules have the executable root test above; preserve the 5 MB and authenticated-user constraints unless requirements intentionally change. Firestore submissions/stats require an authenticated, elevated submitter.
+- `vite.config.js` is Vite/Vitest configuration and hardcodes `FIREBASE_STORAGE_EMULATOR_HOST=127.0.0.1:9199` for tests. `firebase.json` controls Functions runtime, Hosting `dist/`, rewrites, security headers, and emulator ports. `eslint.config.js`, `.prettierrc`, and `pnpm-workspace.yaml` are the style and package-policy configuration.
+
+## CI and delivery
+
+`.github/workflows/pull_request.yml` is the required PR pipeline: pnpm 11, Node from `package.json`, frozen install, Java 21, `pnpm test:ci`, then `pnpm lint`. Preview deployment occurs only after those pass and only for eligible non-`dev` PR authors; it builds with `pnpm build --mode dev` and protected Firebase credentials. Do not depend on previews to validate a change.
+
+Pushes to `main` and `dev` use the release automation. Published prereleases deploy to staging and releases deploy to production through protected credentials; both build with `pnpm build`. Repository root also contains `README.md` (local setup and domain context), `firebase.json`, rules/index configuration, `vite.config.js`, `eslint.config.js`, `pnpm-lock.yaml`, `CHANGELOG.md`, and `AI_ATTESTATION.md`.

.github/workflows/pull_request.yml

@@ -25,7 +25,7 @@ jobs:
       - name: 📦 Setup PNPM
         uses: pnpm/action-setup@v4
         with:
-          version: latest
+          version: 11
 
       - name: 💾 Cache firebase emulators
         uses: actions/cache@v5
@@ -36,23 +36,26 @@ jobs:
       - name: ⎔ Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: lts/*
+          node-version-file: package.json
           cache: pnpm
 
       - name: 📥 Download app dependencies
-        run: pnpm install
+        run: pnpm install --frozen-lockfile
 
       - name: ☕ Setup Java
         uses: actions/setup-java@v4
         with:
           distribution: 'temurin'
           java-version: '21'
 
-      - name: 🧪 Run tests
-        run: pnpm run test:ci
-
       - name: 🔍 Lint
-        run: pnpm run lint
+        run: pnpm lint
+
+      - name: ✅ Type Check
+        run: pnpm check
+
+      - name: 🧪 Run tests
+        run: pnpm test:ci
 
   deploy-preview:
     name: Create preview
@@ -63,11 +66,16 @@ jobs:
       name: preview
 
     steps:
+      - name: ⬇️ Set up code
+        uses: actions/checkout@v6
+        with:
+          show-progress: false
+
       - name: 🚀 Deploy
-        uses: agrc/firebase-website-deploy-composite-action@v1
+        uses: agrc/firebase-website-deploy-composite-action@v2
         with:
           preview: yes
-          build-command: pnpm run build --mode dev
+          build-command: pnpm build --mode dev
           project-id: ${{ secrets.PROJECT_ID }}
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           identity-provider: ${{ secrets.IDENTITY_PROVIDER }}

.github/workflows/release.yml

@@ -38,7 +38,7 @@ jobs:
           identity-provider: ${{ secrets.IDENTITY_PROVIDER }}
           service-account-email: ${{ secrets.SERVICE_ACCOUNT_EMAIL }}
           project-id: ${{ secrets.PROJECT_ID }}
-          build-command: pnpm run build
+          build-command: pnpm build
         env:
           VITE_FIREBASE_CONFIG: ${{ secrets.FIREBASE_CONFIG }}
           VITE_DISCOVER_KEY: ${{ secrets.VITE_DISCOVER_KEY }}
@@ -73,7 +73,7 @@ jobs:
           service-now-username: ${{ secrets.SN_USERNAME }}
           service-now-password: ${{ secrets.SN_PASSWORD }}
           repo-token: ${{ secrets.GITHUB_TOKEN }}
-          build-command: pnpm run build
+          build-command: pnpm build
         env:
           VITE_FIREBASE_CONFIG: ${{ secrets.FIREBASE_CONFIG }}
           VITE_DISCOVER_KEY: ${{ secrets.VITE_DISCOVER_KEY }}

.gitignore

@@ -3,6 +3,9 @@ lerna-debug.log*
 
 dist
 dist-ssr
+storybook-static
+functions/lib
+functions/shared/dist
 *.local
 
 # Editor directories and files

.prettierignore

@@ -7,3 +7,4 @@
 /dist
 /public/assets
 CHANGELOG.md
+pnpm-lock.yaml

.storybook/main.js → .storybook/main.ts

@@ -1,5 +1,5 @@
 export default {
-  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
+  stories: ['../src/**/*.stories.@(ts|tsx)'],
   addons: ['@storybook/addon-links', '@storybook/addon-docs'],
   framework: {
     name: '@storybook/react-vite',

CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## [3.6.17-rc.8](https://github.com/agrc/plss/compare/v3.6.16...v3.6.17-rc.8) (2026-09-10)
+
+
+### Features
+
+* add better busy indicator to map ([b573e84](https://github.com/agrc/plss/commit/b573e84d48f1b15f40e33c2de2771a678f797751)), refs [#551](https://github.com/agrc/plss/issues/551)
+
+
+### Bug Fixes
+
+* allow tasks.arcgisonline.com in content security policy ([80f8d79](https://github.com/agrc/plss/commit/80f8d79570750137f74fbe6e15570db639c1646a))
+* better layout for quick finder tools dialog ([9d82808](https://github.com/agrc/plss/commit/9d828087c7302cd5484562379f59d0b22fa1b9c6))
+* default MMRC project toggle to yes ([baaa2d3](https://github.com/agrc/plss/commit/baaa2d3bf6e0189704361c7a777aa0901cd79a9e)), refs [#549](https://github.com/agrc/plss/issues/549)
+* **functions:** better error handling for submissions ([60af4f9](https://github.com/agrc/plss/commit/60af4f905e96476916d265da9576c271002caf37))
+* **functions:** create the monument firestore prop for new sheets ([e6a75cb](https://github.com/agrc/plss/commit/e6a75cba610f4b4b46ef13eb3f49fa4d3b2a51ec)), refs [#563](https://github.com/agrc/plss/issues/563)
+* make menu ribbon more visible and functional on mobile ([f1e91a1](https://github.com/agrc/plss/commit/f1e91a1681c9438214064f39478de872148a497f)), refs [#160](https://github.com/agrc/plss/issues/160)
+* more natural sorting of TRS ranges with decimals ([06b726c](https://github.com/agrc/plss/commit/06b726c36e7533761a9920b888fcff44be549b89)), refs [#203](https://github.com/agrc/plss/issues/203)
+* prevent form from going back to step 1 after a successful submission ([8cb3972](https://github.com/agrc/plss/commit/8cb3972c6e23d8363f768bd93c76edaeb6ff2c9a))
+* remove skip button on "Location Information" screen ([341da26](https://github.com/agrc/plss/commit/341da26956fbac40e1bf78c4204c9a742130718d)), refs [#550](https://github.com/agrc/plss/issues/550)
+* repoint to AGOL geometry service and better error logging ([8a9e2d1](https://github.com/agrc/plss/commit/8a9e2d1001f1c496f30353fc77502333ce5eb6e9))
+* test artifact registry policy ([a13005e](https://github.com/agrc/plss/commit/a13005e286764ffc7690e51f9e2a18c7ce5101a4))
+
+
+### Dependencies
+
+* @arcgis/core v4 -> v5 ([59c2cec](https://github.com/agrc/plss/commit/59c2cec60f35942815079a16509c83e1ce8d9b88))
+* bump NPM dependencies 🌲 ([1ee9c97](https://github.com/agrc/plss/commit/1ee9c97d07a05dd6dd869bab5c8794a966048348))
+* bump utah design system ([68ddcda](https://github.com/agrc/plss/commit/68ddcda0301ae32426f2f368ce99cc21a920e731))
+
+## [3.6.17-rc.6](https://github.com/agrc/plss/compare/v3.6.17-rc.5...v3.6.17-rc.6) (2026-09-09)
+
+
+### Bug Fixes
+
+* **functions:** create the monument firestore prop for new sheets ([facaafb](https://github.com/agrc/plss/commit/facaafbe979c05e524a05835daf9ab3470530002)), refs [#563](https://github.com/agrc/plss/issues/563)
+
+## [3.6.17-rc.5](https://github.com/agrc/plss/compare/v3.6.17-rc.4...v3.6.17-rc.5) (2026-09-04)
+
+
+### Bug Fixes
+
+* prevent form from going back to step 1 after a successful submission ([976360d](https://github.com/agrc/plss/commit/976360d1b2cea66f427e452d8f417706cfe1f7a2))
+
+## [3.6.17-rc.4](https://github.com/agrc/plss/compare/v3.6.17-rc.3...v3.6.17-rc.4) (2026-08-21)
+
+
+### Bug Fixes
+
+* allow tasks.arcgisonline.com in content security policy ([29ade78](https://github.com/agrc/plss/commit/29ade78d13b2bc479367535d69704ee236db7429))
+
+## [3.6.17-rc.3](https://github.com/agrc/plss/compare/v3.6.17-rc.2...v3.6.17-rc.3) (2026-08-20)
+
+
+### Bug Fixes
+
+* test artifact registry policy ([79e14cb](https://github.com/agrc/plss/commit/79e14cb7e8f2e1ac06a2478e6afe622528597674))
+
+## [3.6.17-rc.2](https://github.com/agrc/plss/compare/v3.6.17-rc.1...v3.6.17-rc.2) (2026-08-18)
+
+
+### Features
+
+* add better busy indicator to map ([44f2ff8](https://github.com/agrc/plss/commit/44f2ff822317c09aeb62c4994a92773230528021)), refs [#551](https://github.com/agrc/plss/issues/551)
+
+
+### Bug Fixes
+
+* better layout for quick finder tools dialog ([795a79e](https://github.com/agrc/plss/commit/795a79ea4e426a83939198953e0bbeefa6f4fb56))
+* default MRRC project toggle to yes ([b982ee2](https://github.com/agrc/plss/commit/b982ee2c8fb6f2327f35714a8cb088e7bba49f24)), refs [#549](https://github.com/agrc/plss/issues/549)
+* make menu ribbon more visible and functional on mobile ([553b138](https://github.com/agrc/plss/commit/553b138a73af6a2498277805f8597ac1a4114824)), refs [#160](https://github.com/agrc/plss/issues/160)
+* more natural sorting of TRS ranges with decimals ([ac72af0](https://github.com/agrc/plss/commit/ac72af046a7e3cee59bda5eaf804766e9f27ab5e)), refs [#203](https://github.com/agrc/plss/issues/203)
+* remove skip button on "Location Information" screen ([9f8250e](https://github.com/agrc/plss/commit/9f8250ee96915f704a2882cc81199b04b638d409)), refs [#550](https://github.com/agrc/plss/issues/550)
+
+## [3.6.17-rc.1](https://github.com/agrc/plss/compare/v3.6.16...v3.6.17-rc.1) (2026-08-18)
+
+
+### Bug Fixes
+
+* repoint to AGOL geometry service and better error logging ([8a9e2d1](https://github.com/agrc/plss/commit/8a9e2d1001f1c496f30353fc77502333ce5eb6e9))
+
+
+### Dependencies
+
+* @arcgis/core v4 -> v5 ([59c2cec](https://github.com/agrc/plss/commit/59c2cec60f35942815079a16509c83e1ce8d9b88))
+* bump NPM dependencies 🌲 ([1ee9c97](https://github.com/agrc/plss/commit/1ee9c97d07a05dd6dd869bab5c8794a966048348))
+* bump utah design system ([68ddcda](https://github.com/agrc/plss/commit/68ddcda0301ae32426f2f368ce99cc21a920e731))
+
 ## [3.6.16](https://github.com/agrc/plss/compare/v3.6.15...v3.6.16) (2026-04-08)
 
 

eslint.config.js

@@ -1,6 +1,9 @@
 import { browser } from '@ugrc/eslint-config';
 
 export default [
+  {
+    ignores: ['coverage/**', 'dist/**', 'functions/lib/**', 'functions/shared/dist/**', 'public/assets/**'],
+  },
   ...browser,
   {
     rules: {

firebase.json

@@ -2,8 +2,9 @@
   "functions": [
     {
       "source": "functions",
-      "runtime": "nodejs22",
+      "runtime": "nodejs24",
       "codebase": "default",
+      "predeploy": "pnpm --dir \"$RESOURCE_DIR\" run build",
       "ignore": ["node_modules", ".git", "firebase-debug.log", "firebase-debug.*.log"]
     }
   ],
@@ -56,7 +57,7 @@
         "headers": [
           {
             "key": "Content-Security-Policy",
-            "value": "default-src 'none'; font-src *; worker-src blob:; script-src 'self' 'unsafe-eval' https://*.google.com https://www.googletagmanager.com; connect-src 'self' https://*.cloudfunctions.net https://*.utah.gov https://*.googleapis.com https://*.arcgis.com https://www.google-analytics.com; img-src 'self' blob: data: https://www.gravatar.com https://*.wp.com https://*.utah.gov https://*.arcgis.com https://www.googletagmanager.com https://*.googleapis.com; style-src 'self' 'unsafe-inline';base-uri 'self'; form-action 'self'; frame-src *; object-src 'self' https://*.googleapis.com"
+            "value": "default-src 'none'; font-src *; worker-src blob:; script-src 'self' 'unsafe-eval' https://*.google.com https://www.googletagmanager.com; connect-src 'self' https://*.cloudfunctions.net https://*.utah.gov https://*.googleapis.com https://*.arcgis.com https://www.google-analytics.com https://*.arcgisonline.com; img-src 'self' blob: data: https://www.gravatar.com https://*.wp.com https://*.utah.gov https://*.arcgis.com https://www.googletagmanager.com https://*.googleapis.com; style-src 'self' 'unsafe-inline';base-uri 'self'; form-action 'self'; frame-src *; object-src 'self' https://*.googleapis.com"
           }
         ]
       },

functions/auth/onCreate.js → functions/auth/onCreate.ts

@@ -1,9 +1,10 @@
-import { logger } from 'firebase-functions/v2';
 import { getFirestore } from 'firebase-admin/firestore';
+import { logger } from 'firebase-functions/v2';
+import type { AuthUserRecord } from 'firebase-functions/v2/identity';
 
 const db = getFirestore();
 
-export const createUser = async (user) => {
+export const createUser = async (user: AuthUserRecord): Promise<true> => {
   logger.info('[auth::user::onCreate] creating user', { user });
 
   const data = {

functions/converters.js → functions/converters.ts

@@ -1,12 +1,18 @@
+import { getStatus } from '@ugrc/plss-shared';
 import { contrastColor } from 'contrast-color';
-import { getStatus } from './shared/index.js';
+import type {
+  DocumentData,
+  FirestoreDataConverter,
+  QueryDocumentSnapshot,
+  WithFieldValue,
+} from 'firebase-admin/firestore';
 
-export const graphicConverter = {
-  toFirestore(data) {
-    return data;
-  },
-  fromFirestore(snapshot, options) {
-    const data = snapshot.data(options);
+const passthrough = (data: WithFieldValue<DocumentData>): DocumentData => data;
+
+export const graphicConverter: FirestoreDataConverter<DocumentData> = {
+  toFirestore: passthrough,
+  fromFirestore(snapshot: QueryDocumentSnapshot<DocumentData>) {
+    const data = snapshot.data();
 
     return {
       photos: data.photos,
@@ -47,19 +53,17 @@ const colors = {
   'UGRC rejected submission.': '#f43f5e',
   'Pending PLSS geometry corrections': '#10b981',
   'Sheet and geometry corrections are live': '#f0fdfa',
-};
+} as const;
 
-export const myContentConverter = {
-  toFirestore(data) {
-    return data;
-  },
-  fromFirestore(snapshot, options) {
-    const data = snapshot.data(options);
+export const myContentConverter: FirestoreDataConverter<DocumentData> = {
+  toFirestore: passthrough,
+  fromFirestore(snapshot: QueryDocumentSnapshot<DocumentData>) {
+    const data = snapshot.data();
 
     const status = getStatus(data.status);
 
     if (status.label in colors) {
-      data.color = colors[status.label];
+      data.color = colors[status.label as keyof typeof colors];
     } else {
       for (const [title, color] of Object.entries(colors)) {
         if (status.label === title || status.label.includes(title)) {
@@ -72,7 +76,7 @@ export const myContentConverter = {
       data.color = colors.Unknown;
     }
 
-    const result = {
+    const result: DocumentData = {
       id: data.blm_point_id,
       key: snapshot.id,
       submitted: data.created_at.toDate().toISOString(),