Skip to content

Codebase Documentation

Jump to bottom Edit New page
niryuu edited this page Jun 2, 2026 · 3 revisions

@geolonia/embed コードベースドキュメント (Claude Code 向け)

この Wiki は Claude Code が @geolonia/embed リポジトリで作業する際の参照資料。 現状の挙動を一切の歪みなく再現できるレベルを目指して記述している (embed-core 分離 + 書き直し前提)。

プロジェクト概要

項目 値
パッケージ名 @geolonia/embed
バージョン 5.2.2
ライセンス MIT
リポジトリ https://github.com/geolonia/embed
説明 MapLibre GL JS をラップし、Geolonia の認証・スタイル配信・プラグインを統合した地図埋め込みライブラリ

メンタルモデル

2 系統の利用方法:

A. HTML 宣言的利用 (embed.js)

<div class="geolonia" data-lat="35.68" data-lng="139.76" data-zoom="14"></div>
<script src="https://cdn.geolonia.com/embed?geolonia-api-key=YOUR-API-KEY"></script>
  • embed.js 読み込みで自動 DOM 走査・マップ生成
  • window.geolonia がグローバル設定される (window.maplibregl / window.mapboxgl も同一参照)

B. プログラム的利用 (embed-core.js)

import { GeoloniaMap } from '@geolonia/embed/core';
new GeoloniaMap({ container: '#map', center: [139.76, 35.68], zoom: 14 });
  • React wrapper 等で利用
  • 自動 DOM 走査・グローバル登録なし

両者とも内部的に GeoloniaMap (maplibregl.Map のサブクラス) を生成する。

技術スタック

  • 地図エンジン: maplibre-gl@5.19.0
  • 言語: TypeScript (target: ES2018)
  • バンドラー: Webpack 5 (UMD)
  • 主要依存:
    • pmtiles@3.0.6 — PMTiles プロトコル
    • tinycolor2@1.4.1 — マーカー影色生成
    • sanitize-html@2.8.0 — popup HTML サニタイズ
    • @turf/center@6.0.1 — popup 位置計算
    • @geolonia/mbgl-gesture-handling@1.0.15 — ジェスチャー制御
    • @mapbox/geojson-extent@1.0.0 — GeoJSON bbox 計算
  • テスト: Vitest (unit), Playwright (E2E, chromium のみ)

ソースファイル一覧

ファイル 行数 役割 主要 export
src/embed.ts 57 フルエントリ。グローバル登録・自動 render geolonia, Map (=GeoloniaMap), Marker (=GeoloniaMarker), SimpleStyle, embedVersion, type EmbedAttributes, EmbedPlugin, Geolonia, GeoloniaMapOptions
src/embed-core.ts 23 副作用なしエントリ (React 等で利用) GeoloniaMap, GeoloniaMarker, SimpleStyle, SimpleStyleVector, keyring, registerPlugin, embedVersion
src/lib/geolonia-map.ts 429 GeoloniaMap クラス (maplibre.Map サブクラス) GeoloniaMap (default), type GeoloniaMapOptions
src/lib/render.ts 122 DOM 走査・遅延読み込み・プラグイン renderGeoloniaMap, registerPlugin
src/lib/parse-atts.ts 67 data-* 属性パース parseAtts (default)
src/lib/keyring.ts 137 API キー・ステージ管理シングルトン keyring
src/lib/util.ts 430 ユーティリティ関数群 (15 関数) isURL, isGeoloniaTilesHost, checkPermission, getLang, getContainer, getStyle, getOptions, getSessionId, parseControlOption, parseSimpleVector, handleRestrictedMode, handleErrorMode, sanitizeDescription, loadImageCompatibility, random, isDomElement, isScrollable, handleMarkerOptions, type GetImageCallback
src/lib/simplestyle.ts 435 GeoJSON SimpleStyle レンダリング SimpleStyle
src/lib/simplestyle-vector.ts 257 ベクトルタイル SimpleStyle SimpleStyleVector (default)
src/lib/geolonia-marker.ts 53 デフォルト SVG マーカー GeoloniaMarker (default)
src/lib/controls/geolonia-control.ts 38 Geolonia ブランディングロゴ GeoloniaControl
src/lib/CustomAttributionControl.ts 394 Shadow DOM 帰属表示 CustomAttributionControl (default)
src/lib/maplibre-util.ts 137 DOM ユーティリティ (maplibre-gl-js から移植) DOM, bindAll
src/types.ts 44 共有型 type EmbedAttributes, EmbedPlugin
src/types-internal.ts 4 SVG モジュール型宣言 (declare module)
src/version.ts 1 ビルド時生成のバージョン定数 VERSION

アーキテクチャ要約

script タグロード → embed.ts (top-level)
  ├─ window.geolonia / maplibregl / mapboxgl 設定
  └─ renderGeoloniaMap()
       ├─ pmtiles プロトコル登録
       ├─ keyring.parse()
       ├─ checkPermission()
       ├─ document.querySelectorAll('.geolonia[data-lazy-loading="off"]') → 即時 render
       └─ '.geolonia:not([data-lazy-loading="off"])' → IntersectionObserver 監視
            ↓ 可視化時
            renderSingleMap(target)
              └─ new GeoloniaMap(container)
                   ├─ getContainer / 重複防止 / parseAtts / getOptions
                   ├─ innerHTML 退避 → 空に
                   ├─ loader spinner 追加
                   ├─ sessionId / sourcesUrl 構築
                   ├─ transformRequest override (key/sessionId 注入)
                   ├─ super(options) で maplibre.Map 初期化
                   ├─ controls 追加 (Geolonia, Attribution, Fullscreen, Navigation, Geolocate, Scale)
                   ├─ map.on('load') → loader 削除 / gesture / marker
                   ├─ map.on('styledata') → SimpleStyle / SimpleStyleVector / 3D
                   ├─ map.on('error') → 402 で handleRestrictedMode
                   └─ container.geoloniaMap = map (シングルトン)

