fix(Map): resolve Stamen tile 401 errors and add free tile providers

Tile Provider Updates:
- Add 3 new free tile providers (no API key required):
  - osm-france: French-language OpenStreetMap style
  - osm-bw: Black & white monochrome OSM variant
  - wikimedia: Wikimedia Foundation tile service
- Update Stamen provider configs to require API keys:
  - Mark stamen-toner, stamen-terrain, stamen-watercolor as requiresApiKey: true
  - Update URLs with ?api_key={apiKey} parameter
  - Update documentation to reflect authentication requirement

Storybook Changes:
- Remove Stamen tile examples from public Storybook demos
  - Prevents 401 errors on GitHub Pages deployment
  - Stadia Maps allows localhost without auth but requires API keys for production domains
- Update Premium Providers documentation section:
  - Add Stamen (via Stadia Maps) with signup link
  - Document Geoapify and Thunderforest providers
  - Show code examples with tileApiKey prop usage
- Update intro text: 15+ → 18+ tile providers supported
- Add note clarifying that examples show free providers only

Why this fixes the issue:
- Stadia Maps (hosting Stamen tiles) allows unauthenticated localhost requests for development
- Production domains (like GitHub Pages) require API key authentication
- This explains why tiles work locally but return 401 on deployed Storybook

Result:
- Library now supports 18 tile providers (up from 15)
- Public Storybook shows only free providers (no 401 errors)
- Users with API keys can still use premium providers via tileApiKey prop
- Clear documentation on authentication requirements

Author: JakeLin

packages/ui/src/components/Map/TileProviders.stories.tsx

@@ -110,9 +110,6 @@ export const TileProviders: FC = () => {
   const [selectedId1, setSelectedId1] = useState<string | undefined>(undefined);
   const [selectedId2, setSelectedId2] = useState<string | undefined>(undefined);
   const [selectedId3, setSelectedId3] = useState<string | undefined>(undefined);
-  const [selectedId4, setSelectedId4] = useState<string | undefined>(undefined);
-  const [selectedId5, setSelectedId5] = useState<string | undefined>(undefined);
-  const [selectedId6, setSelectedId6] = useState<string | undefined>(undefined);
   const [selectedId7, setSelectedId7] = useState<string | undefined>(undefined);
   const [selectedId8, setSelectedId8] = useState<string | undefined>(undefined);
   const [selectedId9, setSelectedId9] = useState<string | undefined>(undefined);
@@ -134,9 +131,10 @@ export const TileProviders: FC = () => {
             lineHeight: 1.6,
           }}
         >
-          The Map component supports 15+ tile provider styles powered by OpenStreetMap data. Choose
-          from CARTO basemaps, Stamen artistic styles, specialized maps, and more. Simply pass the{' '}
-          <code>tileProvider</code> prop to any Map component.
+          The Map component supports 18+ tile provider styles powered by OpenStreetMap data. Choose
+          from CARTO basemaps, OSM variants, specialized maps, and more. Simply pass the{' '}
+          <code>tileProvider</code> prop to any Map component. Examples below show free providers that
+          work without API keys.
         </p>
 
         <div
