@velumo/runtime 0.1.0-beta.0

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"fileNames":["../../../node_modules/typescript/lib/lib.es5.d.ts","../../../node_modules/typescript/lib/lib.es2015.d.ts","../../../node_modules/typescript/lib/lib.es2016.d.ts","../../../node_modules/typescript/lib/lib.es2017.d.ts","../../../node_modules/typescript/lib/lib.es2018.d.ts","../../../node_modules/typescript/lib/lib.es2019.d.ts","../../../node_modules/typescript/lib/lib.es2020.d.ts","../../../node_modules/typescript/lib/lib.es2021.d.ts","../../../node_modules/typescript/lib/lib.es2022.d.ts","../../../node_modules/typescript/lib/lib.dom.d.ts","../../../node_modules/typescript/lib/lib.dom.iterable.d.ts","../../../node_modules/typescript/lib/lib.dom.asynciterable.d.ts","../../../node_modules/typescript/lib/lib.webworker.importscripts.d.ts","../../../node_modules/typescript/lib/lib.scripthost.d.ts","../../../node_modules/typescript/lib/lib.es2015.core.d.ts","../../../node_modules/typescript/lib/lib.es2015.collection.d.ts","../../../node_modules/typescript/lib/lib.es2015.generator.d.ts","../../../node_modules/typescript/lib/lib.es2015.iterable.d.ts","../../../node_modules/typescript/lib/lib.es2015.promise.d.ts","../../../node_modules/typescript/lib/lib.es2015.proxy.d.ts","../../../node_modules/typescript/lib/lib.es2015.reflect.d.ts","../../../node_modules/typescript/lib/lib.es2015.symbol.d.ts","../../../node_modules/typescript/lib/lib.es2015.symbol.wellknown.d.ts","../../../node_modules/typescript/lib/lib.es2016.array.include.d.ts","../../../node_modules/typescript/lib/lib.es2016.intl.d.ts","../../../node_modules/typescript/lib/lib.es2017.arraybuffer.d.ts","../../../node_modules/typescript/lib/lib.es2017.date.d.ts","../../../node_modules/typescript/lib/lib.es2017.object.d.ts","../../../node_modules/typescript/lib/lib.es2017.sharedmemory.d.ts","../../../node_modules/typescript/lib/lib.es2017.string.d.ts","../../../node_modules/typescript/lib/lib.es2017.intl.d.ts","../../../node_modules/typescript/lib/lib.es2017.typedarrays.d.ts","../../../node_modules/typescript/lib/lib.es2018.asyncgenerator.d.ts","../../../node_modules/typescript/lib/lib.es2018.asynciterable.d.ts","../../../node_modules/typescript/lib/lib.es2018.intl.d.ts","../../../node_modules/typescript/lib/lib.es2018.promise.d.ts","../../../node_modules/typescript/lib/lib.es2018.regexp.d.ts","../../../node_modules/typescript/lib/lib.es2019.array.d.ts","../../../node_modules/typescript/lib/lib.es2019.object.d.ts","../../../node_modules/typescript/lib/lib.es2019.string.d.ts","../../../node_modules/typescript/lib/lib.es2019.symbol.d.ts","../../../node_modules/typescript/lib/lib.es2019.intl.d.ts","../../../node_modules/typescript/lib/lib.es2020.bigint.d.ts","../../../node_modules/typescript/lib/lib.es2020.date.d.ts","../../../node_modules/typescript/lib/lib.es2020.promise.d.ts","../../../node_modules/typescript/lib/lib.es2020.sharedmemory.d.ts","../../../node_modules/typescript/lib/lib.es2020.string.d.ts","../../../node_modules/typescript/lib/lib.es2020.symbol.wellknown.d.ts","../../../node_modules/typescript/lib/lib.es2020.intl.d.ts","../../../node_modules/typescript/lib/lib.es2020.number.d.ts","../../../node_modules/typescript/lib/lib.es2021.promise.d.ts","../../../node_modules/typescript/lib/lib.es2021.string.d.ts","../../../node_modules/typescript/lib/lib.es2021.weakref.d.ts","../../../node_modules/typescript/lib/lib.es2021.intl.d.ts","../../../node_modules/typescript/lib/lib.es2022.array.d.ts","../../../node_modules/typescript/lib/lib.es2022.error.d.ts","../../../node_modules/typescript/lib/lib.es2022.intl.d.ts","../../../node_modules/typescript/lib/lib.es2022.object.d.ts","../../../node_modules/typescript/lib/lib.es2022.string.d.ts","../../../node_modules/typescript/lib/lib.es2022.regexp.d.ts","../../../node_modules/typescript/lib/lib.decorators.d.ts","../../../node_modules/typescript/lib/lib.decorators.legacy.d.ts","../../../node_modules/typescript/lib/lib.es2022.full.d.ts","../../core/dist/types.d.ts","../../core/dist/builders.d.ts","../../core/dist/manifest-schema.d.ts","../../core/dist/layout-validation.d.ts","../../core/dist/capabilities.d.ts","../../core/dist/validation.d.ts","../../core/dist/index.d.ts","../src/controller.ts","../src/registry.ts","../src/action-dispatcher.ts","../src/timeline.ts","../src/camera.ts","../src/cue-dispatcher.ts","../src/hash.ts","../src/notes.ts","../src/spatial.ts","../src/scene-player.ts","../src/theme-bundle.ts","../src/index.ts"],"fileIdsList":[[64],[64,65,66,67,68,69],[70,71,72],[74],[70],[70,72,73,74],[71],[71,72,73,74,75,76,77,78,79,80,81],[70,71],[70,74,79],[70,74],[70,72]],"fileInfos":[{"version":"bcd24271a113971ba9eb71ff8cb01bc6b0f872a85c23fdbe5d93065b375933cd","affectsGlobalScope":true,"impliedFormat":1},{"version":"3f88bedbeb09c6f5a6645cb24c7c55f1aa22d19ae96c8e6959cbd8b85a707bc6","impliedFormat":1},{"version":"7fe93b39b810eadd916be8db880dd7f0f7012a5cc6ffb62de8f62a2117fa6f1f","impliedFormat":1},{"version":"bb0074cc08b84a2374af33d8bf044b80851ccc9e719a5e202eacf40db2c31600","impliedFormat":1},{"version":"1a7daebe4f45fb03d9ec53d60008fbf9ac45a697fdc89e4ce218bc94b94f94d6","impliedFormat":1},{"version":"f94b133a3cb14a288803be545ac2683e0d0ff6661bcd37e31aaaec54fc382aed","impliedFormat":1},{"version":"f59d0650799f8782fd74cf73c19223730c6d1b9198671b1c5b3a38e1188b5953","impliedFormat":1},{"version":"8a15b4607d9a499e2dbeed9ec0d3c0d7372c850b2d5f1fb259e8f6d41d468a84","impliedFormat":1},{"version":"26e0fe14baee4e127f4365d1ae0b276f400562e45e19e35fd2d4c296684715e6","impliedFormat":1},{"version":"d6b1eba8496bdd0eed6fc8a685768fe01b2da4a0388b5fe7df558290bffcf32f","affectsGlobalScope":true,"impliedFormat":1},{"version":"7f57fc4404ff020bc45b9c620aff2b40f700b95fe31164024c453a5e3c163c54","impliedFormat":1},{"version":"7f57fc4404ff020bc45b9c620aff2b40f700b95fe31164024c453a5e3c163c54","impliedFormat":1},{"version":"2a2de5b9459b3fc44decd9ce6100b72f1b002ef523126c1d3d8b2a4a63d74d78","affectsGlobalScope":true,"impliedFormat":1},{"version":"f13f4b465c99041e912db5c44129a94588e1aafee35a50eab51044833f50b4ee","affectsGlobalScope":true,"impliedFormat":1},{"version":"eadcffda2aa84802c73938e589b9e58248d74c59cb7fcbca6474e3435ac15504","affectsGlobalScope":true,"impliedFormat":1},{"version":"105ba8ff7ba746404fe1a2e189d1d3d2e0eb29a08c18dded791af02f29fb4711","affectsGlobalScope":true,"impliedFormat":1},{"version":"00343ca5b2e3d48fa5df1db6e32ea2a59afab09590274a6cccb1dbae82e60c7c","affectsGlobalScope":true,"impliedFormat":1},{"version":"ebd9f816d4002697cb2864bea1f0b70a103124e18a8cd9645eeccc09bdf80ab4","affectsGlobalScope":true,"impliedFormat":1},{"version":"2c1afac30a01772cd2a9a298a7ce7706b5892e447bb46bdbeef720f7b5da77ad","affectsGlobalScope":true,"impliedFormat":1},{"version":"7b0225f483e4fa685625ebe43dd584bb7973bbd84e66a6ba7bbe175ee1048b4f","affectsGlobalScope":true,"impliedFormat":1},{"version":"c0a4b8ac6ce74679c1da2b3795296f5896e31c38e888469a8e0f99dc3305de60","affectsGlobalScope":true,"impliedFormat":1},{"version":"3084a7b5f569088e0146533a00830e206565de65cae2239509168b11434cd84f","affectsGlobalScope":true,"impliedFormat":1},{"version":"c5079c53f0f141a0698faa903e76cb41cd664e3efb01cc17a5c46ec2eb0bef42","affectsGlobalScope":true,"impliedFormat":1},{"version":"32cafbc484dea6b0ab62cf8473182bbcb23020d70845b406f80b7526f38ae862","affectsGlobalScope":true,"impliedFormat":1},{"version":"fca4cdcb6d6c5ef18a869003d02c9f0fd95df8cfaf6eb431cd3376bc034cad36","affectsGlobalScope":true,"impliedFormat":1},{"version":"b93ec88115de9a9dc1b602291b85baf825c85666bf25985cc5f698073892b467","affectsGlobalScope":true,"impliedFormat":1},{"version":"f5c06dcc3fe849fcb297c247865a161f995cc29de7aa823afdd75aaaddc1419b","affectsGlobalScope":true,"impliedFormat":1},{"version":"b77e16112127a4b169ef0b8c3a4d730edf459c5f25fe52d5e436a6919206c4d7","affectsGlobalScope":true,"impliedFormat":1},{"version":"fbffd9337146eff822c7c00acbb78b01ea7ea23987f6c961eba689349e744f8c","affectsGlobalScope":true,"impliedFormat":1},{"version":"a995c0e49b721312f74fdfb89e4ba29bd9824c770bbb4021d74d2bf560e4c6bd","affectsGlobalScope":true,"impliedFormat":1},{"version":"c7b3542146734342e440a84b213384bfa188835537ddbda50d30766f0593aff9","affectsGlobalScope":true,"impliedFormat":1},{"version":"ce6180fa19b1cccd07ee7f7dbb9a367ac19c0ed160573e4686425060b6df7f57","affectsGlobalScope":true,"impliedFormat":1},{"version":"3f02e2476bccb9dbe21280d6090f0df17d2f66b74711489415a8aa4df73c9675","affectsGlobalScope":true,"impliedFormat":1},{"version":"45e3ab34c1c013c8ab2dc1ba4c80c780744b13b5676800ae2e3be27ae862c40c","affectsGlobalScope":true,"impliedFormat":1},{"version":"805c86f6cca8d7702a62a844856dbaa2a3fd2abef0536e65d48732441dde5b5b","affectsGlobalScope":true,"impliedFormat":1},{"version":"e42e397f1a5a77994f0185fd1466520691456c772d06bf843e5084ceb879a0ad","affectsGlobalScope":true,"impliedFormat":1},{"version":"f4c2b41f90c95b1c532ecc874bd3c111865793b23aebcc1c3cbbabcd5d76ffb0","affectsGlobalScope":true,"impliedFormat":1},{"version":"ab26191cfad5b66afa11b8bf935ef1cd88fabfcb28d30b2dfa6fad877d050332","affectsGlobalScope":true,"impliedFormat":1},{"version":"2088bc26531e38fb05eedac2951480db5309f6be3fa4a08d2221abb0f5b4200d","affectsGlobalScope":true,"impliedFormat":1},{"version":"cb9d366c425fea79716a8fb3af0d78e6b22ebbab3bd64d25063b42dc9f531c1e","affectsGlobalScope":true,"impliedFormat":1},{"version":"500934a8089c26d57ebdb688fc9757389bb6207a3c8f0674d68efa900d2abb34","affectsGlobalScope":true,"impliedFormat":1},{"version":"689da16f46e647cef0d64b0def88910e818a5877ca5379ede156ca3afb780ac3","affectsGlobalScope":true,"impliedFormat":1},{"version":"bc21cc8b6fee4f4c2440d08035b7ea3c06b3511314c8bab6bef7a92de58a2593","affectsGlobalScope":true,"impliedFormat":1},{"version":"7ca53d13d2957003abb47922a71866ba7cb2068f8d154877c596d63c359fed25","affectsGlobalScope":true,"impliedFormat":1},{"version":"54725f8c4df3d900cb4dac84b64689ce29548da0b4e9b7c2de61d41c79293611","affectsGlobalScope":true,"impliedFormat":1},{"version":"e5594bc3076ac29e6c1ebda77939bc4c8833de72f654b6e376862c0473199323","affectsGlobalScope":true,"impliedFormat":1},{"version":"2f3eb332c2d73e729f3364fcc0c2b375e72a121e8157d25a82d67a138c83a95c","affectsGlobalScope":true,"impliedFormat":1},{"version":"6f4427f9642ce8d500970e4e69d1397f64072ab73b97e476b4002a646ac743b1","affectsGlobalScope":true,"impliedFormat":1},{"version":"48915f327cd1dea4d7bd358d9dc7732f58f9e1626a29cc0c05c8c692419d9bb7","affectsGlobalScope":true,"impliedFormat":1},{"version":"b7bf9377723203b5a6a4b920164df22d56a43f593269ba6ae1fdc97774b68855","affectsGlobalScope":true,"impliedFormat":1},{"version":"db9709688f82c9e5f65a119c64d835f906efe5f559d08b11642d56eb85b79357","affectsGlobalScope":true,"impliedFormat":1},{"version":"4b25b8c874acd1a4cf8444c3617e037d444d19080ac9f634b405583fd10ce1f7","affectsGlobalScope":true,"impliedFormat":1},{"version":"37be57d7c90cf1f8112ee2636a068d8fd181289f82b744160ec56a7dc158a9f5","affectsGlobalScope":true,"impliedFormat":1},{"version":"a917a49ac94cd26b754ab84e113369a75d1a47a710661d7cd25e961cc797065f","affectsGlobalScope":true,"impliedFormat":1},{"version":"6d3261badeb7843d157ef3e6f5d1427d0eeb0af0cf9df84a62cfd29fd47ac86e","affectsGlobalScope":true,"impliedFormat":1},{"version":"195daca651dde22f2167ac0d0a05e215308119a3100f5e6268e8317d05a92526","affectsGlobalScope":true,"impliedFormat":1},{"version":"8b11e4285cd2bb164a4dc09248bdec69e9842517db4ca47c1ba913011e44ff2f","affectsGlobalScope":true,"impliedFormat":1},{"version":"0508571a52475e245b02bc50fa1394065a0a3d05277fbf5120c3784b85651799","affectsGlobalScope":true,"impliedFormat":1},{"version":"8f9af488f510c3015af3cc8c267a9e9d96c4dd38a1fdff0e11dc5a544711415b","affectsGlobalScope":true,"impliedFormat":1},{"version":"fc611fea8d30ea72c6bbfb599c9b4d393ce22e2f5bfef2172534781e7d138104","affectsGlobalScope":true,"impliedFormat":1},{"version":"1ce14b81c5cc821994aa8ec1d42b220dd41b27fcc06373bce3958af7421b77d4","affectsGlobalScope":true,"impliedFormat":1},{"version":"b3a048b3e9302ef9a34ef4ebb9aecfb28b66abb3bce577206a79fee559c230da","affectsGlobalScope":true,"impliedFormat":1},{"version":"01a30f9e8582b369075c0808df71121e6855cb06fd8d3d39511d9ebb66405205","impliedFormat":1},{"version":"8877805003603477c63696f8af86eb14be659de3027a597617e7a95ca9250a92","impliedFormat":99},{"version":"a2c4bcfeeaf83801774f8c21daf4c18b15fd9da4469e222a6708a58d235bb286","impliedFormat":99},{"version":"163a1497b249fb8ac3eac7710af6df75222a21b20434ec35d4489c85f18a397b","impliedFormat":99},{"version":"b1d091ebe44dc4eb7ba1535c76bcbf15df97a0cde19fda1bbd34e1503df10e95","impliedFormat":99},{"version":"baeb0570658dce9269d3a5dabb44a1e6e11d8712f45750ca80885fd0e2dab38e","impliedFormat":99},{"version":"def8ed8b7980dbad419047252c19812799dbf761e797d624a9a030fb318a27ee","impliedFormat":99},{"version":"09451d1bdb65b1b10cafbccc4c762f9181609881ba078e4aabfbb7c6d4effe17","impliedFormat":99},{"version":"bc15e50ef91b8488717676feb2b764cbc1568065d2d4902b64cc6e1d28112781","signature":"4c26794e2a073e20bf40b3482be4f25fa4d6b83c8d4cdb7e3744d8401eef6c38","impliedFormat":99},{"version":"2b99fff0b9b6508c7020a047eb56c8e55b89afc8bc1834741fcc1377db20ac7e","signature":"165426a72c724ac8b6c5068f64aeeedc976a31cddaf7bdb30689ca0e0e885885","impliedFormat":99},{"version":"33f683df740408b1f66efbb4cce476bf2ed8d301b6d4b6c50b0a65afac84887a","signature":"f864cf8286ef0798ae6eb2808965e2038c10ffb940b196a3a6e6364fe534115f","impliedFormat":99},{"version":"25c70402d1573c265a6a0e5c742f694bdc8dcb38900f220a25bf4eccb188944b","signature":"9c6738ae625093663883e4694a79bd8d9c8ff79f0d0bb60b8d6e4ab39393b77d","impliedFormat":99},{"version":"c4f70bdfe4e39a7f3a0204ad07f7f3b41c548669c315dcdf18d9b4215bfc938a","signature":"efbeb4d5e4df969ce57b6fe98d6cabe2097cae2e0695b6ef85c77f7a8045e9a3","impliedFormat":99},{"version":"fa451a10d5cedc04a6587af956ff13df1c224904748127b4771a6bb7fc21eaf1","signature":"d6628b767083fceffd23177e8c53e1348d372e5755c2880f8f2e958d7a6dbafc","impliedFormat":99},{"version":"a818ca32286dc35d4bc7a0415f7929d8ada785e41b1428f915f3f806bf56adc3","signature":"92692f5dcdd41d6cebb9785ebe83f6631e448d468c7e77f56c2fe6f8f32869ba","impliedFormat":99},{"version":"2f96163c2c08e570b3416314858a1f3522a52a57a460b205c642fb64279211ef","signature":"1093522585079cf706e859f4323d23832ef5b62b04805190bcba06614fc8bdcb","impliedFormat":99},{"version":"aa86e431dd4f1db079ad6545800b4a9a152d773649fc75368e0f1bacd68598ca","signature":"4bbc05996c36885d4da5e1d3b140fd16ee7121a4184843447a3bb47b240e3386","impliedFormat":99},{"version":"c0e49d332c7b517f88cea618d562a1f798580222f619479aa51bc5350192d11a","signature":"0eaeeda7b43eb04e6503115b59ea0fc0dcede7d39dc6651a1ae8ba94e5974b46","impliedFormat":99},{"version":"3e822c2174a0ebc674f1ae994f6a45541be23f10026061a9485b915e59d1d7d6","signature":"8cad53853f3c0a8f7391721d625259ba815e33c26139f59e08751fa38c326f6d","impliedFormat":99},{"version":"7200cdc5a2864de9653afbb93d0e66804d35b858d72a95c964a2f39bf6033ef3","signature":"7af78eb71c547cc0353d89ca54074af736128b01e231ab5662e1300adc0e17fd","impliedFormat":99}],"root":[[71,82]],"options":{"composite":true,"declaration":true,"declarationMap":true,"module":199,"outDir":"./","rootDir":"../src","skipLibCheck":true,"sourceMap":true,"strict":true,"target":9,"tsBuildInfoFile":"./tsconfig.tsbuildinfo"},"referencedMap":[[65,1],[68,1],[70,2],[67,1],[69,1],[73,3],[75,4],[71,5],[76,6],[77,7],[82,8],[78,9],[72,5],[80,10],[79,11],[81,12],[74,5]],"latestChangedDtsFile":"./controller.d.ts","version":"6.0.3"}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@velumo/runtime",
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@velumo/core": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}

