@scenography/plugin-focus 0.2.0

package/dist/index.cjs

@@ -0,0 +1,193 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _scenography_engine = require("@scenography/engine");
+let three = require("three");
+//#region src/easing.ts
+/**
+* Sample a CSS-style cubic-bezier easing `(p1x, p1y, p2x, p2y)` with anchors at
+* (0,0) and (1,1). Returns a function mapping linear progress `x` in `[0,1]` to
+* eased progress `y`. Used to give camera moves a smooth ease-in-out curve.
+*/
+function cubicBezier(p1x, p1y, p2x, p2y) {
+	const cx = 3 * p1x;
+	const bx = 3 * (p2x - p1x) - cx;
+	const ax = 1 - cx - bx;
+	const cy = 3 * p1y;
+	const by = 3 * (p2y - p1y) - cy;
+	const ay = 1 - cy - by;
+	const sampleX = (t) => ((ax * t + bx) * t + cx) * t;
+	const sampleY = (t) => ((ay * t + by) * t + cy) * t;
+	const slopeX = (t) => (3 * ax * t + 2 * bx) * t + cx;
+	const solveT = (x) => {
+		let t = x;
+		for (let i = 0; i < 8; i++) {
+			const dx = sampleX(t) - x;
+			if (Math.abs(dx) < 1e-5) return t;
+			const d = slopeX(t);
+			if (Math.abs(d) < 1e-6) break;
+			t -= dx / d;
+		}
+		return t;
+	};
+	return (x) => {
+		if (x <= 0) return 0;
+		if (x >= 1) return 1;
+		return sampleY(solveT(x));
+	};
+}
+/** Standard smooth ease-in-out, the default for camera framing moves. */
+const easeInOut = cubicBezier(.42, 0, .58, 1);
+//#endregion
+//#region src/CameraController.ts
+/** Max up/down framing pitch (radians) — keeps the framed view from flipping. */
+const MAX_PITCH = Math.PI / 3;
+const TAU = Math.PI * 2;
+const FIT_MARGIN = .85;
+const TAKEOVER_DISTANCE = 20;
+const TAKEOVER_YAW = Math.PI / 2;
+const shortestAngle = (delta) => (delta % TAU + TAU + Math.PI) % TAU - Math.PI;
+const clamp = (x, a, b) => Math.min(Math.max(x, a), b);
+/**
+* Drives the camera for artwork framing: it computes a target pose that fits a
+* piece into a region of the screen, then tweens there with an ease-in-out
+* curve. The eye height is read live from the free-roam controls — only XZ
+* position and rotation change. While a tween runs, free-roam input is disabled;
+* when it lands, control returns to the user and (for `focusArtwork`) the
+* controller watches for the user moving/turning away, emitting `artwork:released`.
+*/
+var CameraController = class {
+	camera;
+	getRoam;
+	resolve;
+	emit;
+	groundHeight;
+	tween = null;
+	watch = null;
+	constructor(camera, getRoam, resolve, emit, groundHeight) {
+		this.camera = camera;
+		this.getRoam = getRoam;
+		this.resolve = resolve;
+		this.emit = emit;
+		this.groundHeight = groundHeight;
+	}
+	/** True while a framing tween is in progress (e.g. to suppress click-to-select). */
+	isAnimating() {
+		return this.tween !== null;
+	}
+	focusArtwork(id, options = {}) {
+		this.start(id, options.centerX ?? .5, options.widthFraction ?? 1, options.duration ?? 900, true);
+	}
+	centerArtwork(id, options = {}) {
+		this.start(id, .5, 1, options.duration ?? 900, false);
+	}
+	release() {
+		this.watch = null;
+	}
+	start(id, centerX, widthFraction, duration, watch) {
+		const roam = this.getRoam();
+		if (!roam) return;
+		const object = this.resolve(id);
+		if (!object) return;
+		const [w, h] = object.userData.size ?? [100, 100];
+		const yaw = object.rotation.y;
+		const n = new three.Vector3(Math.sin(yaw), 0, Math.cos(yaw));
+		const center = object.position;
+		const tanV = Math.tan(this.camera.fov * Math.PI / 180 / 2);
+		const tanH = tanV * this.camera.aspect;
+		const dWidth = w / (widthFraction * 2 * tanH * FIT_MARGIN);
+		const dHeight = h / (2 * tanV * FIT_MARGIN);
+		const distance = Math.max(dWidth, dHeight);
+		const tangent = new three.Vector3(n.z, 0, -n.x);
+		const lateral = -((centerX - .5) * 2) * distance * tanH;
+		const px = center.x + n.x * distance + tangent.x * lateral;
+		const pz = center.z + n.z * distance + tangent.z * lateral;
+		const toPos = new three.Vector3(px, this.groundHeight(px, pz) + roam.getEyeHeight(), pz);
+		const f = new three.Vector3(center.x + tangent.x * lateral, center.y, center.z + tangent.z * lateral).sub(toPos).normalize();
+		const toTheta = clamp(Math.asin(clamp(f.y, -1, 1)), -MAX_PITCH, MAX_PITCH);
+		const toPhi = Math.atan2(-f.x, -f.z);
+		const from = roam.getPose();
+		roam.setEnabled(false);
+		this.watch = null;
+		this.tween = {
+			id,
+			fromPos: from.position,
+			toPos,
+			fromPhi: from.phi,
+			dPhi: shortestAngle(toPhi - from.phi),
+			fromTheta: from.theta,
+			toTheta,
+			elapsed: 0,
+			duration,
+			watch
+		};
+	}
+	/** Advance any running tween, and watch for user takeover once landed. */
+	update(deltaMs) {
+		const roam = this.getRoam();
+		const tween = this.tween;
+		if (tween) {
+			tween.elapsed += deltaMs;
+			const t = clamp(tween.elapsed / tween.duration, 0, 1);
+			const k = easeInOut(t);
+			const phi = tween.fromPhi + tween.dPhi * k;
+			const theta = tween.fromTheta + (tween.toTheta - tween.fromTheta) * k;
+			const pos = tween.fromPos.clone().lerp(tween.toPos, k);
+			roam?.setPose(pos, phi, theta);
+			this.applyPose(pos, phi, theta);
+			if (t >= 1) {
+				roam?.setEnabled(true);
+				this.watch = tween.watch ? {
+					id: tween.id,
+					pos: tween.toPos.clone(),
+					phi
+				} : null;
+				this.tween = null;
+			}
+			return;
+		}
+		if (this.watch && roam) {
+			const pose = roam.getPose();
+			const moved = Math.hypot(pose.position.x - this.watch.pos.x, pose.position.z - this.watch.pos.z);
+			const turned = Math.abs(shortestAngle(pose.phi - this.watch.phi));
+			if (moved > TAKEOVER_DISTANCE || turned > TAKEOVER_YAW) {
+				const id = this.watch.id;
+				this.watch = null;
+				this.emit("artwork:released", { id });
+			}
+		}
+	}
+	/** Write a pose straight to the camera (used while we own it during a tween). */
+	applyPose(position, phi, theta) {
+		this.camera.position.copy(position);
+		const forward = new three.Vector3(-Math.cos(theta) * Math.sin(phi), Math.sin(theta), -Math.cos(theta) * Math.cos(phi));
+		this.camera.lookAt(position.clone().add(forward));
+	}
+};
+//#endregion
+//#region src/plugin.ts
+/**
+* Camera framing — a *system* plugin. On selecting an artwork it animates the
+* camera to frame the piece (offset beside an info panel), and centers it when
+* the panel closes, handing control back to free-roam afterwards. Its api
+* surfaces as `ctx.camera`. Cooperates with the roaming camera through the
+* `roamControl` capability (suspends it during a tween); frames on the terrain
+* via `terrain`.
+*/
+const focus = () => ({
+	name: "focus",
+	setup: (ctx) => {
+		const { camera, capabilities, emit, resolve } = ctx;
+		const groundHeight = (x, z) => capabilities.get(_scenography_engine.TERRAIN)?.heightAt(x, z) ?? 0;
+		const controller = new CameraController(camera, () => capabilities.get(_scenography_engine.ROAM_CONTROL), resolve, emit, groundHeight);
+		return {
+			update: (deltaMs) => controller.update(deltaMs),
+			api: controller
+		};
+	}
+});
+//#endregion
+exports.CameraController = CameraController;
+exports.cubicBezier = cubicBezier;
+exports.easeInOut = easeInOut;
+exports.focus = focus;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["Vector3","TERRAIN","ROAM_CONTROL"],"sources":["../src/easing.ts","../src/CameraController.ts","../src/plugin.ts"],"sourcesContent":["/**\n * Sample a CSS-style cubic-bezier easing `(p1x, p1y, p2x, p2y)` with anchors at\n * (0,0) and (1,1). Returns a function mapping linear progress `x` in `[0,1]` to\n * eased progress `y`. Used to give camera moves a smooth ease-in-out curve.\n */\nexport function cubicBezier(p1x: number, p1y: number, p2x: number, p2y: number): (x: number) => number {\n  const cx = 3 * p1x;\n  const bx = 3 * (p2x - p1x) - cx;\n  const ax = 1 - cx - bx;\n  const cy = 3 * p1y;\n  const by = 3 * (p2y - p1y) - cy;\n  const ay = 1 - cy - by;\n\n  const sampleX = (t: number): number => ((ax * t + bx) * t + cx) * t;\n  const sampleY = (t: number): number => ((ay * t + by) * t + cy) * t;\n  const slopeX = (t: number): number => (3 * ax * t + 2 * bx) * t + cx;\n\n  // Solve x(t) = x for t via Newton-Raphson, then evaluate y(t).\n  const solveT = (x: number): number => {\n    let t = x;\n    for (let i = 0; i < 8; i++) {\n      const dx = sampleX(t) - x;\n      if (Math.abs(dx) < 1e-5) return t;\n      const d = slopeX(t);\n      if (Math.abs(d) < 1e-6) break;\n      t -= dx / d;\n    }\n    return t;\n  };\n\n  return (x: number): number => {\n    if (x <= 0) return 0;\n    if (x >= 1) return 1;\n    return sampleY(solveT(x));\n  };\n}\n\n/** Standard smooth ease-in-out, the default for camera framing moves. */\nexport const easeInOut = cubicBezier(0.42, 0, 0.58, 1);\n","import { Vector3, type Object3D, type PerspectiveCamera } from \"three\";\nimport type { CameraApi, FocusOptions, RoamControl } from \"@scenography/engine\";\n\nimport { easeInOut } from \"./easing\";\n\n/** Max up/down framing pitch (radians) — keeps the framed view from flipping. */\nconst MAX_PITCH = Math.PI / 3;\n\nconst TAU = Math.PI * 2;\nconst FIT_MARGIN = 0.85;\n// Thresholds past which the user is considered to have taken control back.\nconst TAKEOVER_DISTANCE = 20; // world units of XZ movement\nconst TAKEOVER_YAW = Math.PI / 2; // 90° of turn\n\nconst shortestAngle = (delta: number): number => ((((delta % TAU) + TAU + Math.PI) % TAU) - Math.PI);\nconst clamp = (x: number, a: number, b: number): number => Math.min(Math.max(x, a), b);\n\ninterface Tween {\n  id: string;\n  fromPos: Vector3;\n  toPos: Vector3;\n  fromPhi: number;\n  dPhi: number;\n  fromTheta: number;\n  toTheta: number;\n  elapsed: number;\n  duration: number;\n  /** Whether to watch for user takeover once the tween lands. */\n  watch: boolean;\n}\n\n/**\n * Drives the camera for artwork framing: it computes a target pose that fits a\n * piece into a region of the screen, then tweens there with an ease-in-out\n * curve. The eye height is read live from the free-roam controls — only XZ\n * position and rotation change. While a tween runs, free-roam input is disabled;\n * when it lands, control returns to the user and (for `focusArtwork`) the\n * controller watches for the user moving/turning away, emitting `artwork:released`.\n */\nexport class CameraController implements CameraApi {\n  private tween: Tween | null = null;\n  private watch: { id: string; pos: Vector3; phi: number } | null = null;\n\n  constructor(\n    private readonly camera: PerspectiveCamera,\n    /** The roaming camera to suspend/resume while framing — from the `roamControl` capability. */\n    private readonly getRoam: () => RoamControl | undefined,\n    private readonly resolve: (id: string) => Object3D | undefined,\n    private readonly emit: (event: string, payload?: unknown) => void,\n    /** Ground height at `(x, z)` — so framing sits on the terrain, not a fixed Y. */\n    private readonly groundHeight: (x: number, z: number) => number,\n  ) {}\n\n  /** True while a framing tween is in progress (e.g. to suppress click-to-select). */\n  isAnimating(): boolean {\n    return this.tween !== null;\n  }\n\n  focusArtwork(id: string, options: FocusOptions = {}): void {\n    this.start(id, options.centerX ?? 0.5, options.widthFraction ?? 1, options.duration ?? 900, true);\n  }\n\n  centerArtwork(id: string, options: FocusOptions = {}): void {\n    this.start(id, 0.5, 1, options.duration ?? 900, false);\n  }\n\n  release(): void {\n    this.watch = null;\n  }\n\n  private start(id: string, centerX: number, widthFraction: number, duration: number, watch: boolean): void {\n    // No roaming camera to hand off from/to: nothing to frame.\n    const roam = this.getRoam();\n    if (!roam) return;\n    const object = this.resolve(id);\n    if (!object) return;\n    const size = (object.userData.size as [number, number] | undefined) ?? [100, 100];\n    const [w, h] = size;\n\n    const yaw = object.rotation.y;\n    const n = new Vector3(Math.sin(yaw), 0, Math.cos(yaw)); // outward normal\n    const center = object.position;\n\n    const tanV = Math.tan(((this.camera.fov * Math.PI) / 180) / 2);\n    const tanH = tanV * this.camera.aspect;\n    const dWidth = w / (widthFraction * 2 * tanH * FIT_MARGIN);\n    const dHeight = h / (2 * tanV * FIT_MARGIN);\n    const distance = Math.max(dWidth, dHeight);\n\n    // Offset the camera *position* sideways (not its aim) so the view stays\n    // square-on to the wall and the piece lands at `centerX` on screen. Moving\n    // the look target instead would yaw the camera and leave it skewed.\n    const tangent = new Vector3(n.z, 0, -n.x);\n    const ndcX = (centerX - 0.5) * 2;\n    const lateral = -ndcX * distance * tanH;\n    // Eye stands a fixed height above the ground at the framing spot, so it\n    // follows the (possibly uneven) terrain instead of a fixed world Y. The eye\n    // height is read live from the controls: it may have been recalibrated\n    // after the floor's heightmap loaded.\n    const px = center.x + n.x * distance + tangent.x * lateral;\n    const pz = center.z + n.z * distance + tangent.z * lateral;\n    const toPos = new Vector3(px, this.groundHeight(px, pz) + roam.getEyeHeight(), pz);\n\n    // Aim straight ahead horizontally (perpendicular to the wall), tilting only\n    // to center the piece vertically since the eye height is locked.\n    const target = new Vector3(center.x + tangent.x * lateral, center.y, center.z + tangent.z * lateral);\n    const f = target.sub(toPos).normalize();\n    const toTheta = clamp(Math.asin(clamp(f.y, -1, 1)), -MAX_PITCH, MAX_PITCH);\n    const toPhi = Math.atan2(-f.x, -f.z);\n\n    const from = roam.getPose();\n    roam.setEnabled(false);\n    this.watch = null;\n    this.tween = {\n      id,\n      fromPos: from.position,\n      toPos,\n      fromPhi: from.phi,\n      dPhi: shortestAngle(toPhi - from.phi),\n      fromTheta: from.theta,\n      toTheta,\n      elapsed: 0,\n      duration,\n      watch,\n    };\n  }\n\n  /** Advance any running tween, and watch for user takeover once landed. */\n  update(deltaMs: number): void {\n    const roam = this.getRoam();\n    const tween = this.tween;\n    if (tween) {\n      tween.elapsed += deltaMs;\n      const t = clamp(tween.elapsed / tween.duration, 0, 1);\n      const k = easeInOut(t);\n      const phi = tween.fromPhi + tween.dPhi * k;\n      const theta = tween.fromTheta + (tween.toTheta - tween.fromTheta) * k;\n      // Y interpolates between two terrain-relative heights (start → target);\n      // don't pin it to a fixed eye height or uphill framing flies in flat.\n      const pos = tween.fromPos.clone().lerp(tween.toPos, k);\n      roam?.setPose(pos, phi, theta);\n      this.applyPose(pos, phi, theta);\n\n      if (t >= 1) {\n        roam?.setEnabled(true);\n        this.watch = tween.watch ? { id: tween.id, pos: tween.toPos.clone(), phi } : null;\n        this.tween = null;\n      }\n      return;\n    }\n\n    if (this.watch && roam) {\n      const pose = roam.getPose();\n      const moved = Math.hypot(pose.position.x - this.watch.pos.x, pose.position.z - this.watch.pos.z);\n      const turned = Math.abs(shortestAngle(pose.phi - this.watch.phi));\n      if (moved > TAKEOVER_DISTANCE || turned > TAKEOVER_YAW) {\n        const id = this.watch.id;\n        this.watch = null;\n        this.emit(\"artwork:released\", { id });\n      }\n    }\n  }\n\n  /** Write a pose straight to the camera (used while we own it during a tween). */\n  private applyPose(position: Vector3, phi: number, theta: number): void {\n    this.camera.position.copy(position);\n    const forward = new Vector3(-Math.cos(theta) * Math.sin(phi), Math.sin(theta), -Math.cos(theta) * Math.cos(phi));\n    this.camera.lookAt(position.clone().add(forward));\n  }\n}\n","import {\n  ROAM_CONTROL,\n  TERRAIN,\n  type CameraApi,\n  type RoamControl,\n  type SystemPlugin,\n  type TerrainCapability,\n} from \"@scenography/engine\";\n\nimport { CameraController } from \"./CameraController\";\n\n/**\n * Camera framing — a *system* plugin. On selecting an artwork it animates the\n * camera to frame the piece (offset beside an info panel), and centers it when\n * the panel closes, handing control back to free-roam afterwards. Its api\n * surfaces as `ctx.camera`. Cooperates with the roaming camera through the\n * `roamControl` capability (suspends it during a tween); frames on the terrain\n * via `terrain`.\n */\nexport const focus = (): SystemPlugin<CameraApi> => ({\n  name: \"focus\",\n  setup: (ctx) => {\n    const { camera, capabilities, emit, resolve } = ctx;\n    const groundHeight = (x: number, z: number): number =>\n      capabilities.get<TerrainCapability>(TERRAIN)?.heightAt(x, z) ?? 0;\n\n    const controller = new CameraController(\n      camera,\n      () => capabilities.get<RoamControl>(ROAM_CONTROL),\n      resolve,\n      emit,\n      groundHeight,\n    );\n\n    return {\n      update: (deltaMs) => controller.update(deltaMs),\n      api: controller,\n    };\n  },\n});\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,62 @@
+import { CameraApi, FocusOptions, RoamControl, SystemPlugin } from "@scenography/engine";
+import { Object3D, PerspectiveCamera } from "three";
+
+//#region src/plugin.d.ts
+/**
+ * Camera framing — a *system* plugin. On selecting an artwork it animates the
+ * camera to frame the piece (offset beside an info panel), and centers it when
+ * the panel closes, handing control back to free-roam afterwards. Its api
+ * surfaces as `ctx.camera`. Cooperates with the roaming camera through the
+ * `roamControl` capability (suspends it during a tween); frames on the terrain
+ * via `terrain`.
+ */
+declare const focus: () => SystemPlugin<CameraApi>;
+//#endregion
+//#region src/CameraController.d.ts
+/**
+ * Drives the camera for artwork framing: it computes a target pose that fits a
+ * piece into a region of the screen, then tweens there with an ease-in-out
+ * curve. The eye height is read live from the free-roam controls — only XZ
+ * position and rotation change. While a tween runs, free-roam input is disabled;
+ * when it lands, control returns to the user and (for `focusArtwork`) the
+ * controller watches for the user moving/turning away, emitting `artwork:released`.
+ */
+declare class CameraController implements CameraApi {
+  private readonly camera;
+  /** The roaming camera to suspend/resume while framing — from the `roamControl` capability. */
+  private readonly getRoam;
+  private readonly resolve;
+  private readonly emit;
+  /** Ground height at `(x, z)` — so framing sits on the terrain, not a fixed Y. */
+  private readonly groundHeight;
+  private tween;
+  private watch;
+  constructor(camera: PerspectiveCamera, /** The roaming camera to suspend/resume while framing — from the `roamControl` capability. */
+
+  getRoam: () => RoamControl | undefined, resolve: (id: string) => Object3D | undefined, emit: (event: string, payload?: unknown) => void, /** Ground height at `(x, z)` — so framing sits on the terrain, not a fixed Y. */
+
+  groundHeight: (x: number, z: number) => number);
+  /** True while a framing tween is in progress (e.g. to suppress click-to-select). */
+  isAnimating(): boolean;
+  focusArtwork(id: string, options?: FocusOptions): void;
+  centerArtwork(id: string, options?: FocusOptions): void;
+  release(): void;
+  private start;
+  /** Advance any running tween, and watch for user takeover once landed. */
+  update(deltaMs: number): void;
+  /** Write a pose straight to the camera (used while we own it during a tween). */
+  private applyPose;
+}
+//#endregion
+//#region src/easing.d.ts
+/**
+ * Sample a CSS-style cubic-bezier easing `(p1x, p1y, p2x, p2y)` with anchors at
+ * (0,0) and (1,1). Returns a function mapping linear progress `x` in `[0,1]` to
+ * eased progress `y`. Used to give camera moves a smooth ease-in-out curve.
+ */
+declare function cubicBezier(p1x: number, p1y: number, p2x: number, p2y: number): (x: number) => number;
+/** Standard smooth ease-in-out, the default for camera framing moves. */
+declare const easeInOut: (x: number) => number;
+//#endregion
+export { CameraController, cubicBezier, easeInOut, focus };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+import { CameraApi, FocusOptions, RoamControl, SystemPlugin } from "@scenography/engine";
+import { Object3D, PerspectiveCamera } from "three";
+
+//#region src/plugin.d.ts
+/**
+ * Camera framing — a *system* plugin. On selecting an artwork it animates the
+ * camera to frame the piece (offset beside an info panel), and centers it when
+ * the panel closes, handing control back to free-roam afterwards. Its api
+ * surfaces as `ctx.camera`. Cooperates with the roaming camera through the
+ * `roamControl` capability (suspends it during a tween); frames on the terrain
+ * via `terrain`.
+ */
+declare const focus: () => SystemPlugin<CameraApi>;
+//#endregion
+//#region src/CameraController.d.ts
+/**
+ * Drives the camera for artwork framing: it computes a target pose that fits a
+ * piece into a region of the screen, then tweens there with an ease-in-out
+ * curve. The eye height is read live from the free-roam controls — only XZ
+ * position and rotation change. While a tween runs, free-roam input is disabled;
+ * when it lands, control returns to the user and (for `focusArtwork`) the
+ * controller watches for the user moving/turning away, emitting `artwork:released`.
+ */
+declare class CameraController implements CameraApi {
+  private readonly camera;
+  /** The roaming camera to suspend/resume while framing — from the `roamControl` capability. */
+  private readonly getRoam;
+  private readonly resolve;
+  private readonly emit;
+  /** Ground height at `(x, z)` — so framing sits on the terrain, not a fixed Y. */
+  private readonly groundHeight;
+  private tween;
+  private watch;
+  constructor(camera: PerspectiveCamera, /** The roaming camera to suspend/resume while framing — from the `roamControl` capability. */
+
+  getRoam: () => RoamControl | undefined, resolve: (id: string) => Object3D | undefined, emit: (event: string, payload?: unknown) => void, /** Ground height at `(x, z)` — so framing sits on the terrain, not a fixed Y. */
+
+  groundHeight: (x: number, z: number) => number);
+  /** True while a framing tween is in progress (e.g. to suppress click-to-select). */
+  isAnimating(): boolean;
+  focusArtwork(id: string, options?: FocusOptions): void;
+  centerArtwork(id: string, options?: FocusOptions): void;
+  release(): void;
+  private start;
+  /** Advance any running tween, and watch for user takeover once landed. */
+  update(deltaMs: number): void;
+  /** Write a pose straight to the camera (used while we own it during a tween). */
+  private applyPose;
+}
+//#endregion
+//#region src/easing.d.ts
+/**
+ * Sample a CSS-style cubic-bezier easing `(p1x, p1y, p2x, p2y)` with anchors at
+ * (0,0) and (1,1). Returns a function mapping linear progress `x` in `[0,1]` to
+ * eased progress `y`. Used to give camera moves a smooth ease-in-out curve.
+ */
+declare function cubicBezier(p1x: number, p1y: number, p2x: number, p2y: number): (x: number) => number;
+/** Standard smooth ease-in-out, the default for camera framing moves. */
+declare const easeInOut: (x: number) => number;
+//#endregion
+export { CameraController, cubicBezier, easeInOut, focus };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,189 @@
+import { ROAM_CONTROL, TERRAIN } from "@scenography/engine";
+import { Vector3 } from "three";
+//#region src/easing.ts
+/**
+* Sample a CSS-style cubic-bezier easing `(p1x, p1y, p2x, p2y)` with anchors at
+* (0,0) and (1,1). Returns a function mapping linear progress `x` in `[0,1]` to
+* eased progress `y`. Used to give camera moves a smooth ease-in-out curve.
+*/
+function cubicBezier(p1x, p1y, p2x, p2y) {
+	const cx = 3 * p1x;
+	const bx = 3 * (p2x - p1x) - cx;
+	const ax = 1 - cx - bx;
+	const cy = 3 * p1y;
+	const by = 3 * (p2y - p1y) - cy;
+	const ay = 1 - cy - by;
+	const sampleX = (t) => ((ax * t + bx) * t + cx) * t;
+	const sampleY = (t) => ((ay * t + by) * t + cy) * t;
+	const slopeX = (t) => (3 * ax * t + 2 * bx) * t + cx;
+	const solveT = (x) => {
+		let t = x;
+		for (let i = 0; i < 8; i++) {
+			const dx = sampleX(t) - x;
+			if (Math.abs(dx) < 1e-5) return t;
+			const d = slopeX(t);
+			if (Math.abs(d) < 1e-6) break;
+			t -= dx / d;
+		}
+		return t;
+	};
+	return (x) => {
+		if (x <= 0) return 0;
+		if (x >= 1) return 1;
+		return sampleY(solveT(x));
+	};
+}
+/** Standard smooth ease-in-out, the default for camera framing moves. */
+const easeInOut = cubicBezier(.42, 0, .58, 1);
+//#endregion
+//#region src/CameraController.ts
+/** Max up/down framing pitch (radians) — keeps the framed view from flipping. */
+const MAX_PITCH = Math.PI / 3;
+const TAU = Math.PI * 2;
+const FIT_MARGIN = .85;
+const TAKEOVER_DISTANCE = 20;
+const TAKEOVER_YAW = Math.PI / 2;
+const shortestAngle = (delta) => (delta % TAU + TAU + Math.PI) % TAU - Math.PI;
+const clamp = (x, a, b) => Math.min(Math.max(x, a), b);
+/**
+* Drives the camera for artwork framing: it computes a target pose that fits a
+* piece into a region of the screen, then tweens there with an ease-in-out
+* curve. The eye height is read live from the free-roam controls — only XZ
+* position and rotation change. While a tween runs, free-roam input is disabled;
+* when it lands, control returns to the user and (for `focusArtwork`) the
+* controller watches for the user moving/turning away, emitting `artwork:released`.
+*/
+var CameraController = class {
+	camera;
+	getRoam;
+	resolve;
+	emit;
+	groundHeight;
+	tween = null;
+	watch = null;
+	constructor(camera, getRoam, resolve, emit, groundHeight) {
+		this.camera = camera;
+		this.getRoam = getRoam;
+		this.resolve = resolve;
+		this.emit = emit;
+		this.groundHeight = groundHeight;
+	}
+	/** True while a framing tween is in progress (e.g. to suppress click-to-select). */
+	isAnimating() {
+		return this.tween !== null;
+	}
+	focusArtwork(id, options = {}) {
+		this.start(id, options.centerX ?? .5, options.widthFraction ?? 1, options.duration ?? 900, true);
+	}
+	centerArtwork(id, options = {}) {
+		this.start(id, .5, 1, options.duration ?? 900, false);
+	}
+	release() {
+		this.watch = null;
+	}
+	start(id, centerX, widthFraction, duration, watch) {
+		const roam = this.getRoam();
+		if (!roam) return;
+		const object = this.resolve(id);
+		if (!object) return;
+		const [w, h] = object.userData.size ?? [100, 100];
+		const yaw = object.rotation.y;
+		const n = new Vector3(Math.sin(yaw), 0, Math.cos(yaw));
+		const center = object.position;
+		const tanV = Math.tan(this.camera.fov * Math.PI / 180 / 2);
+		const tanH = tanV * this.camera.aspect;
+		const dWidth = w / (widthFraction * 2 * tanH * FIT_MARGIN);
+		const dHeight = h / (2 * tanV * FIT_MARGIN);
+		const distance = Math.max(dWidth, dHeight);
+		const tangent = new Vector3(n.z, 0, -n.x);
+		const lateral = -((centerX - .5) * 2) * distance * tanH;
+		const px = center.x + n.x * distance + tangent.x * lateral;
+		const pz = center.z + n.z * distance + tangent.z * lateral;
+		const toPos = new Vector3(px, this.groundHeight(px, pz) + roam.getEyeHeight(), pz);
+		const f = new Vector3(center.x + tangent.x * lateral, center.y, center.z + tangent.z * lateral).sub(toPos).normalize();
+		const toTheta = clamp(Math.asin(clamp(f.y, -1, 1)), -MAX_PITCH, MAX_PITCH);
+		const toPhi = Math.atan2(-f.x, -f.z);
+		const from = roam.getPose();
+		roam.setEnabled(false);
+		this.watch = null;
+		this.tween = {
+			id,
+			fromPos: from.position,
+			toPos,
+			fromPhi: from.phi,
+			dPhi: shortestAngle(toPhi - from.phi),
+			fromTheta: from.theta,
+			toTheta,
+			elapsed: 0,
+			duration,
+			watch
+		};
+	}
+	/** Advance any running tween, and watch for user takeover once landed. */
+	update(deltaMs) {
+		const roam = this.getRoam();
+		const tween = this.tween;
+		if (tween) {
+			tween.elapsed += deltaMs;
+			const t = clamp(tween.elapsed / tween.duration, 0, 1);
+			const k = easeInOut(t);
+			const phi = tween.fromPhi + tween.dPhi * k;
+			const theta = tween.fromTheta + (tween.toTheta - tween.fromTheta) * k;
+			const pos = tween.fromPos.clone().lerp(tween.toPos, k);
+			roam?.setPose(pos, phi, theta);
+			this.applyPose(pos, phi, theta);
+			if (t >= 1) {
+				roam?.setEnabled(true);
+				this.watch = tween.watch ? {
+					id: tween.id,
+					pos: tween.toPos.clone(),
+					phi
+				} : null;
+				this.tween = null;
+			}
+			return;
+		}
+		if (this.watch && roam) {
+			const pose = roam.getPose();
+			const moved = Math.hypot(pose.position.x - this.watch.pos.x, pose.position.z - this.watch.pos.z);
+			const turned = Math.abs(shortestAngle(pose.phi - this.watch.phi));
+			if (moved > TAKEOVER_DISTANCE || turned > TAKEOVER_YAW) {
+				const id = this.watch.id;
+				this.watch = null;
+				this.emit("artwork:released", { id });
+			}
+		}
+	}
+	/** Write a pose straight to the camera (used while we own it during a tween). */
+	applyPose(position, phi, theta) {
+		this.camera.position.copy(position);
+		const forward = new Vector3(-Math.cos(theta) * Math.sin(phi), Math.sin(theta), -Math.cos(theta) * Math.cos(phi));
+		this.camera.lookAt(position.clone().add(forward));
+	}
+};
+//#endregion
+//#region src/plugin.ts
+/**
+* Camera framing — a *system* plugin. On selecting an artwork it animates the
+* camera to frame the piece (offset beside an info panel), and centers it when
+* the panel closes, handing control back to free-roam afterwards. Its api
+* surfaces as `ctx.camera`. Cooperates with the roaming camera through the
+* `roamControl` capability (suspends it during a tween); frames on the terrain
+* via `terrain`.
+*/
+const focus = () => ({
+	name: "focus",
+	setup: (ctx) => {
+		const { camera, capabilities, emit, resolve } = ctx;
+		const groundHeight = (x, z) => capabilities.get(TERRAIN)?.heightAt(x, z) ?? 0;
+		const controller = new CameraController(camera, () => capabilities.get(ROAM_CONTROL), resolve, emit, groundHeight);
+		return {
+			update: (deltaMs) => controller.update(deltaMs),
+			api: controller
+		};
+	}
+});
+//#endregion
+export { CameraController, cubicBezier, easeInOut, focus };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/easing.ts","../src/CameraController.ts","../src/plugin.ts"],"sourcesContent":["/**\n * Sample a CSS-style cubic-bezier easing `(p1x, p1y, p2x, p2y)` with anchors at\n * (0,0) and (1,1). Returns a function mapping linear progress `x` in `[0,1]` to\n * eased progress `y`. Used to give camera moves a smooth ease-in-out curve.\n */\nexport function cubicBezier(p1x: number, p1y: number, p2x: number, p2y: number): (x: number) => number {\n  const cx = 3 * p1x;\n  const bx = 3 * (p2x - p1x) - cx;\n  const ax = 1 - cx - bx;\n  const cy = 3 * p1y;\n  const by = 3 * (p2y - p1y) - cy;\n  const ay = 1 - cy - by;\n\n  const sampleX = (t: number): number => ((ax * t + bx) * t + cx) * t;\n  const sampleY = (t: number): number => ((ay * t + by) * t + cy) * t;\n  const slopeX = (t: number): number => (3 * ax * t + 2 * bx) * t + cx;\n\n  // Solve x(t) = x for t via Newton-Raphson, then evaluate y(t).\n  const solveT = (x: number): number => {\n    let t = x;\n    for (let i = 0; i < 8; i++) {\n      const dx = sampleX(t) - x;\n      if (Math.abs(dx) < 1e-5) return t;\n      const d = slopeX(t);\n      if (Math.abs(d) < 1e-6) break;\n      t -= dx / d;\n    }\n    return t;\n  };\n\n  return (x: number): number => {\n    if (x <= 0) return 0;\n    if (x >= 1) return 1;\n    return sampleY(solveT(x));\n  };\n}\n\n/** Standard smooth ease-in-out, the default for camera framing moves. */\nexport const easeInOut = cubicBezier(0.42, 0, 0.58, 1);\n","import { Vector3, type Object3D, type PerspectiveCamera } from \"three\";\nimport type { CameraApi, FocusOptions, RoamControl } from \"@scenography/engine\";\n\nimport { easeInOut } from \"./easing\";\n\n/** Max up/down framing pitch (radians) — keeps the framed view from flipping. */\nconst MAX_PITCH = Math.PI / 3;\n\nconst TAU = Math.PI * 2;\nconst FIT_MARGIN = 0.85;\n// Thresholds past which the user is considered to have taken control back.\nconst TAKEOVER_DISTANCE = 20; // world units of XZ movement\nconst TAKEOVER_YAW = Math.PI / 2; // 90° of turn\n\nconst shortestAngle = (delta: number): number => ((((delta % TAU) + TAU + Math.PI) % TAU) - Math.PI);\nconst clamp = (x: number, a: number, b: number): number => Math.min(Math.max(x, a), b);\n\ninterface Tween {\n  id: string;\n  fromPos: Vector3;\n  toPos: Vector3;\n  fromPhi: number;\n  dPhi: number;\n  fromTheta: number;\n  toTheta: number;\n  elapsed: number;\n  duration: number;\n  /** Whether to watch for user takeover once the tween lands. */\n  watch: boolean;\n}\n\n/**\n * Drives the camera for artwork framing: it computes a target pose that fits a\n * piece into a region of the screen, then tweens there with an ease-in-out\n * curve. The eye height is read live from the free-roam controls — only XZ\n * position and rotation change. While a tween runs, free-roam input is disabled;\n * when it lands, control returns to the user and (for `focusArtwork`) the\n * controller watches for the user moving/turning away, emitting `artwork:released`.\n */\nexport class CameraController implements CameraApi {\n  private tween: Tween | null = null;\n  private watch: { id: string; pos: Vector3; phi: number } | null = null;\n\n  constructor(\n    private readonly camera: PerspectiveCamera,\n    /** The roaming camera to suspend/resume while framing — from the `roamControl` capability. */\n    private readonly getRoam: () => RoamControl | undefined,\n    private readonly resolve: (id: string) => Object3D | undefined,\n    private readonly emit: (event: string, payload?: unknown) => void,\n    /** Ground height at `(x, z)` — so framing sits on the terrain, not a fixed Y. */\n    private readonly groundHeight: (x: number, z: number) => number,\n  ) {}\n\n  /** True while a framing tween is in progress (e.g. to suppress click-to-select). */\n  isAnimating(): boolean {\n    return this.tween !== null;\n  }\n\n  focusArtwork(id: string, options: FocusOptions = {}): void {\n    this.start(id, options.centerX ?? 0.5, options.widthFraction ?? 1, options.duration ?? 900, true);\n  }\n\n  centerArtwork(id: string, options: FocusOptions = {}): void {\n    this.start(id, 0.5, 1, options.duration ?? 900, false);\n  }\n\n  release(): void {\n    this.watch = null;\n  }\n\n  private start(id: string, centerX: number, widthFraction: number, duration: number, watch: boolean): void {\n    // No roaming camera to hand off from/to: nothing to frame.\n    const roam = this.getRoam();\n    if (!roam) return;\n    const object = this.resolve(id);\n    if (!object) return;\n    const size = (object.userData.size as [number, number] | undefined) ?? [100, 100];\n    const [w, h] = size;\n\n    const yaw = object.rotation.y;\n    const n = new Vector3(Math.sin(yaw), 0, Math.cos(yaw)); // outward normal\n    const center = object.position;\n\n    const tanV = Math.tan(((this.camera.fov * Math.PI) / 180) / 2);\n    const tanH = tanV * this.camera.aspect;\n    const dWidth = w / (widthFraction * 2 * tanH * FIT_MARGIN);\n    const dHeight = h / (2 * tanV * FIT_MARGIN);\n    const distance = Math.max(dWidth, dHeight);\n\n    // Offset the camera *position* sideways (not its aim) so the view stays\n    // square-on to the wall and the piece lands at `centerX` on screen. Moving\n    // the look target instead would yaw the camera and leave it skewed.\n    const tangent = new Vector3(n.z, 0, -n.x);\n    const ndcX = (centerX - 0.5) * 2;\n    const lateral = -ndcX * distance * tanH;\n    // Eye stands a fixed height above the ground at the framing spot, so it\n    // follows the (possibly uneven) terrain instead of a fixed world Y. The eye\n    // height is read live from the controls: it may have been recalibrated\n    // after the floor's heightmap loaded.\n    const px = center.x + n.x * distance + tangent.x * lateral;\n    const pz = center.z + n.z * distance + tangent.z * lateral;\n    const toPos = new Vector3(px, this.groundHeight(px, pz) + roam.getEyeHeight(), pz);\n\n    // Aim straight ahead horizontally (perpendicular to the wall), tilting only\n    // to center the piece vertically since the eye height is locked.\n    const target = new Vector3(center.x + tangent.x * lateral, center.y, center.z + tangent.z * lateral);\n    const f = target.sub(toPos).normalize();\n    const toTheta = clamp(Math.asin(clamp(f.y, -1, 1)), -MAX_PITCH, MAX_PITCH);\n    const toPhi = Math.atan2(-f.x, -f.z);\n\n    const from = roam.getPose();\n    roam.setEnabled(false);\n    this.watch = null;\n    this.tween = {\n      id,\n      fromPos: from.position,\n      toPos,\n      fromPhi: from.phi,\n      dPhi: shortestAngle(toPhi - from.phi),\n      fromTheta: from.theta,\n      toTheta,\n      elapsed: 0,\n      duration,\n      watch,\n    };\n  }\n\n  /** Advance any running tween, and watch for user takeover once landed. */\n  update(deltaMs: number): void {\n    const roam = this.getRoam();\n    const tween = this.tween;\n    if (tween) {\n      tween.elapsed += deltaMs;\n      const t = clamp(tween.elapsed / tween.duration, 0, 1);\n      const k = easeInOut(t);\n      const phi = tween.fromPhi + tween.dPhi * k;\n      const theta = tween.fromTheta + (tween.toTheta - tween.fromTheta) * k;\n      // Y interpolates between two terrain-relative heights (start → target);\n      // don't pin it to a fixed eye height or uphill framing flies in flat.\n      const pos = tween.fromPos.clone().lerp(tween.toPos, k);\n      roam?.setPose(pos, phi, theta);\n      this.applyPose(pos, phi, theta);\n\n      if (t >= 1) {\n        roam?.setEnabled(true);\n        this.watch = tween.watch ? { id: tween.id, pos: tween.toPos.clone(), phi } : null;\n        this.tween = null;\n      }\n      return;\n    }\n\n    if (this.watch && roam) {\n      const pose = roam.getPose();\n      const moved = Math.hypot(pose.position.x - this.watch.pos.x, pose.position.z - this.watch.pos.z);\n      const turned = Math.abs(shortestAngle(pose.phi - this.watch.phi));\n      if (moved > TAKEOVER_DISTANCE || turned > TAKEOVER_YAW) {\n        const id = this.watch.id;\n        this.watch = null;\n        this.emit(\"artwork:released\", { id });\n      }\n    }\n  }\n\n  /** Write a pose straight to the camera (used while we own it during a tween). */\n  private applyPose(position: Vector3, phi: number, theta: number): void {\n    this.camera.position.copy(position);\n    const forward = new Vector3(-Math.cos(theta) * Math.sin(phi), Math.sin(theta), -Math.cos(theta) * Math.cos(phi));\n    this.camera.lookAt(position.clone().add(forward));\n  }\n}\n","import {\n  ROAM_CONTROL,\n  TERRAIN,\n  type CameraApi,\n  type RoamControl,\n  type SystemPlugin,\n  type TerrainCapability,\n} from \"@scenography/engine\";\n\nimport { CameraController } from \"./CameraController\";\n\n/**\n * Camera framing — a *system* plugin. On selecting an artwork it animates the\n * camera to frame the piece (offset beside an info panel), and centers it when\n * the panel closes, handing control back to free-roam afterwards. Its api\n * surfaces as `ctx.camera`. Cooperates with the roaming camera through the\n * `roamControl` capability (suspends it during a tween); frames on the terrain\n * via `terrain`.\n */\nexport const focus = (): SystemPlugin<CameraApi> => ({\n  name: \"focus\",\n  setup: (ctx) => {\n    const { camera, capabilities, emit, resolve } = ctx;\n    const groundHeight = (x: number, z: number): number =>\n      capabilities.get<TerrainCapability>(TERRAIN)?.heightAt(x, z) ?? 0;\n\n    const controller = new CameraController(\n      camera,\n      () => capabilities.get<RoamControl>(ROAM_CONTROL),\n      resolve,\n      emit,\n      groundHeight,\n    );\n\n    return {\n      update: (deltaMs) => controller.update(deltaMs),\n      api: controller,\n    };\n  },\n});\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@scenography/plugin-focus",
+  "version": "0.2.0",
+  "description": "Focus plugin for scenography: animates the camera to frame an artwork on selection and center it when its info panel closes. A system plugin exposing ctx.camera.",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@scenography/scene": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/three": "^0.160.0",
+    "three": "^0.160.0",
+    "@scenography/engine": "0.2.0"
+  },
+  "peerDependencies": {
+    "three": ">=0.160.0",
+    "@scenography/engine": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}