詳細は Architecture 参照。

グローバル状態

状態 場所 注意
window.geolonia embed.ts 経由でセット ページライフタイム全期
window.maplibregl / window.mapboxgl 同一参照 (後方互換) 削除可否は議論余地
keyring シングルトン keyring.ts:134 reset() で初期化 (テスト用)
plugins (module-level Array) render.ts:10 registerPlugin で push、クリアなし
sessionId (module-level cache) util.ts:337 初回 getSessionId で生成、以降固定
pmtiles protocol maplibre 内部 embed.js / embed-core.js で二重登録の可能性
container.geoloniaMap DOM 要素プロパティ remove() で delete
map._geolonia_restricted_mode_handled map インスタンス (動的) 402 再入防止

詳細は Architecture のグローバル状態節。

重要な型

  • EmbedAttributes (src/types.ts:3-34) — 全 data-* 属性のキーと型
  • EmbedPlugin<PluginAttributes> (src/types.ts:36-44) — プラグイン関数シグネチャ
  • GeoloniaMapOptions (src/lib/geolonia-map.ts:38) — MapOptions & { interactive?: boolean }
  • Geolonia (src/embed.ts:20-28) — window.geolonia の型

ドキュメント構成 (このディレクトリ)

上位 (概念)

  • Home — このファイル (索引)
  • Architecture — 全体アーキテクチャ・初期化フロー・グローバル状態
  • Core-vs-Wrapper — embed-core 分離方針・lib/wrapper 境界・書き直し時の移植チェックリスト

参照 (定数・属性・API)

  • Data-Attributes — data-* 属性完全リファレンス (29 属性 + 隠れ属性)
  • URL-Rewrite-Spec — transformRequest の URL 変換完全表
  • Constants — 全ハードコード値 (URL, 色, px, zoom, HTTP status, CSS class, layer ID...)

仕様 (隠れた挙動)

  • Hidden-Spec — 未文書化機能の規約 (3D metadata, SimpleStyle GeoJSON props, geolonia://, container.geoloniaMap, sanitize-html 設定, etc.)
  • Suspicious-Logic — 怪しい / wrong に見えるロジックカタログ (30 項目)

モジュール詳細

運用 (作業手順)

  • Development-Guide — ビルド・テスト・lint・ステージ環境変数
  • E2E-Plan — E2E テスト拡充計画 (#411 umbrella)
  • E2E-for-Embed-Only-Features — embed (wrapper) にしかない機能の E2E 戦略 (グローバル登録、auto-render、Observer、プラグイン等)

このドキュメントの使い方

「○○ という機能を変更したい」

  1. 関連する 各 Module-* ページ を読む
  2. Data-Attributes で関連 data-* 属性を確認
  3. Hidden-Spec / Suspicious-Logic で関連の制約や落とし穴を確認
  4. 必要なら Constants で値の定義場所を grep する元の情報を取得

「embed-core 切り出し / 書き直し作業」

  1. Core-vs-Wrapper を全体マップとして読む
  2. 該当モジュールの詳細 (各 Module-* ページ) で挙動を再確認
  3. URL-Rewrite-Spec / Data-Attributes / Hidden-Spec の表を写経して回帰しないテストを書く
  4. Suspicious-Logic の各項目で「現状維持 / 修正 / 削除」を決める

「E2E テストを書きたい」

  1. E2E-Plan で該当 Phase を確認
  2. Development-Guide の E2E 節でコマンドを確認
  3. Module-Util / Module-Render で対象機能の挙動を確認

「不明点の調査」

Suspicious-Logic には 30 個の「現状動いてるが意図不明」項目をまとめてある。仕様確認の際の参考に。

参照する重要な root 直下ドキュメント

  • CLAUDE.md — プロジェクトレベル指示 (issue→code→PR ワークフロー)
  • README.md — 公開向け README
  • PLUGIN.md — プラグイン作成ドキュメント
  • CHANGELOG.md — リリース履歴

既知の未解決項目

  • Suspicious-Logic の 30 項目
  • simplestyle.ts:32 の heatmap TODO
  • SimpleStyleVector の remove() 欠落 (listener leak)
  • iframe 許可特例リストのメンテナンス負担 (Codepen / JSFiddle / CodeSandbox のみ)
  • MAP_PLATFORM_STAGE の build-time 固定 (ランタイム可変化の議論)
  • デフォルト色の重複定義 ('#E4402F', '#ff0000')

検証コマンド (このドキュメントの正しさを確認)

# 全 hex color literal
grep -nE "'#[0-9A-Fa-f]+'" src --include="*.ts" -r | grep -v test

# Geolonia 系ホスト
grep -nE "geolonia\.com|tileserver|cdn\.geolonia|api\.geolonia" src --include="*.ts" -r | grep -v test

# layer / source ID prefix
grep -nE "geolonia-simple-style|vt-(circle|geolonia)-simple-style" src --include="*.ts" -r

# CSS class
grep -nE "(geolonia-|maplibregl-|lds-grid|geolonia__)" src --include="*.ts" -r

# 全 data-* キー (`getAttribute`, `dataset.` を grep)
grep -nE "dataset\.|getAttribute\(" src --include="*.ts" -r | grep -v test

定数の照合表は Constants の最終節を参照。

Add a custom footer
Add a custom sidebar

Clone this wiki locally