package/src/action-dispatcher.ts

@@ -0,0 +1,81 @@
+import type { Cue, CueAction, JsonValue } from "@velumo/core";
+import type { RuntimeController } from "./controller.js";
+import type { ActionHandler } from "./registry.js";
+
+export type ActionSource = "cue" | "control";
+
+// The generalized handler context. Both the timeline cue path and the
+// imperative control (click) path build one of these. The cue-only fields
+// (cue/cueIndex/timeMs) are optional here and narrowed to required on the
+// cue path's CueDispatchEvent.
+export interface ActionContext {
+  readonly action: CueAction;
+  readonly payload: JsonValue | undefined;
+  readonly source: ActionSource;
+  // Path asymmetry (by design): `runtime` is ALWAYS set on the control path
+  // (a click, source:"control") and NEVER on the cue path (source:"cue"). The
+  // cue-only fields below (`cue`/`cueIndex`/`timeMs`) are the mirror image —
+  // present on the cue path, absent on the control path. A handler shared by
+  // both paths must guard on `source` before reading a path-specific field.
+  readonly runtime?: RuntimeController;
+  readonly target?: string;
+  readonly cue?: Cue;
+  readonly cueIndex?: number;
+  readonly timeMs?: number;
+}
+
+// Generic over the context type so BOTH paths type-check without a
+// contravariance error: the cue path uses ActionDispatcher<CueDispatchEvent>
+// (its registry yields ActionHandler<CueDispatchEvent>), the control path uses
+// the default ActionDispatcher<ActionContext>.
+export interface ActionDispatcherOptions<
+  TCtx extends ActionContext = ActionContext,
+> {
+  readonly registry: {
+    getActionHandler(type: string): ActionHandler<TCtx> | undefined;
+  };
+}
+
+// Shared lookup+invoke core for both the timeline cue path and the imperative
+// control (click) path. Returns whether a handler existed; NEVER throws for a
+// missing handler. Callers decide the missing-handler policy: the cue path
+// throws (CueDispatcher throws on false), the control path is a no-op.
+export class ActionDispatcher<TCtx extends ActionContext = ActionContext> {
+  readonly #registry: ActionDispatcherOptions<TCtx>["registry"];
+
+  constructor(options: ActionDispatcherOptions<TCtx>) {
+    this.#registry = options.registry;
+  }
+
+  dispatch(actionType: string, context: TCtx): boolean {
+    const handler = this.#registry.getActionHandler(actionType);
+    if (handler === undefined) {
+      return false;
+    }
+    handler(context);
+    return true;
+  }
+}
+
+export function createActionDispatcher<
+  TCtx extends ActionContext = ActionContext,
+>(options: ActionDispatcherOptions<TCtx>): ActionDispatcher<TCtx> {
+  return new ActionDispatcher<TCtx>(options);
+}
+
+// Convenience for the control (click) path: build the ActionContext from a
+// declared action and dispatch it, returning nothing (a missing handler is a
+// silent no-op).
+export function dispatchControlAction(
+  dispatcher: ActionDispatcher<ActionContext>,
+  action: CueAction,
+  runtime?: RuntimeController,
+): void {
+  dispatcher.dispatch(action.type, {
+    action,
+    payload: action.payload,
+    source: "control",
+    ...(runtime === undefined ? {} : { runtime }),
+    ...(action.target === undefined ? {} : { target: action.target }),
+  });
+}

