@cn-map/gaode-react-extra 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Jungzl.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# @cn-map/gaode-react-extra
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+高德地图 react 扩展组件，基于 [`@cn-map/gaode-react`](https://github.com/Jungzl/amap/tree/main/packages/react) 的 `GLCustomLayer` 与 [`@react-three/fiber`](https://r3f.docs.pmnd.rs) 集成 three.js 3D 渲染图层。
+
+## 安装
+
+```bash
+npm install @cn-map/gaode-react-extra three@0.162.0 @types/three@0.162.0
+```
+
+```bash
+yarn add @cn-map/gaode-react-extra three@0.162.0 @types/three@0.162.0
+```
+
+```bash
+pnpm add @cn-map/gaode-react-extra three@0.162.0 @types/three@0.162.0
+```
+
+```bash
+bun add @cn-map/gaode-react-extra three@0.162.0 @types/three@0.162.0
+```
+
+> ⚠️ 由于 [`r163`](https://github.com/mrdoob/three.js/releases/tag/r163) 移除了 WebGL 1 支持，且高德 JS API 2.0 的 GL 上下文基于 WebGL 1，`three` 版本不得高于 `0.162.0`。
+
+> `@cn-map/gaode-react` 与 `@react-three/fiber` 是 peer 依赖，npm 7+ / pnpm 会自动安装，yarn 需手动添加。
+
+TypeScript 类型见 [`@cn-map/gaode-types`](../types/README.md)。
+
+## 使用
+
+| 导出名称   | 类型 | 描述                                          |
+| ---------- | ---- | --------------------------------------------- |
+| `R3FLayer` | 组件 | 基于 `GLCustomLayer` 的 `three.js` 3D渲染图层 |
+
+```tsx
+import { R3FLayer } from '@cn-map/gaode-react-extra'
+
+const Demo = () => (
+  <R3FLayer>
+    <ambientLight intensity={Math.PI / 2} />
+    <spotLight angle={0.15} decay={0} intensity={Math.PI} penumbra={1} position={[10, 10, 10]} />
+    <pointLight decay={0} intensity={Math.PI} position={[-10, -10, -10]} />
+    <mesh>
+      <boxGeometry args={[1, 1, 1]} />
+      <meshStandardMaterial color="orange" />
+    </mesh>
+  </R3FLayer>
+)
+```
+
+## 地理坐标
+
+`GeoGroup` 可以直接用经纬度放置对象，内部会通过 `map.customCoords` 转换到当前图层坐标系；children 仍使用相对该经纬度的局部坐标。
+
+```tsx
+import { GeoGroup, R3FLayer } from '@cn-map/gaode-react-extra'
+
+const Demo = () => (
+  <R3FLayer>
+    <GeoGroup altitude={100} position={[120.1, 30.2]}>
+      <mesh>
+        <boxGeometry />
+        <meshStandardMaterial />
+      </mesh>
+    </GeoGroup>
+  </R3FLayer>
+)
+```
+
+需要批量转换或读取转换函数时使用 `useMapCoordinates()`：
+
+```tsx
+const coordinates = useMapCoordinates()
+const positions = coordinates.lngLatsToScene(lnglats)
+```
+
+转换使用的 origin 与图层相机的 origin 一致，因此 2D/3D、平移、缩放和旋转下都保持对齐。
+
+`position` 也支持三元组 `[lng, lat, altitude]`；如果同时传了 `altitude`，以 `altitude` 为准。
+
+## 2D 地图
+
+高德地图的 `viewMode` 默认为 `2D`。`R3FLayer` 会根据当前视图自动选择相机：`2D` 使用 `OrthographicCamera`，`3D` 使用 `PerspectiveCamera`，并在每个地图帧同步 AMap 的相机参数，无需额外配置。地图旋转（`rotation`）也会同步到相机。地图平移时相机会跟随当前地图中心，固定世界坐标的对象保持与地图的地理锚定。
+
+> 如果通过 `camera` 传入自定义相机，或在子组件中通过 `makeDefault`（如 drei 的 `<PerspectiveCamera makeDefault />`）切换相机，2D 下必须使用正交相机、3D 下必须使用透视相机；相机类型不匹配时会输出 warning，并可能渲染空白或位置错误。
+
+> ⚠️ 一个地图 canvas 只支持挂载一个 `R3FLayer`。第二个实例会输出 warning 并跳过挂载，不会破坏第一个图层。第二个实例不会自动接管；需要在第一个卸载后重新挂载。
+
+## renderer 所有权
+
+通过 `gl` 传入 renderer 实例或同步工厂时，`R3FLayer` 会在挂载期间临时修改 `render`、`autoClear` 和 `forceContextLoss`，并在卸载完成后恢复原值；不会 dispose renderer，也不会让 AMap 的 GL context 丢失。若要在别处复用同一个 renderer，请等 unmount 完成后再使用。
+
+## 更多用法
+
+- `origin` 指定 Three.js 坐标系原点，省略时使用初始地图中心点。
+- `ref` 指向底层 `AMap.GLCustomLayer`；`onComplete` 会转发图层 complete 事件。
+- `gl` 支持 `WebGLRenderer` 实例、同步工厂或 `WebGLRendererParameters`；异步工厂以及使用其他 canvas/context 的 renderer 会被拒绝。
+- React 19 的 `StrictMode` 和 `Activity` 已覆盖测试；`Activity` 隐藏时 R3F root 保留、帧循环暂停。
+
+## 渲染循环模式
+
+| `frameloop`        | 说明                                                                          |
+| ------------------ | ----------------------------------------------------------------------------- |
+| `demand`（默认值） | 按需渲染，需在子组件中调用 `invalidate()`（例如在 `useFrame` 中）请求地图重绘 |
+| `always`           | 持续渲染，内部通过 `requestAnimationFrame` 持续触发地图重绘                   |
+| `never`            | 不主动渲染，需自行调用 `advance()` 请求渲染（用于完全接管渲染时机）           |
+
+```tsx
+import { useFrame } from '@react-three/fiber'
+
+const Animation = () => {
+  // frameloop="demand"（默认值）时，需要调用 invalidate() 请求地图重绘
+  useFrame(({ invalidate }) => invalidate())
+
+  return null
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import { MapCoordinates } from "@cn-map/gaode-extra-shared";
+import { FC, PropsWithChildren, ReactElement } from "react";
+import { GLCustomLayerProps } from "@cn-map/gaode-react";
+import { GLProps, RenderProps, Renderer } from "@react-three/fiber";
+import { WebGLRenderer, WebGLRendererParameters } from "three";
+/**
+ * Access the coordinate converter of the surrounding `R3FLayer`.
+ *
+ * The converter uses the same origin as the layer camera, so converted
+ * positions remain aligned with the map.
+ */
+export declare function useMapCoordinates(): MapCoordinates;
+interface GeoGroupProps extends PropsWithChildren {
+  /** Geographic position of the object. */
+  position: AMap.LngLatLike;
+  /**
+   * Altitude mapped to the scene's Z axis.
+   * Overrides a third tuple element such as `[lng, lat, altitude]`.
+   */
+  altitude?: number;
+}
+/**
+ * Place a R3F object using a geographic position.
+ *
+ * Children keep their local coordinates relative to the geographic origin.
+ */
+declare const GeoGroup: ({ position, altitude, children }: GeoGroupProps) => ReactElement;
+type GLDefaults = Omit<WebGLRendererParameters, "canvas"> & {
+  canvas: HTMLCanvasElement;
+};
+type GLFactory = (...args: never[]) => unknown;
+type GLObjectProps = Exclude<GLProps, Renderer | GLFactory>;
+type SyncRendererFactory = (defaults: GLDefaults) => WebGLRenderer;
+/**
+ * `R3FLayer` needs the renderer before its first map frame, so async factories are excluded.
+ * Renderer results must also reuse the AMap canvas and context, which is checked at runtime.
+ */
+type R3FLayerGLProps = WebGLRenderer | SyncRendererFactory | GLObjectProps;
+interface R3FLayerProps extends PropsWithChildren<Omit<RenderProps<HTMLCanvasElement>, "frameloop" | "gl"> & Omit<GLCustomLayerProps, "init" | "render">> {
+  /**
+   * R3F renderer、同步工厂或 renderer 参数。
+   *
+   * 工厂必须同步返回 renderer，且 renderer 必须复用 `GLCustomLayer` 的 `canvas` 与 WebGL `context`。
+   * renderer 参数中的 `canvas` / `context` 会被忽略，始终使用图层的上下文。
+   * 异步工厂或使用其他 canvas/context 的 renderer 会被拒绝。
+   */
+  gl?: R3FLayerGLProps;
+  /**
+   * Three.js渲染坐标系原点经纬度
+   * @default 地图中心点
+   */
+  origin?: AMap.LngLatLike;
+  /**
+   * R3F's render mode. Set to `demand` to only render on state change or `never` to take control.
+   * 与 `@react-three/fiber` 的 `Canvas` 不同，默认值为 `"demand"`
+   *
+   * @default "demand"
+   *
+   * @see https://docs.pmnd.rs/react-three-fiber/advanced/scaling-performance#on-demand-rendering
+   */
+  frameloop?: RenderProps<HTMLCanvasElement>["frameloop"];
+}
+/**
+ * `GLCustomLayer` 与 [`@react-three/fiber`](https://r3f.docs.pmnd.rs) 结合使用的组件
+ * 可以直接在子组件中使用 `@react-three/fiber` 组件，无需手动处理 `GLCustomLayer` 的 `init` 和 `render`
+ */
+declare const R3FLayer: FC<R3FLayerProps>;
+export { GeoGroup, type GeoGroupProps, R3FLayer, type R3FLayerGLProps, type R3FLayerProps };

package/dist/index.js

@@ -0,0 +1,534 @@
+import { createMapCoordinates, releaseCanvas, syncMapCamera, tryAcquireCanvas } from "@cn-map/gaode-extra-shared";
+import { logger, lostContextError } from "@cn-map/gaode-shared/utils";
+import * as React from "react";
+import { Fragment, StrictMode, Suspense, createContext, use, useCallback, useInsertionEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+import { GLCustomLayer, splitProps, useMapInstance } from "@cn-map/gaode-react";
+import { FiberProvider, traverseFiber, useActivityBridge, useContextBridge, useFiber } from "its-fine";
+import { _roots, applyProps, createRoot, events, unmountComponentAtNode } from "@react-three/fiber";
+import { WebGLRenderer } from "three";
+// src/r3f-layer/coordinates-context.ts
+const EMPTY = Symbol("No MapCoordinates");
+const MapCoordinatesContext = createContext(EMPTY);
+/**
+* Access the coordinate converter of the surrounding `R3FLayer`.
+*
+* The converter uses the same origin as the layer camera, so converted
+* positions remain aligned with the map.
+*/
+function useMapCoordinates() {
+	const context = use(MapCoordinatesContext);
+	if (context === EMPTY) throw lostContextError("`MapCoordinates`");
+	return useMemo(() => createMapCoordinates(context.map, context.origin), [context]);
+}
+// src/r3f-layer/geo-group.tsx
+/**
+* Place a R3F object using a geographic position.
+*
+* Children keep their local coordinates relative to the geographic origin.
+*/
+const GeoGroup = ({ position, altitude, children }) => {
+	const coordinates = useMapCoordinates();
+	const scenePosition = useMemo(() => coordinates.lngLatToScene(position, altitude), [
+		altitude,
+		coordinates,
+		position
+	]);
+	return /* @__PURE__ */ jsx("group", {
+		position: scenePosition,
+		children
+	});
+};
+// src/r3f-layer/map-frame-bridge.ts
+/**
+* 帧外请求与 AMap 帧之间的桥
+*
+* 核心约束：
+* - 同一帧内 `advance` 优先，不能被随后到达的 `redraw` 降级（否则 `useFrame` 链会断掉）
+* - `runInMapFrame` 在回调前取走并清空请求，保证一次请求只消费一次
+* - `inMapFrame` 支持嵌套，回调抛错时也会恢复
+*/
+var MapFrameBridge = class {
+	inMapFrame = false;
+	pending = null;
+	get isInMapFrame() {
+		return this.inMapFrame;
+	}
+	requestAdvance() {
+		this.pending = { kind: "advance" };
+	}
+	requestRedraw(scene, camera) {
+		if (this.pending?.kind === "advance") return;
+		this.pending = {
+			kind: "redraw",
+			draw: [scene, camera]
+		};
+	}
+	runInMapFrame(callback) {
+		const wasInMapFrame = this.inMapFrame;
+		const pending = this.pending;
+		this.pending = null;
+		this.inMapFrame = true;
+		try {
+			callback(pending);
+		} finally {
+			this.inMapFrame = wasInMapFrame;
+		}
+	}
+};
+// src/r3f-layer/use-frame-loop.ts
+/**
+* 将 R3F 的 frameloop 接入 AMap 的帧调度
+*/
+function useFrameLoop(store, frameloop, requestAdvance) {
+	useLayoutEffect(() => {
+		if (!store) return;
+		if (!store.getState().gl) return;
+		if (frameloop !== "demand") return;
+		const setState = store.setState;
+		const { invalidate } = store.getState();
+		setState({
+			frameloop,
+			invalidate: () => requestAdvance()
+		});
+		requestAdvance();
+		return () => {
+			setState({
+				frameloop: "never",
+				invalidate
+			});
+		};
+	}, [
+		frameloop,
+		requestAdvance,
+		store
+	]);
+	useLayoutEffect(() => {
+		if (!store || frameloop !== "always") return;
+		let raf = 0;
+		const tick = () => {
+			requestAdvance();
+			raf = requestAnimationFrame(tick);
+		};
+		raf = requestAnimationFrame(tick);
+		return () => cancelAnimationFrame(raf);
+	}, [
+		frameloop,
+		requestAdvance,
+		store
+	]);
+}
+// src/r3f-layer/use-r3f-layer-render.ts
+/**
+* 同步 AMap 相机，并在 AMap 帧内执行 R3F 的 advance/redraw
+*/
+function useR3FLayerRender({ frameBridge, originLngLat }) {
+	const warnedCameraMismatchRef = useRef(false);
+	return useCallback(({ canvas }, { map }, { viewMode }) => {
+		const store = _roots.get(canvas)?.store;
+		if (!store) return;
+		const state = store.getState();
+		if (!state.gl) return;
+		state.gl.resetState();
+		const result = syncMapCamera({
+			map,
+			camera: state.camera,
+			viewMode,
+			origin: originLngLat
+		});
+		if (!result.synced && !warnedCameraMismatchRef.current) {
+			warnedCameraMismatchRef.current = true;
+			logger.warn(`[R3FLayer] ${result.viewMode} view requires a ${result.expected}`);
+		}
+		try {
+			frameBridge.runInMapFrame((pending) => {
+				if (pending?.kind === "advance") state.advance(performance.now(), true);
+				else if (pending?.kind === "redraw") state.gl.render(pending.draw[0], pending.draw[1]);
+				else state.gl.render(state.scene, state.camera);
+			});
+		} finally {
+			state.gl.resetState();
+		}
+	}, [frameBridge, originLngLat]);
+}
+// src/r3f-layer/use-r3f-root-tree.tsx
+const resolveActivityBridge = React["Activity"] ? useActivityBridge : () => Fragment;
+/**
+* 来自 `@react-three/fiber` 的 `useBridge`
+* 桥接上层 Context、StrictMode 和 Activity 可见性
+* @see https://github.com/pmndrs/react-three-fiber/blob/13e5e0e152562a9cb64c31dee1d10a2af7aa39c4/packages/fiber/src/core/utils/react.tsx#L70-L95
+*/
+function useBridge() {
+	const fiber = useFiber();
+	const ContextBridge = useContextBridge();
+	const ActivityBridge = resolveActivityBridge();
+	return useMemo(() => ({ children }) => {
+		const Root = !!traverseFiber(fiber, true, (node) => node.type === StrictMode) ? StrictMode : Fragment;
+		return /* @__PURE__ */ jsx(Root, { children: /* @__PURE__ */ jsx(ActivityBridge, { children: /* @__PURE__ */ jsx(ContextBridge, { children }) }) });
+	}, [
+		fiber,
+		ContextBridge,
+		ActivityBridge
+	]);
+}
+/**
+* 将 React children 渲染到 R3F root
+*/
+function useR3FRootTree({ children, root }) {
+	const Bridge = useBridge();
+	useLayoutEffect(() => {
+		if (!root) return;
+		root.render(/* @__PURE__ */ jsx(Bridge, { children: /* @__PURE__ */ jsx(Suspense, { children }) }));
+	}, [
+		children,
+		Bridge,
+		root
+	]);
+}
+// src/r3f-layer/use-r3f-store.ts
+const DEFAULT_GL_PROPS = {
+	powerPreference: "high-performance",
+	antialias: true,
+	alpha: true
+};
+function isRenderer(value) {
+	return !!value && typeof value === "object" && "render" in value && "domElement" in value && "getContext" in value;
+}
+function isPromiseLike(value) {
+	return !!value && typeof value.then === "function";
+}
+function getRendererProps(gl) {
+	if (!gl || typeof gl === "function" || isRenderer(gl)) return void 0;
+	const { canvas: _canvas, context: _context, ...props } = gl;
+	return props;
+}
+function assertRendererUsesMapSurface(renderer, canvas, context) {
+	if (renderer.domElement !== canvas || renderer.getContext() !== context) throw new Error("[R3FLayer] the gl renderer must reuse the AMap canvas and WebGL context; use the canvas/context from the factory defaults");
+}
+function logConfigureError(error) {
+	logger.error("[R3FLayer] failed to configure the R3F root", error);
+}
+/**
+* 在 R3F 之外创建 renderer，保证 AMap 的 canvas/context 不会被用户配置覆盖。
+* 实例传给 `root.configure` 后 R3F 只释放缓存，不会 dispose renderer 或丢失上下文。
+*/
+function createRenderer(canvas, context, gl) {
+	const defaults = {
+		...DEFAULT_GL_PROPS,
+		canvas,
+		context
+	};
+	if (typeof gl === "function") {
+		const renderer = gl(defaults);
+		if (isPromiseLike(renderer)) {
+			Promise.resolve(renderer).catch(() => {});
+			throw new Error("[R3FLayer] gl factories must return a renderer synchronously; async factories are not supported");
+		}
+		if (!isRenderer(renderer)) throw new Error("[R3FLayer] gl factories must return a WebGLRenderer");
+		assertRendererUsesMapSurface(renderer, canvas, context);
+		return renderer;
+	}
+	if (isRenderer(gl)) {
+		assertRendererUsesMapSurface(gl, canvas, context);
+		return gl;
+	}
+	const params = gl ?? {};
+	return new WebGLRenderer({
+		...defaults,
+		...params,
+		canvas,
+		context
+	});
+}
+/**
+* 创建并同步 R3F root/store，同时管理尺寸监听和资源清理
+*/
+function useR3FStoreSync({ frameBridge, map, renderProps, requestAdvance, requestRedraw }) {
+	const canvasRef = useRef(null);
+	const rootEntryRef = useRef(null);
+	const renderPropsRef = useRef(renderProps);
+	const lifecycleTokenRef = useRef(0);
+	const pendingRootCreatesRef = useRef(/* @__PURE__ */ new Map());
+	const claimedCanvasRef = useRef(null);
+	const ownerTokenRef = useRef(Symbol("R3FLayer"));
+	const warnedCanvasOwnershipRef = useRef(false);
+	const [ready, setReady] = useState(null);
+	renderPropsRef.current = renderProps;
+	const flushPendingRoot = useCallback((canvas) => {
+		const create = pendingRootCreatesRef.current.get(canvas);
+		if (!create) return;
+		pendingRootCreatesRef.current.delete(canvas);
+		create();
+	}, []);
+	const disposeRoot = useCallback((entry) => {
+		lifecycleTokenRef.current++;
+		pendingRootCreatesRef.current.delete(entry.canvas);
+		releaseCanvas(entry.canvas, ownerTokenRef.current);
+		if (claimedCanvasRef.current === entry.canvas) claimedCanvasRef.current = null;
+		if (rootEntryRef.current === entry) {
+			rootEntryRef.current = null;
+			if (canvasRef.current === entry.canvas) canvasRef.current = null;
+		}
+		unmountComponentAtNode(entry.canvas, () => {
+			entry.restoreRenderer?.();
+			entry.restoreRenderer = void 0;
+			flushPendingRoot(entry.canvas);
+		});
+	}, [flushPendingRoot]);
+	const releaseRoot = useCallback((entry) => {
+		disposeRoot(entry);
+		setReady((current) => current?.root === entry.root ? null : current);
+	}, [disposeRoot]);
+	useInsertionEffect(() => {
+		return () => {
+			pendingRootCreatesRef.current.clear();
+			const entry = rootEntryRef.current;
+			if (entry) disposeRoot(entry);
+			else if (claimedCanvasRef.current) {
+				releaseCanvas(claimedCanvasRef.current, ownerTokenRef.current);
+				claimedCanvasRef.current = null;
+			}
+		};
+	}, [disposeRoot]);
+	useLayoutEffect(() => {
+		const gl = map?.getGL();
+		if (!gl) {
+			const entry = rootEntryRef.current;
+			if (entry) releaseRoot(entry);
+			return;
+		}
+		const canvas = gl.canvas;
+		const existingEntry = rootEntryRef.current;
+		if (existingEntry?.canvas === canvas) return;
+		if (existingEntry) releaseRoot(existingEntry);
+		if (!tryAcquireCanvas(canvas, ownerTokenRef.current)) {
+			if (!warnedCanvasOwnershipRef.current) {
+				warnedCanvasOwnershipRef.current = true;
+				logger.warn("[R3FLayer] only one R3FLayer can be mounted per map canvas; skipping this layer");
+			}
+			return;
+		}
+		canvasRef.current = canvas;
+		claimedCanvasRef.current = canvas;
+		const token = ++lifecycleTokenRef.current;
+		const create = () => {
+			if (lifecycleTokenRef.current !== token) return;
+			if (_roots.has(canvas)) {
+				pendingRootCreatesRef.current.set(canvas, create);
+				unmountComponentAtNode(canvas, () => flushPendingRoot(canvas));
+				return;
+			}
+			const root = createRoot(canvas);
+			const entry = {
+				canvas,
+				root
+			};
+			rootEntryRef.current = entry;
+			const configure = (renderer, rendererProps) => {
+				if (lifecycleTokenRef.current !== token) return;
+				const originalRender = renderer.render;
+				const originalAutoClear = renderer.autoClear;
+				const originalForceContextLoss = renderer.forceContextLoss;
+				entry.restoreRenderer = () => {
+					renderer.render = originalRender;
+					renderer.autoClear = originalAutoClear;
+					renderer.forceContextLoss = originalForceContextLoss;
+				};
+				renderer.autoClear = false;
+				renderer.forceContextLoss = () => {};
+				const currentRenderProps = renderPropsRef.current;
+				let configured;
+				try {
+					configured = root.configure({
+						dpr: window.devicePixelRatio,
+						events,
+						...currentRenderProps,
+						orthographic: map?.getView().type === "2D",
+						frameloop: "never",
+						gl: renderer,
+						onCreated: (state) => {
+							const draw = state.gl.render.bind(state.gl);
+							state.gl.render = (scene, camera) => {
+								if (frameBridge.isInMapFrame) {
+									draw(scene, camera);
+									return;
+								}
+								requestRedraw(scene, camera);
+							};
+							currentRenderProps.onCreated?.(state);
+						},
+						camera: {
+							aspect: canvas.clientWidth / canvas.clientHeight,
+							...currentRenderProps.camera
+						},
+						size: {
+							width: canvas.clientWidth,
+							height: canvas.clientHeight,
+							top: canvas.offsetTop,
+							left: canvas.offsetLeft,
+							...currentRenderProps.size
+						}
+					});
+				} catch (error) {
+					logConfigureError(error);
+					releaseRoot(entry);
+					return;
+				}
+				const onReady = () => {
+					if (lifecycleTokenRef.current !== token || rootEntryRef.current !== entry) return;
+					if (rendererProps) try {
+						applyProps(renderer, rendererProps);
+					} catch (error) {
+						logger.error("[R3FLayer] failed to apply gl renderer props", error);
+					}
+					const store = _roots.get(canvas)?.store;
+					if (!store) {
+						logger.error("[R3FLayer] the R3F root store is not available after configuration");
+						releaseRoot(entry);
+						return;
+					}
+					setReady({
+						root,
+						store
+					});
+				};
+				if (configured.status !== "fulfilled") {
+					logConfigureError(configured.status === "rejected" ? configured.reason : /* @__PURE__ */ new Error("[R3FLayer] R3F root configuration did not complete synchronously"));
+					releaseRoot(entry);
+					return;
+				}
+				onReady();
+			};
+			let renderer;
+			const glConfig = renderPropsRef.current.gl;
+			const rendererProps = getRendererProps(glConfig);
+			try {
+				renderer = createRenderer(canvas, gl, glConfig);
+			} catch (error) {
+				logger.error("[R3FLayer] failed to prepare the R3F renderer", error);
+				releaseRoot(entry);
+				return;
+			}
+			configure(renderer, rendererProps);
+		};
+		create();
+	}, [
+		flushPendingRoot,
+		frameBridge,
+		map,
+		releaseRoot,
+		requestRedraw
+	]);
+	useLayoutEffect(() => {
+		if (!ready) return;
+		const { store } = ready;
+		const { advance } = store.getState();
+		store.setState({ advance: (timestamp, runGlobalEffects) => {
+			if (frameBridge.isInMapFrame) {
+				advance(timestamp, runGlobalEffects);
+				return;
+			}
+			requestAdvance();
+		} });
+		return () => {
+			store.setState({ advance });
+		};
+	}, [
+		frameBridge,
+		map,
+		requestAdvance,
+		ready
+	]);
+	useLayoutEffect(() => {
+		if (!map) return;
+		if (!ready) return;
+		const canvas = canvasRef.current;
+		if (!canvas) return;
+		const { store } = ready;
+		const onResize = () => {
+			const { clientWidth, clientHeight, offsetLeft, offsetTop } = canvas;
+			const { setDpr, setSize, gl, camera } = store.getState();
+			if (map.getView().type === "3D") camera.aspect = clientWidth / clientHeight;
+			camera.updateProjectionMatrix();
+			gl.setSize(clientWidth, clientHeight);
+			setDpr(window.devicePixelRatio);
+			setSize(clientWidth, clientHeight, offsetTop, offsetLeft);
+		};
+		const ro = new ResizeObserver(onResize);
+		ro.observe(canvas);
+		return () => {
+			ro.disconnect();
+		};
+	}, [map, ready]);
+	return ready;
+}
+// src/r3f-layer/r3f-layer.tsx
+const noopInit = () => {};
+/**
+* `GLCustomLayer` 与 [`@react-three/fiber`](https://r3f.docs.pmnd.rs) 结合使用的组件（内部实现）
+*/
+const R3FLayerImpl = ({ children, frameloop = "demand", origin, ref, onComplete, map: _map, ...props }) => {
+	const map = useMapInstance(_map);
+	const [layerProps, r3fProps] = splitProps(props, [
+		"cacheSize",
+		"ce",
+		"depthTest",
+		"opacity",
+		"rejectMapMask",
+		"visible",
+		"zIndex",
+		"zooms"
+	]);
+	const originLngLat = useMemo(() => {
+		if (origin) return origin;
+		return map?.getCenter().toArray() || [0, 0];
+	}, [origin, map]);
+	const [frameBridge] = useState(() => new MapFrameBridge());
+	const requestAdvance = useCallback(() => {
+		frameBridge.requestAdvance();
+		map?.render();
+	}, [frameBridge, map]);
+	const ready = useR3FStoreSync({
+		frameBridge,
+		map,
+		renderProps: r3fProps,
+		requestAdvance,
+		requestRedraw: useCallback((scene, camera) => {
+			frameBridge.requestRedraw(scene, camera);
+			map?.render();
+		}, [frameBridge, map])
+	});
+	const root = ready?.root ?? null;
+	useFrameLoop(ready?.store ?? null, frameloop, requestAdvance);
+	const coordinateContext = useMemo(() => map ? {
+		map,
+		origin: originLngLat
+	} : null, [map, originLngLat]);
+	useR3FRootTree({
+		children: useMemo(() => coordinateContext ? /* @__PURE__ */ jsx(MapCoordinatesContext, {
+			value: coordinateContext,
+			children
+		}) : children, [children, coordinateContext]),
+		root
+	});
+	const render = useR3FLayerRender({
+		frameBridge,
+		originLngLat
+	});
+	return /* @__PURE__ */ jsx(GLCustomLayer, {
+		ref,
+		init: noopInit,
+		render,
+		onComplete,
+		...layerProps,
+		map: map ?? void 0
+	});
+};
+/**
+* `GLCustomLayer` 与 [`@react-three/fiber`](https://r3f.docs.pmnd.rs) 结合使用的组件
+* 可以直接在子组件中使用 `@react-three/fiber` 组件，无需手动处理 `GLCustomLayer` 的 `init` 和 `render`
+*/
+const R3FLayer = (props) => {
+	return /* @__PURE__ */ jsx(FiberProvider, { children: /* @__PURE__ */ jsx(R3FLayerImpl, { ...props }) });
+};
+export { GeoGroup, R3FLayer, useMapCoordinates };

package/package.json

@@ -1,6 +1,88 @@
 {
   "name": "@cn-map/gaode-react-extra",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "高德地图 react 扩展组件",
+  "keywords": [
+    "amap",
+    "react",
+    "three",
+    "高德",
+    "高德地图"
+  ],
+  "bugs": {
+    "url": "https://gtihub.com/Jungzl/amap/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jungzl/amap.git",
+    "directory": "packages/react-extra"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#lib": "./src/index.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@cn-map/gaode-extra-shared": "^0.0.1",
+    "@cn-map/gaode-shared": "^0.0.1"
+  },
+  "devDependencies": {
+    "@cn-map/gaode-react": "0.0.1",
+    "@cn-map/gaode-types": "^2.1.0",
+    "@react-three/fiber": "^9.8.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@types/three": "0.162.0",
+    "@vitejs/plugin-react": "^6.3.0",
+    "its-fine": "^2.1.1",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "three": "0.162.0",
+    "vitest-browser-react": "^2.3.0"
+  },
+  "peerDependencies": {
+    "@cn-map/gaode-react": "^0.0.1",
+    "@cn-map/gaode-types": "^2.0.0",
+    "@react-three/fiber": "^9.8.1",
+    "@types/react": "^19.2.0",
+    "@types/three": "<=0.162.0",
+    "its-fine": "^2.1.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "three": "<=0.162.0"
+  },
+  "peerDependenciesMeta": {
+    "@cn-map/gaode-types": {
+      "optional": true
+    },
+    "@types/react": {
+      "optional": true
+    },
+    "@types/three": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check:type": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run -p unit",
+    "test:e2e": "vitest run -p e2e"
+  }
 }