Revival: secure, deployable, and maintainable again (waves 1–4)

.claude/skills/verify/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: verify
+description: Build, launch, and drive bubblemap locally to verify UI changes end-to-end with Playwright screenshots.
+---
+
+# Verifying bubblemap changes in the running app
+
+## Environment gotchas (do these first)
+
+- The default shell is Node 16: `source ~/.nvm/nvm.sh && nvm use 24` before
+  any npm/npx/firebase command.
+- Emulators need JDK 21: `export JAVA_HOME=/opt/homebrew/opt/openjdk@21;
+  export PATH="$JAVA_HOME/bin:$PATH"`.
+- Never start the hosting emulator locally — macOS ControlCenter squats
+  port 5000. Always pass `--only`.
+
+## Launch (two background processes)
+
+```bash
+npx firebase-tools emulators:start --only firestore,auth -P testing
+BROWSER=none npx vite --port 5173 --strictPort
+```
+
+Add `functions` to `--only` (and build ./functions first) if the flow under
+test calls the suggestion backend; otherwise the canvas logs
+`internal` / connection-refused errors on 5001 that are environment noise,
+not bugs.
+
+Ready when `curl localhost:9099` returns 200 and `curl localhost:5173`
+returns the HTML shell. Dev mode (`MODE !== 'production'`) auto-connects to
+the emulators and skips App Check.
+
+## Drive
+
+Playwright works well (install once: `npx playwright install chromium`;
+`npm i playwright` in a scratch dir, not the repo). Useful flows:
+
+- Signed-out home: fresh context → `/` → h1 "Bubble Map", primary CTA
+  "Create Your First MindMap".
+- Full CTA flow: click the CTA → anonymous sign-in → new map →
+  `waitForURL('**/mindmaps/**')` → canvas shows root bubble + unclaimed-
+  account banner.
+- Signed-in home state: revisit `/` in the same context → CTA becomes
+  "Browse Your Mindmaps".
+- Dark mode: new context with `colorScheme: 'dark'` → body background
+  should be `rgb(18, 18, 18)`.
+- Mobile: 375px viewport; assert
+  `document.documentElement.scrollWidth <= clientWidth`.
+- Capture `pageerror` + console errors; home page should produce zero.
+
+Screenshots to the session scratchpad, full-page for marketing routes.

.env.example

@@ -0,0 +1,29 @@
+# Copy this file to `.env` before running or building the app:
+#   cp .env.example .env
+#
+# These are Firebase Web SDK config values: public, client-visible
+# identifiers (they ship in the JS bundle), NOT secrets. The values below
+# are the official bubblemap projects' config; replace them with your own
+# Firebase project's config if you are working from a fork. The real
+# security boundary is Firestore rules, App Check, and API-key HTTP
+# referrer restrictions — never put actual secrets in VITE_* variables.
+
+# Production project (bubblemap-app)
+VITE_FIREBASE_API_KEY=AIzaSyAcH2oqXkfT2gJjbgmQeU62GmHy78PXyww
+VITE_FIREBASE_AUTH_DOMAIN=bubblemap-app.firebaseapp.com
+VITE_FIREBASE_PROJECT_ID=bubblemap-app
+VITE_FIREBASE_STORAGE_BUCKET=bubblemap-app.appspot.com
+VITE_FIREBASE_MESSAGING_SENDER_ID=961385019430
+VITE_FIREBASE_APP_ID=1:961385019430:web:d81b367e47eaecfc430ee7
+VITE_FIREBASE_MEASUREMENT_ID=G-EYXHSKR3ZV
+
+# Development/testing project (mind-map-testing) — used when MODE !== 'production'
+VITE_FIREBASE_API_KEY_DEV=AIzaSyD-oEhhMx9GRPYa1Dn6qhFR_yBV18KOY8Q
+VITE_FIREBASE_AUTH_DOMAIN_DEV=mind-map-testing.firebaseapp.com
+VITE_FIREBASE_PROJECT_ID_DEV=mind-map-testing
+VITE_FIREBASE_STORAGE_BUCKET_DEV=mind-map-testing.appspot.com
+VITE_FIREBASE_MESSAGING_SENDER_ID_DEV=427950169016
+VITE_FIREBASE_APP_ID_DEV=1:427950169016:web:ca279979776510972d0d4d
+VITE_FIREBASE_MEASUREMENT_ID_DEV=G-GZZRF9XDMM
+
+VITE_RECAPTCHA_PUBLIC_KEY=6LfGWUgtAAAAAHD94Wv7luFfyoAq45ebU6FnyZzz

.eslintrc.js

@@ -45,10 +45,14 @@ module.exports = {
     'react/require-default-props': 'off',
     'react-hooks/rules-of-hooks': 'error',
     'react-hooks/exhaustive-deps': 'warn',
+    'import/no-extraneous-dependencies': ['error', { devDependencies: true }],
   },
   settings: {
     jest: {
       version: 'latest',
     },
+    // ESM-only packages resolved via package.json "exports", which
+    // eslint-plugin-import's node resolver cannot follow
+    'import/core-modules': ['vite', '@vitejs/plugin-react'],
   },
 };

.github/CONTRIBUTING.md

@@ -4,8 +4,8 @@
 
 1. Ensure you have the following installed:
 
-   - Node.JS v16
-   - Node Package Manager v8
+   - Node.JS v24
+   - Node Package Manager v11
    - Firebase CLI
 
 1. Clone the repo

.github/workflows/cd.yml

