improvement(tldraw): embed config (tldraw#9068)

Closes tldraw#9024

In order to stop the default Google Maps embed from reading
`process.env.NEXT_PUBLIC_GC_API_KEY` inside the SDK (tldraw#9024), this PR
lets consumers pass per-embed config through `EmbedShapeUtil.configure`.
Config is keyed by embed type, so each definition only receives its own
values and no key leaks across embeds.

```ts
EmbedShapeUtil.configure({
	embedConfig: { google_maps: { apiKey: '...' } },
})
```

tldraw.com now configures the embed util explicitly (reading the
vite-inlined key in app code) instead of relying on the SDK reading the
env var.

### Change type

- [x] `api`

### Test plan

1. Configure `EmbedShapeUtil` with a `google_maps` api key and paste a
Google Maps URL — the embed renders with the key.
2. Without config, the maps embed URL has no key (no env fallback in the
SDK).

- [x] Unit tests

### API changes

- Added `embedConfig` option to `EmbedShapeOptions`.
- Added `GoogleMapsEmbedConfig` and `DefaultEmbedConfig` types.
- `EmbedDefinition`/`CustomEmbedDefinition` are now generic over a
`Config`; `toEmbedUrl(url, config?)` takes an optional per-embed config.
- `getEmbedInfo`/`matchUrl` accept an optional `embedConfig` argument.

### Release notes

- Add `embedConfig` to `EmbedShapeUtil` so embeds like Google Maps can
be given an API key via `EmbedShapeUtil.configure({ embedConfig: {
google_maps: { apiKey } } })`. The default Google Maps embed no longer
reads `process.env.NEXT_PUBLIC_GC_API_KEY`.

Author: kaneel

apps/dotcom/client/src/tla/components/TlaEditor/TlaEditor.tsx

@@ -34,6 +34,7 @@ import { trackEvent, useHandleUiEvents } from '../../../utils/analytics'
 import { assetUrls } from '../../../utils/assetUrls'
 import { MULTIPLAYER_SERVER } from '../../../utils/config'
 import { createAssetFromUrl } from '../../../utils/createAssetFromUrl'
+import { embedShapeUtils } from '../../../utils/embedShapeUtil'
 import { isProductionEnv } from '../../../utils/env'
 import { globalEditor } from '../../../utils/globalEditor'
 import { multiplayerAssetStore } from '../../../utils/multiplayerAssetStore'
@@ -284,6 +285,7 @@ function TlaEditorInner({ fileSlug, deepLinks }: TlaEditorProps) {
 				licenseKey={getLicenseKey()}
 				store={store}
 				assetUrls={assetUrls}
+				shapeUtils={embedShapeUtils}
 				user={app?.tlUser}
 				onMount={handleMount}
 				onUiEvent={handleUiEvent}

apps/dotcom/client/src/tla/components/TlaEditor/TlaHistorySnapshotEditor.tsx

@@ -5,6 +5,7 @@ import { ThemeUpdater } from '../../../components/ThemeUpdater/ThemeUpdater'
 import { useLegacyUrlParams } from '../../../hooks/useLegacyUrlParams'
 import { useHandleUiEvents } from '../../../utils/analytics'
 import { assetUrls } from '../../../utils/assetUrls'
+import { embedShapeUtils } from '../../../utils/embedShapeUtil'
 import { globalEditor } from '../../../utils/globalEditor'
 import { useMaybeApp } from '../../hooks/useAppState'
 import { ReadyWrapper, useSetIsReady } from '../../hooks/useIsReady'
@@ -103,6 +104,7 @@ function TlaEditorInner({
 				licenseKey={getLicenseKey()}
 				snapshot={snapshot}
 				assetUrls={assetUrls}
+				shapeUtils={embedShapeUtils}
 				onMount={handleMount}
 				overrides={[fileSystemUiOverrides]}
 				initialState={'hand'}

apps/dotcom/client/src/tla/components/TlaEditor/TlaLegacyFileEditor.tsx

@@ -15,6 +15,7 @@ import { trackEvent, useHandleUiEvents } from '../../../utils/analytics'
 import { assetUrls } from '../../../utils/assetUrls'
 import { MULTIPLAYER_SERVER } from '../../../utils/config'
 import { createAssetFromUrl } from '../../../utils/createAssetFromUrl'
+import { embedShapeUtils } from '../../../utils/embedShapeUtil'
 import { globalEditor } from '../../../utils/globalEditor'
 import { multiplayerAssetStore } from '../../../utils/multiplayerAssetStore'
 import { useMaybeApp } from '../../hooks/useAppState'
@@ -115,6 +116,7 @@ function TlaEditorInner({
 				licenseKey={getLicenseKey()}
 				store={storeWithStatus}
 				assetUrls={assetUrls}
+				shapeUtils={embedShapeUtils}
 				onMount={handleMount}
 				overrides={[fileSystemUiOverrides]}
 				initialState={isReadonly ? 'hand' : 'select'}

apps/dotcom/client/src/tla/components/TlaEditor/TlaLegacySnapshotEditor.tsx

@@ -5,6 +5,7 @@ import { ThemeUpdater } from '../../../components/ThemeUpdater/ThemeUpdater'
 import { useLegacyUrlParams } from '../../../hooks/useLegacyUrlParams'
 import { useHandleUiEvents } from '../../../utils/analytics'
 import { assetUrls } from '../../../utils/assetUrls'
+import { embedShapeUtils } from '../../../utils/embedShapeUtil'
 import { globalEditor } from '../../../utils/globalEditor'
 import { useMaybeApp } from '../../hooks/useAppState'
 import { ReadyWrapper, useSetIsReady } from '../../hooks/useIsReady'
@@ -75,6 +76,7 @@ function TlaEditorInner({ snapshot }: { snapshot: TLStoreSnapshot }) {
 				licenseKey={getLicenseKey()}
 				snapshot={snapshot}
 				assetUrls={assetUrls}
+				shapeUtils={embedShapeUtils}
 				onMount={handleMount}
 				overrides={[fileSystemUiOverrides]}
 				initialState={'hand'}

apps/dotcom/client/src/tla/components/TlaEditor/TlaPublishEditor.tsx

@@ -6,6 +6,7 @@ import { useLegacyUrlParams } from '../../../hooks/useLegacyUrlParams'
 import { usePerformanceTracking } from '../../../hooks/usePerformanceTracking'
 import { useHandleUiEvents } from '../../../utils/analytics'
 import { assetUrls } from '../../../utils/assetUrls'
+import { embedShapeUtils } from '../../../utils/embedShapeUtil'
 import { globalEditor } from '../../../utils/globalEditor'
 import { TlaEditorErrorFallback } from './editor-components/TlaEditorErrorFallback'
 import { TlaEditorPublishedSharePanel } from './editor-components/TlaEditorPublishedSharePanel'
@@ -48,6 +49,7 @@ export function TlaPublishEditor({ schema, records }: TlaPublishEditorProps) {
 			<Tldraw
 				licenseKey={getLicenseKey()}
 				assetUrls={assetUrls}
+				shapeUtils={embedShapeUtils}
 				snapshot={snapshot}
 				overrides={[fileEditorOverrides]}
 				onUiEvent={handleUiEvent}

apps/dotcom/client/src/utils/embedShapeUtil.ts

@@ -0,0 +1,9 @@
+import { EmbedShapeUtil } from 'tldraw'
+
+// vite inlines this NEXT_PUBLIC_ var at build time.
+const googleMapsApiKey = process.env.NEXT_PUBLIC_GC_API_KEY
+
+// Module-scoped so the array keeps a stable identity across renders.
+export const embedShapeUtils = [
+	EmbedShapeUtil.configure({ embedConfig: { google_maps: { apiKey: googleMapsApiKey } } }),
+]

packages/tldraw/api-report.api.md

@@ -851,7 +851,7 @@ export interface CustomDebugFlags {
 }
 
 // @public (undocumented)
-export interface CustomEmbedDefinition extends EmbedDefinition {
+export interface CustomEmbedDefinition<Config = never> extends EmbedDefinition<Config> {
     // (undocumented)
     readonly icon: string;
 }
@@ -928,7 +928,7 @@ export const DEFAULT_EMBED_DEFINITIONS: readonly [{
         readonly 'allow-presentation': true;
     };
     readonly title: "Google Maps";
-    readonly toEmbedUrl: (url: string) => string | undefined;
+    readonly toEmbedUrl: (url: string, config?: GoogleMapsEmbedConfig | undefined) => string | undefined;
     readonly type: "google_maps";
     readonly width: 720;
 }, {
@@ -1144,6 +1144,12 @@ export const DefaultDialogs: NamedExoticComponent<object>;
 // @public (undocumented)
 export let defaultEditorAssetUrls: TLEditorAssetUrls;
 
+// @public
+export interface DefaultEmbedConfig {
+    // (undocumented)
+    readonly google_maps?: GoogleMapsEmbedConfig;
+}
+
 // @public (undocumented)
 export type DefaultEmbedDefinitionType = (typeof DEFAULT_EMBED_DEFINITIONS)[number]['type'];
 
@@ -1749,7 +1755,7 @@ export interface ElbowArrowTargetBox extends ElbowArrowBox {
 export function EllipseToolbarItem(): JSX.Element;
 
 // @public (undocumented)
-export interface EmbedDefinition {
+export interface EmbedDefinition<Config = never> {
     // (undocumented)
     readonly backgroundColor?: string;
     // (undocumented)
@@ -1779,7 +1785,7 @@ export interface EmbedDefinition {
     // (undocumented)
     readonly title: string;
     // (undocumented)
-    readonly toEmbedUrl: (url: string) => string | undefined;
+    readonly toEmbedUrl: (url: string, config?: Config) => string | undefined;
     // (undocumented)
     readonly type: string;
     // (undocumented)
@@ -1788,6 +1794,7 @@ export interface EmbedDefinition {
 
 // @public (undocumented)
 export interface EmbedShapeOptions extends ShapeOptionsWithDisplayValues<TLEmbedShape, EmbedShapeUtilDisplayValues> {
+    readonly embedConfig?: DefaultEmbedConfig & Record<string, unknown>;
     readonly embedDefinitions: readonly TLEmbedDefinition[];
 }
 
@@ -1850,7 +1857,7 @@ export class EmbedShapeUtil extends BaseBoxShapeUtil<TLEmbedShape> {
     // (undocumented)
     static props: RecordProps<TLEmbedShape>;
     // @deprecated (undocumented)
-    static setEmbedDefinitions(embedDefinitions: readonly EmbedDefinition[]): void;
+    static setEmbedDefinitions(embedDefinitions: readonly TLEmbedDefinition[]): void;
     // (undocumented)
     static type: "embed";
 }
@@ -2348,7 +2355,7 @@ export function getDisplayValues<Shape extends TLShape, DisplayValues extends ob
 }, shape: Shape, colorMode?: 'dark' | 'light'): DisplayValues;
 
 // @public
-export function getEmbedInfo(definitions: readonly TLEmbedDefinition[], inputUrl: string): TLEmbedResult;
+export function getEmbedInfo(definitions: readonly TLEmbedDefinition[], inputUrl: string, embedConfig?: Record<string, unknown>): TLEmbedResult;
 
 // @public (undocumented)
 export function getFontFamily(theme: TLTheme, font: string): string;
@@ -2389,6 +2396,12 @@ export function getUncroppedSize(shapeSize: {
     w: number;
 };
 
+// @public
+export interface GoogleMapsEmbedConfig {
+    // (undocumented)
+    readonly apiKey?: string;
+}
+
 // @public (undocumented)
 export function GroupMenuItem(): JSX.Element | null;
 
@@ -4428,7 +4441,7 @@ export interface TLElbowArrowInfo {
 }
 
 // @public (undocumented)
-export type TLEmbedDefinition = CustomEmbedDefinition | EmbedDefinition;
+export type TLEmbedDefinition = CustomEmbedDefinition<any> | EmbedDefinition<any>;
 
 // @public (undocumented)
 export type TLEmbedResult = {

packages/tldraw/src/index.ts

@@ -116,8 +116,10 @@ export {
 	embedShapePermissionDefaults,
 	unknownEmbedShapePermissionOverrides,
 	type CustomEmbedDefinition,
+	type DefaultEmbedConfig,
 	type DefaultEmbedDefinitionType,
 	type EmbedDefinition,
+	type GoogleMapsEmbedConfig,
 	type TLEmbedDefinition,
 	type TLEmbedShapePermissions,
 } from './lib/defaultEmbedDefinitions'

packages/tldraw/src/lib/defaultEmbedDefinitions.ts

@@ -111,7 +111,7 @@ export const DEFAULT_EMBED_DEFINITIONS = [
 		overridePermissions: {
 			'allow-presentation': true,
 		},
-		toEmbedUrl: (url) => {
+		toEmbedUrl: (url, config?: GoogleMapsEmbedConfig) => {
 			if (url.includes('/maps/embed?')) {
 				return url
 			} else if (url.includes('/maps/')) {
@@ -126,7 +126,9 @@ export const DEFAULT_EMBED_DEFINITIONS = [
 							? zoomOrMeters
 							: -Math.log2(parseInt(zoomOrMeters) / 14772321) / 0.8
 					const host = new URL(url).host.replace('www.', '')
-					result = `https://${host}/maps/embed/v1/view?key=${process.env.NEXT_PUBLIC_GC_API_KEY}&center=${lat},${lng}&zoom=${z}&maptype=${mapType}`
+					// TODO: remove the process.env fallback once all consumers pass `apiKey` via `embedConfig`.
+					const apiKey = config?.apiKey ?? process.env.NEXT_PUBLIC_GC_API_KEY
+					result = `https://${host}/maps/embed/v1/view?key=${apiKey}&center=${lat},${lng}&zoom=${z}&maptype=${mapType}`
 				} else {
 					result = ''
 				}
@@ -702,8 +704,28 @@ export const unknownEmbedShapePermissionOverrides: TLEmbedShapePermissions = {
 	'allow-popups': false,
 }
 
+/**
+ * Configuration for the default Google Maps embed. Provide an `apiKey` through
+ * {@link EmbedShapeUtil}'s `embedConfig` option to render Google Maps embeds.
+ *
+ * @public
+ */
+export interface GoogleMapsEmbedConfig {
+	readonly apiKey?: string
+}
+
+/**
+ * Per-embed configuration for the default embed definitions, keyed by embed type.
+ * Passed to an embed definition's `toEmbedUrl` when building its embed URL.
+ *
+ * @public
+ */
+export interface DefaultEmbedConfig {
+	readonly google_maps?: GoogleMapsEmbedConfig
+}
+
 /** @public */
-export interface EmbedDefinition {
+export interface EmbedDefinition<Config = never> {
 	readonly type: string
 	readonly title: string
 	readonly hostnames: readonly string[]
@@ -721,18 +743,18 @@ export interface EmbedDefinition {
 	// TODO: FIXME this is ugly be required because some embeds have their own border radius for example spotify embeds
 	readonly overrideOutlineRadius?: number
 	// eslint-disable-next-line tldraw/method-signature-style
-	readonly toEmbedUrl: (url: string) => string | undefined
+	readonly toEmbedUrl: (url: string, config?: Config) => string | undefined
 	// eslint-disable-next-line tldraw/method-signature-style
 	readonly fromEmbedUrl: (url: string) => string | undefined
 }
 
 /** @public */
-export interface CustomEmbedDefinition extends EmbedDefinition {
+export interface CustomEmbedDefinition<Config = never> extends EmbedDefinition<Config> {
 	readonly icon: string
 }
 
 /** @public */
-export type TLEmbedDefinition = EmbedDefinition | CustomEmbedDefinition
+export type TLEmbedDefinition = EmbedDefinition<any> | CustomEmbedDefinition<any>
 
 /** @public */
 export type DefaultEmbedDefinitionType = (typeof DEFAULT_EMBED_DEFINITIONS)[number]['type']

packages/tldraw/src/lib/shapes/embed/EmbedShapeUtil.tsx

@@ -18,7 +18,7 @@ import {
 } from '@tldraw/editor'
 import {
 	DEFAULT_EMBED_DEFINITIONS,
-	EmbedDefinition,
+	DefaultEmbedConfig,
 	TLEmbedDefinition,
 	TLEmbedShapePermissions,
 	embedShapePermissionDefaults,
@@ -41,6 +41,15 @@ export interface EmbedShapeOptions extends ShapeOptionsWithDisplayValues<
 > {
 	/** The embed definitions to use for this shape util. */
 	readonly embedDefinitions: readonly TLEmbedDefinition[]
+	/**
+	 * Per-embed configuration, keyed by embed type. Passed to each definition's `toEmbedUrl` when
+	 * building its embed URL — for example, an API key for the default Google Maps embed:
+	 *
+	 * ```ts
+	 * EmbedShapeUtil.configure({ embedConfig: { google_maps: { apiKey: '...' } } })
+	 * ```
+	 */
+	readonly embedConfig?: DefaultEmbedConfig & Record<string, unknown>
 }
 
 const getSandboxPermissions = (permissions: TLEmbedShapePermissions) => {
@@ -58,6 +67,7 @@ export class EmbedShapeUtil extends BaseBoxShapeUtil<TLEmbedShape> {
 
 	override options: EmbedShapeOptions = {
 		embedDefinitions: DEFAULT_EMBED_DEFINITIONS,
+		embedConfig: {},
 		getDefaultDisplayValues(): EmbedShapeUtilDisplayValues {
 			return {
 				showShadow: true,
@@ -74,10 +84,10 @@ export class EmbedShapeUtil extends BaseBoxShapeUtil<TLEmbedShape> {
 		return result.definition.canEditWhileLocked ?? true
 	}
 
-	private static legacyEmbedDefinitions: readonly EmbedDefinition[] | null = null
+	private static legacyEmbedDefinitions: readonly TLEmbedDefinition[] | null = null
 
 	/** @deprecated - Use `EmbedShapeUtil.configure({ embedDefinitions: [...] })` instead. */
-	static setEmbedDefinitions(embedDefinitions: readonly EmbedDefinition[]) {
+	static setEmbedDefinitions(embedDefinitions: readonly TLEmbedDefinition[]) {
 		EmbedShapeUtil.legacyEmbedDefinitions = embedDefinitions
 	}
 
@@ -90,7 +100,7 @@ export class EmbedShapeUtil extends BaseBoxShapeUtil<TLEmbedShape> {
 	}
 
 	getEmbedDefinition(url: string): TLEmbedResult {
-		return getEmbedInfo(this.getEmbedDefs(), url)
+		return getEmbedInfo(this.getEmbedDefs(), url, this.options.embedConfig)
 	}
 
 	override getText(shape: TLEmbedShape) {