kaleidr.js — loader

1つの script タグで window.Kaleidr をインストールし、 <kaleidr-map> 要素を定義します：

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

この façade は軽量な loader です。担当するのは version、config、script loading、 product registry、key passing、doorway selection、mount lifecycle、error normalization、dormancy flag のみです。各製品の実際の動作は 独自の bundle にあり、初回使用時に URL から遅延読み込みされます。

Kaleidr.mount(target, options) → KaleidrHandle

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map: myMap,
});

product bundle がバックグラウンドで読み込まれている間も、handle は 同期的に 返されます。ロード前の呼び出しはキューに入り、準備完了後に実行されます。

オプション

オプション	型	説明
product	'chat' | 'viewer' | 'editor' | 'tile'	必須。bundle + デフォルト doorway を選択します。
publishableKey	string	Publishable browser key（kld_pk_live_…）。chat/editor/tile では必須。viewer にキーを渡してはいけません。渡すと product_not_allowed で拒否されます。SDK は実行時にキーを短期間有効な origin-bound session と交換します。
apiKey	string	publishableKey の非推奨 alias。旧 kld_live_… キーも使用できます。
shareId / mapId	string	Viewer のみ。必須 — 省略すると bundle 読み込み時にエラーになります。
styleId	string	Tile/editor。Tile: Kaleidr ベースマップの style id（デフォルトは viewer の canvas default）。Editor: style id または 完全な style URL — 省略時は組織に保存された default、次に kaleidr-morning が適用されます。
map	map instance	Chat: アタッチ先となるページ内の稼働中 Mapbox / MapLibre / Google map。
mapTarget	string	Chat: host map element の CSS selector（宣言的パス）。
contained	boolean	Chat のみ。デフォルト false。パネルを document.body 上に浮かせず、mount element 内に固定します — 指定しない場合、パネルがレイアウト外に出て壊れて見えます。
center zoom		初期カメラ（viewer, editor, tile）。
pitch bearing		viewer、editor、tile の初期カメラ。
theme	object or JSON object string	CSS-token bag（例 { '--kd-accent': '#2da84a' }）。Chat は handle 経由のライブ更新にも対応します。名前付き string theme は サポートされません。単なる string を渡すと警告が記録され、無視されます。
doorway	'iframe' | 'attach'	Escape hatch — product default を上書きします。
base	string	bundle の読み込み元 CDN origin を上書きします（dev / self-host）。
viewerBase	string	Viewer/tile: iframe が読み込む origin。base とは別です — iframe が CDN を参照することはありません。
tileBase	string	Editor: カタログの styleId 値を解決する tile CDN。デフォルト https://tile.kaleidr.com。
apiBase	string	service path を含める必要があります。 デフォルト https://api.kaleidr.com/inference-api。https://api.kaleidr.com のような bare origin は session exchange で 404 になります。chat、editor、tile — session exchange を行うすべての product に適用されます。
enabled	boolean	mount ごとの dormancy 上書き。

KaleidrHandle

handle の形は superset です — 各 product はサポート可能な method のみを 実装します。どの product でどの method が何をするかは Handle matrix を参照してください。

interface KaleidrHandle {
  product: 'chat' | 'viewer' | 'editor' | 'tile';
  // Always present.
  destroy(): void;
  // Viewer, editor, tile: real. Chat: NO-OP (chat does not drive the map).
  setCamera?(camera): void;
  // Chat: live update (real). Editor: mount-time only; live update is a
  // follow-up SDK release. Viewer/tile: not applicable.
  setTheme?(theme): void;
  // Tile only. Not exposed on any other product.
  setStyle?(styleId: string): void;
}

現在、サポートされていない method を呼び出すと [kaleidr] warning が記録され、そのまま戻ります — loader は例外を投げません。この動作は v1 major alias の contract です。

Kaleidr.init()

DOM 内にすでに存在する <kaleidr-map> を upgrade します。ロード時に自動実行されます。 動的に要素を挿入した場合は、その後に呼び出してください。

Kaleidr.enable(on = true)

SDK は デフォルトで有効 です — 何かを enable する必要はなく、 quickstart は記載どおりに動作します。

enable() はオフスイッチとして存在します。false を渡すと mount() が bundle を一切読み込まなくなるため、embed を consent banner の背後に置いたり、markup を削除せずに ページ上で無効化したりできます。同じスイッチは window.__KALEIDR_EMBED_ENABLED__ = false（script 実行前）または mount ごとの flag 属性 / enabled オプションとしても使用できます。

Kaleidr.version

loader の version string。

CDN base の上書き

ローカル開発や self-hosting では、loader の参照先を別の origin に変更できます：

<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn-dev.kaleidr.com';</script>