@@ -9,26 +9,20 @@ jobs:
     name: Upload Build and Deploy to Firebase
     if: github.repository_owner == 'SpiritSeal'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Setup Node
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '16'
-
-      - name: Cache node modules
-        uses: actions/cache@v2
-        env:
-          cache-name: cache-node-modules
-        with:
-          path: ~/.npm
-          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-build-${{ env.cache-name }}-
-            ${{ runner.os }}-build-
-            ${{ runner.os }}-
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: |
+            package-lock.json
+            functions/package-lock.json
 
       - name: Install ./ Dependencies
         run: npm ci --prefer-offline --no-audit
@@ -39,6 +33,9 @@ jobs:
       - name: TSC
         run: npm run tsc
 
+      - name: Create .env from .env.example
+        run: cp .env.example .env
+
       - name: Build React
         run: npm run build
 
@@ -47,37 +44,26 @@ jobs:
           zip -r build.zip build
           tar -czf build.tar.gz build
 
-      - name: Upload .zip Build Asset
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: ${{ github.event.release.upload_url }}
-          asset_path: ./build.zip
-          asset_name: build.zip
-          asset_content_type: application/zip
-
-      - name: Upload .tar.gz Build Asset
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Upload Build Assets to Release
+        uses: softprops/action-gh-release@v2
         with:
-          upload_url: ${{ github.event.release.upload_url }}
-          asset_path: ./build.tar.gz
-          asset_name: build.tar.gz
-          asset_content_type: application/gzip
+          files: |
+            build.zip
+            build.tar.gz
 
-      - name: Deploy to Firebase
-        uses: w9jds/firebase-action@master
-        with:
-          args: deploy -P testing --force
+      - name: Deploy to Firebase (testing)
+        run: |
+          echo "$GCP_SA_KEY" > "$RUNNER_TEMP/gcp_sa_key.json"
+          npx firebase-tools deploy -P testing --force
         env:
-          GCP_SA_KEY: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_MIND_MAP_TESTING }}'
+          GCP_SA_KEY: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_MIND_MAP_TESTING }}
+          GOOGLE_APPLICATION_CREDENTIALS: ${{ runner.temp }}/gcp_sa_key.json
 
-      - name: Deploy to Firebase
+      - name: Deploy to Firebase (production)
         if: '!github.event.release.prerelease'
-        uses: w9jds/firebase-action@master
-        with:
-          args: deploy -P app --force
+        run: |
+          echo "$GCP_SA_KEY" > "$RUNNER_TEMP/gcp_sa_key.json"
+          npx firebase-tools deploy -P app --force
         env:
-          GCP_SA_KEY: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_BUBBLEMAP_APP }}'
+          GCP_SA_KEY: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_BUBBLEMAP_APP }}
+          GOOGLE_APPLICATION_CREDENTIALS: ${{ runner.temp }}/gcp_sa_key.json

.github/workflows/ci.yml

@@ -12,24 +12,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Setup Node
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '16'
-
-      - name: Cache node modules
-        uses: actions/cache@v2
-        env:
-          cache-name: cache-node-modules
-        with:
-          path: ~/.npm
-          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-build-${{ env.cache-name }}-
-            ${{ runner.os }}-build-
-            ${{ runner.os }}-
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: |
+            package-lock.json
+            functions/package-lock.json
 
       - name: Install ./ Dependencies
         run: npm ci --prefer-offline --no-audit
@@ -48,24 +40,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Setup Node
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '16'
-
-      - name: Cache node modules
-        uses: actions/cache@v2
-        env:
-          cache-name: cache-node-modules
-        with:
-          path: ~/.npm
-          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-build-${{ env.cache-name }}-
-            ${{ runner.os }}-build-
-            ${{ runner.os }}-
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: |
+            package-lock.json
+            functions/package-lock.json
 
       - name: Install ./ Dependencies
         run: npm ci --prefer-offline --no-audit
@@ -85,27 +69,25 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Setup Node
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '16'
-
-      - name: Cache node modules
-        uses: actions/cache@v2
-        env:
-          cache-name: cache-node-modules
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: |
+            package-lock.json
+            functions/package-lock.json
+
+      - name: Setup Java (required by Firebase emulators)
+        uses: actions/setup-java@v4
         with:
-          path: ~/.npm
-          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-build-${{ env.cache-name }}-
-            ${{ runner.os }}-build-
-            ${{ runner.os }}-
+          distribution: 'temurin'
+          java-version: '21'
 
       - name: Cache Firebase Emulators
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: ~/.cache/firebase/emulators
           key: ${{ runner.os }}-firebase-emulators

.github/workflows/preview.yml

@@ -10,24 +10,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Setup Node
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '16'
-
-      - name: Cache node modules
-        uses: actions/cache@v2
-        env:
-          cache-name: cache-node-modules
-        with:
-          path: ~/.npm
-          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-build-${{ env.cache-name }}-
-            ${{ runner.os }}-build-
-            ${{ runner.os }}-
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: |
+            package-lock.json
+            functions/package-lock.json
 
       - name: Install ./ Dependencies
         run: npm ci --prefer-offline --no-audit
@@ -38,6 +30,9 @@ jobs:
       - name: TSC
         run: npm run tsc
 
+      - name: Create .env from .env.example
+        run: cp .env.example .env
+
       - name: Build React
         run: npm run build
 
@@ -48,5 +43,3 @@ jobs:
           firebaseServiceAccount: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_MIND_MAP_TESTING }}
           projectId: mind-map-testing
           target: default
-        env:
-          FIREBASE_CLI_PREVIEWS: hostingchannels

.gitignore

@@ -196,4 +196,7 @@ tsconfig.tsbuildinfo
 
 *.secret
 
-.runtimeconfig.json
+# Local environment files (copy from .env.example)
+.env
+.env.local
+.env.*.local

.nvmrc

@@ -0,0 +1 @@
+24