package/src/camera.ts

@@ -0,0 +1,513 @@
+import { type EasingFunction, lerp } from "./timeline.js";
+
+const ERROR_PREFIX = "CameraController: ";
+
+export interface CameraVector3 {
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+}
+
+export interface CameraBounds {
+  readonly min: CameraVector3;
+  readonly max: CameraVector3;
+}
+
+export interface CameraState {
+  readonly position: CameraVector3;
+  readonly target: CameraVector3;
+  readonly zoom: number;
+  readonly bounds?: CameraBounds;
+}
+
+export interface CameraTransition {
+  readonly to: Partial<Omit<CameraState, "bounds">>;
+  readonly durationMs: number;
+  readonly easing?: EasingFunction;
+}
+
+export interface CameraKeyframe {
+  readonly state: Partial<Omit<CameraState, "bounds">>;
+  readonly atMs: number;
+  readonly easing?: EasingFunction;
+}
+
+export interface CameraPath {
+  readonly keyframes: readonly CameraKeyframe[];
+}
+
+export type CameraEventName = "camera:change";
+
+export interface CameraChangeEvent {
+  readonly type: "camera:change";
+  readonly state: CameraState;
+}
+
+export type CameraEventHandler = (event: CameraChangeEvent) => void;
+
+export interface CameraControllerOptions {
+  readonly initial?: Partial<Omit<CameraState, "bounds">>;
+  readonly bounds?: CameraBounds;
+}
+
+interface ResolvedState {
+  position: CameraVector3;
+  target: CameraVector3;
+  zoom: number;
+}
+
+interface TransitionAnimation {
+  readonly type: "transition";
+  readonly startState: ResolvedState;
+  readonly to: Partial<Omit<CameraState, "bounds">>;
+  readonly durationMs: number;
+  readonly easing: EasingFunction;
+  elapsedMs: number;
+}
+
+interface PathAnimation {
+  readonly type: "path";
+  readonly keyframes: readonly CameraKeyframe[];
+  readonly startState: ResolvedState;
+  elapsedMs: number;
+}
+
+type ActiveAnimation = TransitionAnimation | PathAnimation;
+
+function assertFinite(value: number, field: string): void {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(
+      `${ERROR_PREFIX}${field} must be a finite number; got ${String(value)}`,
+    );
+  }
+}
+
+function validateVector(value: unknown, field: string): CameraVector3 {
+  if (value === null || typeof value !== "object") {
+    throw new Error(
+      `${ERROR_PREFIX}${field} must be an object {x, y, z}; got ${String(value)}`,
+    );
+  }
+  const record = value as Record<string, unknown>;
+  for (const axis of ["x", "y", "z"] as const) {
+    const axisValue = record[axis];
+    if (typeof axisValue !== "number" || !Number.isFinite(axisValue)) {
+      throw new Error(
+        `${ERROR_PREFIX}${field}.${axis} must be a finite number; got ${String(axisValue)}`,
+      );
+    }
+  }
+  return {
+    x: record.x as number,
+    y: record.y as number,
+    z: record.z as number,
+  };
+}
+
+function validateBounds(
+  bounds: CameraBounds | undefined,
+): CameraBounds | undefined {
+  if (bounds === undefined) {
+    return undefined;
+  }
+  const min = validateVector(bounds.min, "bounds.min");
+  const max = validateVector(bounds.max, "bounds.max");
+  for (const axis of ["x", "y", "z"] as const) {
+    if (min[axis] > max[axis]) {
+      throw new Error(
+        `${ERROR_PREFIX}bounds.min.${axis} (${min[axis]}) must be <= bounds.max.${axis} (${max[axis]})`,
+      );
+    }
+  }
+  return { min, max };
+}
+
+function clampPosition(
+  position: CameraVector3,
+  bounds: CameraBounds | undefined,
+): CameraVector3 {
+  if (bounds === undefined) {
+    return position;
+  }
+  return {
+    x: Math.min(bounds.max.x, Math.max(bounds.min.x, position.x)),
+    y: Math.min(bounds.max.y, Math.max(bounds.min.y, position.y)),
+    z: Math.min(bounds.max.z, Math.max(bounds.min.z, position.z)),
+  };
+}
+
+function copyVector(value: CameraVector3): CameraVector3 {
+  return { x: value.x, y: value.y, z: value.z };
+}
+
+function copyBounds(bounds: CameraBounds): CameraBounds {
+  return { min: copyVector(bounds.min), max: copyVector(bounds.max) };
+}
+
+export class CameraController {
+  readonly #handlers = new Map<CameraEventName, Set<CameraEventHandler>>();
+  readonly #bounds: CameraBounds | undefined;
+  #position: CameraVector3;
+  #target: CameraVector3;
+  #zoom: number;
+  #animation: ActiveAnimation | undefined;
+
+  constructor(options: CameraControllerOptions = {}) {
+    this.#bounds = validateBounds(options.bounds);
+
+    const initial = options.initial ?? {};
+
+    const initialPosition =
+      initial.position !== undefined
+        ? validateVector(initial.position, "initial.position")
+        : { x: 0, y: 0, z: 0 };
+    const initialTarget =
+      initial.target !== undefined
+        ? validateVector(initial.target, "initial.target")
+        : { x: 0, y: 0, z: 0 };
+    let initialZoom = 1;
+    if (initial.zoom !== undefined) {
+      assertFinite(initial.zoom, "initial.zoom");
+      initialZoom = initial.zoom;
+    }
+
+    this.#position = clampPosition(initialPosition, this.#bounds);
+    this.#target = initialTarget;
+    this.#zoom = initialZoom;
+  }
+
+  getState(): CameraState {
+    const state: { -readonly [K in keyof CameraState]: CameraState[K] } = {
+      position: copyVector(this.#position),
+      target: copyVector(this.#target),
+      zoom: this.#zoom,
+    };
+    if (this.#bounds !== undefined) {
+      state.bounds = copyBounds(this.#bounds);
+    }
+    return state;
+  }
+
+  setState(partial: Partial<Omit<CameraState, "bounds">>): void {
+    let nextPosition = this.#position;
+    let nextTarget = this.#target;
+    let nextZoom = this.#zoom;
+
+    if (partial.position !== undefined) {
+      nextPosition = clampPosition(
+        validateVector(partial.position, "setState.position"),
+        this.#bounds,
+      );
+    }
+    if (partial.target !== undefined) {
+      nextTarget = validateVector(partial.target, "setState.target");
+    }
+    if (partial.zoom !== undefined) {
+      assertFinite(partial.zoom, "setState.zoom");
+      nextZoom = partial.zoom;
+    }
+
+    this.#position = nextPosition;
+    this.#target = nextTarget;
+    this.#zoom = nextZoom;
+    this.#emit();
+  }
+
+  transitionTo(transition: CameraTransition): void {
+    assertFinite(transition.durationMs, "transitionTo.durationMs");
+    if (transition.durationMs < 0) {
+      throw new Error(
+        `${ERROR_PREFIX}transitionTo.durationMs must be >= 0; got ${transition.durationMs}`,
+      );
+    }
+    const validatedTo: {
+      position?: CameraVector3;
+      target?: CameraVector3;
+      zoom?: number;
+    } = {};
+    if (transition.to.position !== undefined) {
+      validatedTo.position = validateVector(
+        transition.to.position,
+        "transitionTo.to.position",
+      );
+    }
+    if (transition.to.target !== undefined) {
+      validatedTo.target = validateVector(
+        transition.to.target,
+        "transitionTo.to.target",
+      );
+    }
+    if (transition.to.zoom !== undefined) {
+      assertFinite(transition.to.zoom, "transitionTo.to.zoom");
+      validatedTo.zoom = transition.to.zoom;
+    }
+
+    this.#animation = {
+      type: "transition",
+      startState: this.#snapshotResolvedState(),
+      to: validatedTo,
+      durationMs: transition.durationMs,
+      easing: transition.easing ?? linearEasing,
+      elapsedMs: 0,
+    };
+  }
+
+  playPath(path: CameraPath): void {
+    const keyframes = path.keyframes;
+    if (keyframes.length === 0) {
+      throw new Error(
+        `${ERROR_PREFIX}playPath.keyframes must contain at least one keyframe; got empty array`,
+      );
+    }
+    if (keyframes[0].atMs !== 0) {
+      throw new Error(
+        `${ERROR_PREFIX}playPath.keyframes[0].atMs must equal 0; got ${keyframes[0].atMs}`,
+      );
+    }
+    const copiedKeyframes: CameraKeyframe[] = [];
+    let prevAtMs = -Infinity;
+    for (let i = 0; i < keyframes.length; i += 1) {
+      const kf = keyframes[i];
+      assertFinite(kf.atMs, `playPath.keyframes[${i}].atMs`);
+      if (i > 0 && kf.atMs <= prevAtMs) {
+        throw new Error(
+          `${ERROR_PREFIX}playPath.keyframes[${i}].atMs (${kf.atMs}) must be strictly greater than keyframes[${i - 1}].atMs (${prevAtMs})`,
+        );
+      }
+      prevAtMs = kf.atMs;
+
+      const copiedState: {
+        position?: CameraVector3;
+        target?: CameraVector3;
+        zoom?: number;
+      } = {};
+      if (kf.state.position !== undefined) {
+        copiedState.position = validateVector(
+          kf.state.position,
+          `playPath.keyframes[${i}].state.position`,
+        );
+      }
+      if (kf.state.target !== undefined) {
+        copiedState.target = validateVector(
+          kf.state.target,
+          `playPath.keyframes[${i}].state.target`,
+        );
+      }
+      if (kf.state.zoom !== undefined) {
+        assertFinite(kf.state.zoom, `playPath.keyframes[${i}].state.zoom`);
+        copiedState.zoom = kf.state.zoom;
+      }
+
+      copiedKeyframes.push({
+        state: copiedState,
+        atMs: kf.atMs,
+        ...(kf.easing !== undefined ? { easing: kf.easing } : {}),
+      });
+    }
+
+    this.#animation = {
+      type: "path",
+      keyframes: copiedKeyframes,
+      startState: this.#snapshotResolvedState(),
+      elapsedMs: 0,
+    };
+  }
+
+  advance(deltaMs: number): void {
+    assertFinite(deltaMs, "advance.deltaMs");
+    if (deltaMs < 0) {
+      throw new Error(
+        `${ERROR_PREFIX}advance.deltaMs must be non-negative; got ${deltaMs}`,
+      );
+    }
+    if (deltaMs === 0) {
+      return;
+    }
+    if (this.#animation === undefined) {
+      return;
+    }
+
+    if (this.#animation.type === "transition") {
+      this.#advanceTransition(this.#animation, deltaMs);
+    } else {
+      this.#advancePath(this.#animation, deltaMs);
+    }
+
+    this.#emit();
+  }
+
+  on(eventName: CameraEventName, handler: CameraEventHandler): () => void {
+    let handlers = this.#handlers.get(eventName);
+    if (handlers === undefined) {
+      handlers = new Set();
+      this.#handlers.set(eventName, handlers);
+    }
+    handlers.add(handler);
+
+    let disposed = false;
+    return () => {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      handlers.delete(handler);
+    };
+  }
+
+  #snapshotResolvedState(): ResolvedState {
+    return {
+      position: copyVector(this.#position),
+      target: copyVector(this.#target),
+      zoom: this.#zoom,
+    };
+  }
+
+  #advanceTransition(anim: TransitionAnimation, deltaMs: number): void {
+    const newElapsed = anim.elapsedMs + deltaMs;
+    const rawProgress =
+      anim.durationMs === 0 ? 1 : Math.min(1, newElapsed / anim.durationMs);
+    const t = anim.easing(rawProgress);
+
+    if (anim.to.position !== undefined) {
+      const to = anim.to.position;
+      this.#position = clampPosition(
+        {
+          x: lerp(anim.startState.position.x, to.x, t),
+          y: lerp(anim.startState.position.y, to.y, t),
+          z: lerp(anim.startState.position.z, to.z, t),
+        },
+        this.#bounds,
+      );
+    }
+    if (anim.to.target !== undefined) {
+      const to = anim.to.target;
+      this.#target = {
+        x: lerp(anim.startState.target.x, to.x, t),
+        y: lerp(anim.startState.target.y, to.y, t),
+        z: lerp(anim.startState.target.z, to.z, t),
+      };
+    }
+    if (anim.to.zoom !== undefined) {
+      this.#zoom = lerp(anim.startState.zoom, anim.to.zoom, t);
+    }
+
+    if (rawProgress >= 1) {
+      this.#animation = undefined;
+    } else {
+      anim.elapsedMs = newElapsed;
+    }
+  }
+
+  #advancePath(anim: PathAnimation, deltaMs: number): void {
+    const newElapsed = anim.elapsedMs + deltaMs;
+    const keyframes = anim.keyframes;
+    const totalMs = keyframes[keyframes.length - 1].atMs;
+
+    if (newElapsed >= totalMs) {
+      const finalResolved = resolveStateAtKeyframe(
+        keyframes.length - 1,
+        anim.startState,
+        keyframes,
+      );
+      this.#position = clampPosition(finalResolved.position, this.#bounds);
+      this.#target = finalResolved.target;
+      this.#zoom = finalResolved.zoom;
+      this.#animation = undefined;
+      return;
+    }
+
+    let segIdx = 0;
+    for (let i = 0; i < keyframes.length - 1; i += 1) {
+      if (
+        keyframes[i].atMs <= newElapsed &&
+        newElapsed < keyframes[i + 1].atMs
+      ) {
+        segIdx = i;
+        break;
+      }
+    }
+
+    const segStart = keyframes[segIdx];
+    const segEnd = keyframes[segIdx + 1];
+    const segDuration = segEnd.atMs - segStart.atMs;
+    const segElapsed = newElapsed - segStart.atMs;
+    const rawProgress = segDuration === 0 ? 1 : segElapsed / segDuration;
+    const easing = segEnd.easing ?? linearEasing;
+    const t = easing(rawProgress);
+
+    const stateAtSegStart = resolveStateAtKeyframe(
+      segIdx,
+      anim.startState,
+      keyframes,
+    );
+    const stateAtSegEnd = resolveStateAtKeyframe(
+      segIdx + 1,
+      anim.startState,
+      keyframes,
+    );
+
+    this.#position = clampPosition(
+      {
+        x: lerp(stateAtSegStart.position.x, stateAtSegEnd.position.x, t),
+        y: lerp(stateAtSegStart.position.y, stateAtSegEnd.position.y, t),
+        z: lerp(stateAtSegStart.position.z, stateAtSegEnd.position.z, t),
+      },
+      this.#bounds,
+    );
+    this.#target = {
+      x: lerp(stateAtSegStart.target.x, stateAtSegEnd.target.x, t),
+      y: lerp(stateAtSegStart.target.y, stateAtSegEnd.target.y, t),
+      z: lerp(stateAtSegStart.target.z, stateAtSegEnd.target.z, t),
+    };
+    this.#zoom = lerp(stateAtSegStart.zoom, stateAtSegEnd.zoom, t);
+
+    anim.elapsedMs = newElapsed;
+  }
+
+  #emit(): void {
+    const handlers = this.#handlers.get("camera:change");
+    if (handlers === undefined) {
+      return;
+    }
+    const event: CameraChangeEvent = {
+      type: "camera:change",
+      state: this.getState(),
+    };
+    for (const handler of [...handlers]) {
+      handler(event);
+    }
+  }
+}
+
+function linearEasing(t: number): number {
+  return t;
+}
+
+function resolveStateAtKeyframe(
+  idx: number,
+  start: ResolvedState,
+  keyframes: readonly CameraKeyframe[],
+): ResolvedState {
+  let position = copyVector(start.position);
+  let target = copyVector(start.target);
+  let zoom = start.zoom;
+  for (let i = 0; i <= idx; i += 1) {
+    const kf = keyframes[i];
+    if (kf.state.position !== undefined) {
+      position = copyVector(kf.state.position);
+    }
+    if (kf.state.target !== undefined) {
+      target = copyVector(kf.state.target);
+    }
+    if (kf.state.zoom !== undefined) {
+      zoom = kf.state.zoom;
+    }
+  }
+  return { position, target, zoom };
+}
+
+export function createCameraController(
+  options?: CameraControllerOptions,
+): CameraController {
+  return new CameraController(options);
+}