Enhance map functionality and API documentation

- Updated API documentation for the `rebuildZooms` endpoint to clarify its long execution time and response behavior.
- Modified MapView component to manage tile cache invalidation after rebuilding zoom levels, ensuring fresh tile display.
- Introduced a new composable for handling tile cache invalidation state after admin actions.
- Enhanced character icon creation to reflect ownership status with distinct colors.
- Improved loading state handling in various components for better user experience during data fetching.

frontend-nuxt/lib/Character.ts

@@ -1,21 +1,21 @@
 import type L from 'leaflet'
+import { getColorForCharacterId, type CharacterColors } from '~/lib/characterColors'
 import { HnHMaxZoom } from '~/lib/LeafletCustomTypes'
 
 export type LeafletApi = typeof import('leaflet')
 
-/** SVG data URL for character marker icon (teal pin, bottom-center anchor). */
-const CHARACTER_ICON_URL =
-  'data:image/svg+xml,' +
-  encodeURIComponent(
+function buildCharacterIconUrl(colors: CharacterColors): string {
+  const svg =
     '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 32" width="24" height="32">' +
-      '<path fill="#0d9488" stroke="#0f766e" stroke-width="1" d="M12 2a6 6 0 0 1 6 6c0 4-6 10-6 10s-6-6-6-10a6 6 0 0 1 6-6z"/>' +
-      '<circle cx="12" cy="8" r="2.5" fill="white"/>' +
-      '</svg>'
-  )
+    `<path fill="${colors.fill}" stroke="${colors.stroke}" stroke-width="1" d="M12 2a6 6 0 0 1 6 6c0 4-6 10-6 10s-6-6-6-10a6 6 0 0 1 6-6z"/>` +
+    '<circle cx="12" cy="8" r="2.5" fill="white"/>' +
+    '</svg>'
+  return 'data:image/svg+xml,' + encodeURIComponent(svg)
+}
 
-function createCharacterIcon(L: LeafletApi): L.Icon {
+export function createCharacterIcon(L: LeafletApi, colors: CharacterColors): L.Icon {
   return new L.Icon({
-    iconUrl: CHARACTER_ICON_URL,
+    iconUrl: buildCharacterIconUrl(colors),
     iconSize: [24, 32],
     iconAnchor: [12, 32],
     popupAnchor: [0, -32],
@@ -28,6 +28,8 @@ export interface CharacterData {
   type: string
   id: number
   map: number
+  /** True when this character was last updated by one of the current user's tokens. */
+  ownedByMe?: boolean
 }
 
 export interface CharacterMapViewRef {
@@ -44,6 +46,7 @@ export interface MapCharacter {
   map: number
   text: string
   value: number
+  ownedByMe?: boolean
   leafletMarker: L.Marker | null
   remove: (mapview: CharacterMapViewRef) => void
   add: (mapview: CharacterMapViewRef) => void
@@ -54,7 +57,9 @@ export interface MapCharacter {
 export function createCharacter(data: CharacterData, L: LeafletApi): MapCharacter {
   let leafletMarker: L.Marker | null = null
   let onClick: ((e: L.LeafletMouseEvent) => void) | null = null
-  const characterIcon = createCharacterIcon(L)
+  let ownedByMe = data.ownedByMe ?? false
+  const colors = getColorForCharacterId(data.id, { ownedByMe })
+  let characterIcon = createCharacterIcon(L, colors)
 
   const character: MapCharacter = {
     id: data.id,
@@ -64,6 +69,12 @@ export function createCharacter(data: CharacterData, L: LeafletApi): MapCharacte
     map: data.map,
     text: data.name,
     value: data.id,
+    get ownedByMe() {
+      return ownedByMe
+    },
+    set ownedByMe(v: boolean | undefined) {
+      ownedByMe = v ?? false
+    },
 
     get leafletMarker() {
       return leafletMarker
@@ -90,6 +101,12 @@ export function createCharacter(data: CharacterData, L: LeafletApi): MapCharacte
     },
 
     update(mapview: CharacterMapViewRef, updated: CharacterData | MapCharacter): void {
+      const updatedOwnedByMe = (updated as { ownedByMe?: boolean }).ownedByMe ?? false
+      if (ownedByMe !== updatedOwnedByMe) {
+        ownedByMe = updatedOwnedByMe
+        characterIcon = createCharacterIcon(L, getColorForCharacterId(character.id, { ownedByMe }))
+        if (leafletMarker) leafletMarker.setIcon(characterIcon)
+      }
       if (character.map !== updated.map) {
         character.remove(mapview)
       }