@@ -230,81 +228,6 @@ export const TileProviders: FC = () => {
         </div>
       </section>
 
-      {/* Stamen Design Maps */}
-      <section style={{ paddingTop: '32px', borderTop: '1px solid var(--ai-color-border-default)' }}>
-        <h2 style={{ marginBottom: '8px', fontSize: '28px', fontWeight: 600 }}>
-          Stamen Design Maps
-        </h2>
-        <p
-          style={{
-            margin: '0 0 32px',
-            color: 'var(--ai-color-text-secondary)',
-            lineHeight: 1.6,
-          }}
-        >
-          Distinctive artistic map styles by Stamen Design. Served via Stadia Maps with no API key
-          required.
-        </p>
-
-        <div style={{ display: 'flex', flexDirection: 'column', gap: '64px' }}>
-          <ExampleSection
-            title="Stamen Toner"
-            description="High-contrast black and white with print-like effect."
-            code={`<Map
-  locations={locations}
-  tileProvider="stamen-toner"
-/>`}
-          >
-            <CompactMap
-              key="stamen-toner"
-              locations={locations}
-              selectedId={selectedId4}
-              onLocationSelect={setSelectedId4}
-              tileProvider="stamen-toner"
-              defaultCenter={[37.7849, -122.4194]}
-              defaultZoom={13}
-            />
-          </ExampleSection>
-
-          <ExampleSection
-            title="Stamen Terrain"
-            description="Topographic terrain style with hillshading. Perfect for outdoor and regional context."
-            code={`<Map
-  locations={locations}
-  tileProvider="stamen-terrain"
-/>`}
-          >
-            <CompactMap
-              key="stamen-terrain"
-              locations={locations}
-              selectedId={selectedId5}
-              onLocationSelect={setSelectedId5}
-              tileProvider="stamen-terrain"
-              defaultCenter={[37.7849, -122.4194]}
-              defaultZoom={13}
-            />
-          </ExampleSection>
-
-          <ExampleSection
-            title="Stamen Watercolor"
-            description="Artistic watercolor rendition of map data."
-            code={`<Map
-  locations={locations}
-  tileProvider="stamen-watercolor"
-/>`}
-          >
-            <CompactMap
-              key="stamen-watercolor"
-              locations={locations}
-              selectedId={selectedId6}
-              onLocationSelect={setSelectedId6}
-              tileProvider="stamen-watercolor"
-              defaultCenter={[37.7849, -122.4194]}
-              defaultZoom={13}
-            />
-          </ExampleSection>
-        </div>
-      </section>
 
       {/* OpenStreetMap Styles */}
       <section style={{ paddingTop: '32px', borderTop: '1px solid var(--ai-color-border-default)' }}>
@@ -460,18 +383,73 @@ export const TileProviders: FC = () => {
                 lineHeight: 1.6,
               }}
             >
-              Additional tile providers are available that require free API keys. All offer generous
-              free tiers:
+              Additional tile providers are available that require API keys. All offer generous free
+              tiers:
             </p>
+            <ul
+              style={{
+                margin: '0 0 16px',
+                paddingLeft: '20px',
+                color: 'var(--ai-color-text-secondary)',
+                lineHeight: 1.8,
+              }}
+            >
+              <li>
+                <strong>Stamen Design Maps</strong> (via Stadia Maps) -{' '}
+                <a
+                  href="https://client.stadiamaps.com/signup/"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  style={{ color: 'var(--ai-color-brand-primary)' }}
+                >
+                  Sign up at Stadia Maps
+                </a>
+                <br />
+                <code>stamen-toner</code>, <code>stamen-terrain</code>, <code>stamen-watercolor</code>
+              </li>
+              <li>
+                <strong>Geoapify</strong> -{' '}
+                <a
+                  href="https://www.geoapify.com/"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  style={{ color: 'var(--ai-color-brand-primary)' }}
+                >
+                  Sign up at Geoapify
+                </a>
+                <br />
+                <code>geoapify-osm-bright-grey</code>, <code>geoapify-osm-bright-smooth</code>
+              </li>
+              <li>
+                <strong>Thunderforest</strong> -{' '}
+                <a
+                  href="https://www.thunderforest.com/"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  style={{ color: 'var(--ai-color-brand-primary)' }}
+                >
+                  Sign up at Thunderforest
+                </a>
+                <br />
+                <code>thunderforest-transport</code>, <code>thunderforest-landscape</code>
+              </li>
+            </ul>
             <CodeBlock
