`kaleidr.js` — loader

一個 script 標籤即可安裝 window.Kaleidr 並定義 <kaleidr-map> 元素：

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

此 façade 是一個輕量 loader。它只負責：版本、設定、script 載入、產品登錄、金鑰傳遞、接入方式選擇、掛載生命週期、錯誤標準化與 dormancy flag。每個產品的實際行為都存在於自己的 bundle 中，並在首次使用時透過 URL 延遲載入。

`Kaleidr.mount(target, options) → KaleidrHandle`

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

當產品 bundle 在背景載入時，也會同步傳回 handle；載入前的呼叫會進入佇列，並在準備完成後執行。

選項

選項	類型	說明
`product`	`'chat' \| 'viewer' \| 'editor' \| 'tile'`	必填。選擇 bundle + 預設接入方式。
`publishableKey`	`string`	Publishable 瀏覽器金鑰（`kld_pk_live_…`）。chat/editor/tile 必填；viewer 不得接收金鑰，傳入金鑰會以 `product_not_allowed` 拒絕。SDK 會在運行時將金鑰交換為短期、綁定 origin 的工作階段。
`apiKey`	`string`	`publishableKey` 的已棄用別名。也接受舊版 `kld_live_…` 金鑰。
`shareId` / `mapId`	`string`	僅 Viewer。必填 — 省略時會在 bundle 載入時拋出錯誤。
`styleId`	`string`	Tile/editor。Tile：Kaleidr 底圖 style id（預設使用 viewer 的 canvas 預設值）。Editor：style id 或完整 style URL — 省略時先套用組織儲存的預設值，接著使用 `kaleidr-morning`。
`map`	map instance	Chat：要連接的頁面內即時 Mapbox / MapLibre / Google 地圖。
`mapTarget`	`string`	Chat：host map element 的 CSS selector（宣告式路徑）。
`contained`	`boolean`	僅 Chat。預設 `false`。將面板固定在 mount element 內，而不是浮動在 `document.body` 上 — 否則面板會脫離頁面配置，看起來像是損壞。
`center` `zoom`		初始相機（viewer、editor、tile）。
`pitch` `bearing`		viewer、editor 與 tile 的初始相機。
`theme`	`object` or JSON object string	CSS-token 集合（例如 `{ '--kd-accent': '#2da84a' }`）。Chat 也支援透過 handle 即時更新。具名字串 theme 不受支援；傳入純字串會記錄警告並被忽略。
`doorway`	`'iframe' \| 'attach'`	備用選項 — 覆蓋產品預設值。
`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`	必須包含服務路徑。預設 `https://api.kaleidr.com/inference-api`；像 `https://api.kaleidr.com` 這樣的 bare origin 會在工作階段交換時傳回 404。適用於 chat、editor 與 tile — 也就是任何執行工作階段交換的產品。
`enabled`	`boolean`	每次掛載的 dormancy 覆蓋設定。

`KaleidrHandle`

handle 的結構是一個 superset — 每個產品只實作其能夠支援的方法。請參閱 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;
}

目前呼叫不支援的方法會記錄 [kaleidr] 警告並傳回 — loader 不會拋出錯誤。此行為屬於 v1 主版本別名的 contract。

`Kaleidr.init()`

升級 DOM 中已存在的任何 <kaleidr-map>。載入時會自動呼叫；動態插入元素後請再次呼叫。

`Kaleidr.enable(on = true)`

SDK 預設為啟用狀態 — 無需額外啟用任何內容， quickstart 按照文件即可運行。

enable() 可作為關閉開關：傳入 false 會阻止 mount() 載入任何 bundle，因此您可以將 embed 放在同意橫幅後方，或在不移除 markup 的情況下於頁面中停用它們。同一個開關也可以透過 window.__KALEIDR_EMBED_ENABLED__ = false（在 script 運行前）或每次掛載的 flag 屬性 / enabled 選項使用。

`Kaleidr.version`

loader 的版本字串。

覆蓋 CDN base

若用於本機開發或 self-hosting，請將 loader 指向另一個 origin：

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

Kaleidr.mount(target, options) → KaleidrHandle​

選項​

KaleidrHandle​

Kaleidr.init()​

Kaleidr.enable(on = true)​

Kaleidr.version​

覆蓋 CDN base​