-              code={`// Geoapify OSM Bright styles
+              code={`// Example: Using Stamen Watercolor with API key
+<Map
+  locations={locations}
+  tileProvider="stamen-watercolor"
+  tileApiKey={process.env.REACT_APP_STADIA_MAPS_KEY}
+/>
+
+// Example: Geoapify OSM Bright
 <Map
   locations={locations}
   tileProvider="geoapify-osm-bright-grey"
   tileApiKey={process.env.REACT_APP_GEOAPIFY_KEY}
 />
 
-// Thunderforest Transport
+// Example: Thunderforest Transport
 <Map
   locations={locations}
   tileProvider="thunderforest-transport"

packages/ui/src/components/Map/tileProviders.ts

@@ -51,6 +51,9 @@ export interface TileProviderConfig {
 export type TileProviderPreset =
   | 'osm-standard'
   | 'osm-humanitarian'
+  | 'osm-france'
+  | 'osm-bw'
+  | 'wikimedia'
   | 'carto-light'
   | 'carto-dark'
   | 'carto-voyager'
@@ -96,6 +99,43 @@ export const TILE_PROVIDER_PRESETS: Record<TileProviderPreset, TileProviderConfi
     detectRetina: true,
   },
 
+  /**
+   * OpenStreetMap France - French-language OSM style
+   * Free to use, no API key required
+   */
+  'osm-france': {
+    url: 'https://{s}.tile.openstreetmap.fr/osmfr/{z}/{x}/{y}.png',
+    attribution:
+      '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors, Tiles by <a href="https://www.openstreetmap.fr">OpenStreetMap France</a>',
+    subdomains: ['a', 'b', 'c'],
+    maxZoom: 20,
+    detectRetina: true,
+  },
+
+  /**
+   * OpenStreetMap Black & White - Monochrome OSM style
+   * Free to use, no API key required
+   */
+  'osm-bw': {
+    url: 'https://tiles.wmflabs.org/bw-mapnik/{z}/{x}/{y}.png',
+    attribution:
+      '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
+    maxZoom: 18,
+    detectRetina: true,
+  },
+
+  /**
+   * Wikimedia Maps - Wikimedia Foundation tile service
+   * Free to use, no API key required
+   */
+  wikimedia: {
+    url: 'https://maps.wikimedia.org/osm-intl/{z}/{x}/{y}.png',
+    attribution:
+      '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors, <a href="https://foundation.wikimedia.org/wiki/Maps_Terms_of_Use">Wikimedia maps</a>',
+    maxZoom: 19,
+    detectRetina: true,
+  },
+
   /**
    * CARTO Light (Positron) - Clean, minimal light theme
    * Free to use, no API key required
@@ -138,38 +178,44 @@ export const TILE_PROVIDER_PRESETS: Record<TileProviderPreset, TileProviderConfi
 
   /**
    * Stamen Toner - High contrast black & white
-   * Free to use via Stadia Maps, no API key required
+   * Requires Stadia Maps API key (free tier available at https://client.stadiamaps.com/signup/)
+   * Note: These tiles are hosted by Stadia Maps and require authentication
    */
   'stamen-toner': {
-    url: 'https://tiles.stadiamaps.com/tiles/stamen_toner/{z}/{x}/{y}.png',
+    url: 'https://tiles.stadiamaps.com/tiles/stamen_toner/{z}/{x}/{y}.png?api_key={apiKey}',
     attribution:
       '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors &copy; <a href="https://stamen.com">Stamen Design</a>',
     maxZoom: 18,
     detectRetina: true,
+    requiresApiKey: true,
   },
 
   /**
    * Stamen Terrain - Topographic terrain style with hillshading
-   * Free to use via Stadia Maps, no API key required
+   * Requires Stadia Maps API key (free tier available at https://client.stadiamaps.com/signup/)
+   * Note: These tiles are hosted by Stadia Maps and require authentication
    */
   'stamen-terrain': {
-    url: 'https://tiles.stadiamaps.com/tiles/stamen_terrain/{z}/{x}/{y}.png',
+    url: 'https://tiles.stadiamaps.com/tiles/stamen_terrain/{z}/{x}/{y}.png?api_key={apiKey}',
     attribution:
       '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors &copy; <a href="https://stamen.com">Stamen Design</a>',
     maxZoom: 18,
     detectRetina: true,
+    requiresApiKey: true,
   },
 
   /**
    * Stamen Watercolor - Artistic watercolor style
-   * Free to use via Stadia Maps, no API key required
+   * Requires Stadia Maps API key (free tier available at https://client.stadiamaps.com/signup/)
+   * Note: These tiles are hosted by Stadia Maps and require authentication
    */
   'stamen-watercolor': {
-    url: 'https://tiles.stadiamaps.com/tiles/stamen_watercolor/{z}/{x}/{y}.jpg',
+    url: 'https://tiles.stadiamaps.com/tiles/stamen_watercolor/{z}/{x}/{y}.jpg?api_key={apiKey}',
     attribution:
       '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors &copy; <a href="https://stamen.com">Stamen Design</a>',
     maxZoom: 16,
     detectRetina: false, // Watercolor doesn't benefit from retina
+    requiresApiKey: true,
   },
 
   /**