@scenography/plugin-light 0.2.0

package/dist/data-CcMZWQIz.cjs

@@ -0,0 +1,41 @@
+let _scenography_scene = require("@scenography/scene");
+//#region src/data/validate.ts
+const POSITIONED = new Set([
+	"directional",
+	"point",
+	"spot"
+]);
+const LIGHT_TYPES = new Set([
+	...POSITIONED,
+	"ambient",
+	"hemisphere"
+]);
+const validateLight = (light) => (0, _scenography_scene.validate)([
+	(0, _scenography_scene.existsProp)("id", "Light is missing an id."),
+	(0, _scenography_scene.propIs)("intensity", _scenography_scene.isFiniteNumber, "intensity must be a finite number."),
+	(0, _scenography_scene.when)((l) => POSITIONED.has(l.type), (0, _scenography_scene.existsProp)("position"), (0, _scenography_scene.propIs)("position", _scenography_scene.isVec3, "position must be [x, y, z]."), (0, _scenography_scene.propIs)("target", _scenography_scene.isVec3, "target must be [x, y, z].")),
+	(0, _scenography_scene.when)((l) => !(0, _scenography_scene.isOneOf)(LIGHT_TYPES)(l.type), (0, _scenography_scene.fail)("type", "unknown light type."))
+])(light);
+//#endregion
+//#region src/data/plugin.ts
+/** The data half of the light plugin: owns the `lights` scene key (a collection). */
+const lightData = {
+	kind: "lights",
+	cardinality: "many",
+	validate: (light) => validateLight(light)
+};
+//#endregion
+Object.defineProperty(exports, "lightData", {
+	enumerable: true,
+	get: function() {
+		return lightData;
+	}
+});
+Object.defineProperty(exports, "validateLight", {
+	enumerable: true,
+	get: function() {
+		return validateLight;
+	}
+});
+
+//# sourceMappingURL=data-CcMZWQIz.cjs.map

package/dist/data-CcMZWQIz.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-CcMZWQIz.cjs","names":["isFiniteNumber","isVec3"],"sources":["../src/data/validate.ts","../src/data/plugin.ts"],"sourcesContent":["import {\n  existsProp,\n  fail,\n  isFiniteNumber,\n  isOneOf,\n  isVec3,\n  propIs,\n  validate,\n  when,\n  type ValidationResult,\n} from \"@scenography/scene\";\n\nimport type { Light } from \"./light\";\n\nconst POSITIONED: ReadonlySet<string> = new Set([\"directional\", \"point\", \"spot\"]);\nconst LIGHT_TYPES: ReadonlySet<string> = new Set([...POSITIONED, \"ambient\", \"hemisphere\"]);\n\nexport const validateLight = (light: Light): ValidationResult =>\n  validate<Light>([\n    existsProp(\"id\", \"Light is missing an id.\"),\n    propIs(\"intensity\", isFiniteNumber, \"intensity must be a finite number.\"),\n    when(\n      (l: Light) => POSITIONED.has(l.type),\n      existsProp(\"position\"),\n      propIs(\"position\", isVec3, \"position must be [x, y, z].\"),\n      propIs(\"target\", isVec3, \"target must be [x, y, z].\"),\n    ),\n    when(\n      (l: Light) => !isOneOf(LIGHT_TYPES)(l.type),\n      fail(\"type\", \"unknown light type.\"),\n    ),\n  ])(light);\n","import type { DataPlugin } from \"@scenography/scene\";\n\nimport { validateLight } from \"./validate\";\nimport type { Light } from \"./light\";\n\n/** The data half of the light plugin: owns the `lights` scene key (a collection). */\nexport const lightData: DataPlugin<Light> = {\n  kind: \"lights\",\n  cardinality: \"many\",\n  validate: (light) => validateLight(light),\n};\n"],"mappings":";;AAcA,MAAM,aAAkC,IAAI,IAAI;CAAC;CAAe;CAAS;AAAM,CAAC;AAChF,MAAM,cAAmC,IAAI,IAAI;CAAC,GAAG;CAAY;CAAW;AAAY,CAAC;AAEzF,MAAa,iBAAiB,WAAA,GAAA,mBAAA,SAAA,CACZ;oCACH,MAAM,yBAAyB;gCACnC,aAAaA,mBAAAA,gBAAgB,oCAAoC;+BAErE,MAAa,WAAW,IAAI,EAAE,IAAI,IAAA,GAAA,mBAAA,WAAA,CACxB,UAAU,IAAA,GAAA,mBAAA,OAAA,CACd,YAAYC,mBAAAA,QAAQ,6BAA6B,IAAA,GAAA,mBAAA,OAAA,CACjD,UAAUA,mBAAAA,QAAQ,2BAA2B,CACtD;+BAEG,MAAa,EAAA,GAAA,mBAAA,QAAA,CAAS,WAAW,CAAC,CAAC,EAAE,IAAI,IAAA,GAAA,mBAAA,KAAA,CACrC,QAAQ,qBAAqB,CACpC;AACF,CAAC,CAAC,CAAC,KAAK;;;;ACzBV,MAAa,YAA+B;CAC1C,MAAM;CACN,aAAa;CACb,WAAW,UAAU,cAAc,KAAK;AAC1C"}

package/dist/data-bkULec9x.mjs

@@ -0,0 +1,30 @@
+import { existsProp, fail, isFiniteNumber, isOneOf, isVec3, propIs, validate, when } from "@scenography/scene";
+//#region src/data/validate.ts
+const POSITIONED = new Set([
+	"directional",
+	"point",
+	"spot"
+]);
+const LIGHT_TYPES = new Set([
+	...POSITIONED,
+	"ambient",
+	"hemisphere"
+]);
+const validateLight = (light) => validate([
+	existsProp("id", "Light is missing an id."),
+	propIs("intensity", isFiniteNumber, "intensity must be a finite number."),
+	when((l) => POSITIONED.has(l.type), existsProp("position"), propIs("position", isVec3, "position must be [x, y, z]."), propIs("target", isVec3, "target must be [x, y, z].")),
+	when((l) => !isOneOf(LIGHT_TYPES)(l.type), fail("type", "unknown light type."))
+])(light);
+//#endregion
+//#region src/data/plugin.ts
+/** The data half of the light plugin: owns the `lights` scene key (a collection). */
+const lightData = {
+	kind: "lights",
+	cardinality: "many",
+	validate: (light) => validateLight(light)
+};
+//#endregion
+export { validateLight as n, lightData as t };
+
+//# sourceMappingURL=data-bkULec9x.mjs.map

package/dist/data-bkULec9x.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-bkULec9x.mjs","names":[],"sources":["../src/data/validate.ts","../src/data/plugin.ts"],"sourcesContent":["import {\n  existsProp,\n  fail,\n  isFiniteNumber,\n  isOneOf,\n  isVec3,\n  propIs,\n  validate,\n  when,\n  type ValidationResult,\n} from \"@scenography/scene\";\n\nimport type { Light } from \"./light\";\n\nconst POSITIONED: ReadonlySet<string> = new Set([\"directional\", \"point\", \"spot\"]);\nconst LIGHT_TYPES: ReadonlySet<string> = new Set([...POSITIONED, \"ambient\", \"hemisphere\"]);\n\nexport const validateLight = (light: Light): ValidationResult =>\n  validate<Light>([\n    existsProp(\"id\", \"Light is missing an id.\"),\n    propIs(\"intensity\", isFiniteNumber, \"intensity must be a finite number.\"),\n    when(\n      (l: Light) => POSITIONED.has(l.type),\n      existsProp(\"position\"),\n      propIs(\"position\", isVec3, \"position must be [x, y, z].\"),\n      propIs(\"target\", isVec3, \"target must be [x, y, z].\"),\n    ),\n    when(\n      (l: Light) => !isOneOf(LIGHT_TYPES)(l.type),\n      fail(\"type\", \"unknown light type.\"),\n    ),\n  ])(light);\n","import type { DataPlugin } from \"@scenography/scene\";\n\nimport { validateLight } from \"./validate\";\nimport type { Light } from \"./light\";\n\n/** The data half of the light plugin: owns the `lights` scene key (a collection). */\nexport const lightData: DataPlugin<Light> = {\n  kind: \"lights\",\n  cardinality: \"many\",\n  validate: (light) => validateLight(light),\n};\n"],"mappings":";;AAcA,MAAM,aAAkC,IAAI,IAAI;CAAC;CAAe;CAAS;AAAM,CAAC;AAChF,MAAM,cAAmC,IAAI,IAAI;CAAC,GAAG;CAAY;CAAW;AAAY,CAAC;AAEzF,MAAa,iBAAiB,UAC5B,SAAgB;CACd,WAAW,MAAM,yBAAyB;CAC1C,OAAO,aAAa,gBAAgB,oCAAoC;CACxE,MACG,MAAa,WAAW,IAAI,EAAE,IAAI,GACnC,WAAW,UAAU,GACrB,OAAO,YAAY,QAAQ,6BAA6B,GACxD,OAAO,UAAU,QAAQ,2BAA2B,CACtD;CACA,MACG,MAAa,CAAC,QAAQ,WAAW,CAAC,CAAC,EAAE,IAAI,GAC1C,KAAK,QAAQ,qBAAqB,CACpC;AACF,CAAC,CAAC,CAAC,KAAK;;;;ACzBV,MAAa,YAA+B;CAC1C,MAAM;CACN,aAAa;CACb,WAAW,UAAU,cAAc,KAAK;AAC1C"}

package/dist/data.cjs

@@ -0,0 +1,4 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_data = require("./data-CcMZWQIz.cjs");
+exports.lightData = require_data.lightData;
+exports.validateLight = require_data.validateLight;

package/dist/data.d.cts

@@ -0,0 +1,2 @@
+import { a as LightType, i as LightShadow, n as validateLight, r as Light, t as lightData } from "./index-CfFuhLoP.cjs";
+export { type Light, type LightShadow, type LightType, lightData, validateLight };

package/dist/data.d.mts

@@ -0,0 +1,2 @@
+import { a as LightType, i as LightShadow, n as validateLight, r as Light, t as lightData } from "./index-CfFuhLoP.mjs";
+export { type Light, type LightShadow, type LightType, lightData, validateLight };

package/dist/data.mjs

@@ -0,0 +1,2 @@
+import { n as validateLight, t as lightData } from "./data-bkULec9x.mjs";
+export { lightData, validateLight };

package/dist/index-CfFuhLoP.d.cts

@@ -0,0 +1,86 @@
+import { DataPlugin, ValidationResult, Vec3 } from "@scenography/scene";
+
+//#region src/data/light.d.ts
+/** Fields shared by every light variant. */
+interface LightBase {
+  id: string;
+  /** CSS-style color. Defaults to white. */
+  color?: string;
+  /** Brightness multiplier. Sensible defaults vary by `type`. */
+  intensity?: number;
+}
+/**
+ * Shadow-casting settings for a light. Only `directional`, `spot` and `point`
+ * lights can cast. `true` enables shadows with engine defaults; the object form
+ * tunes quality and the shadow camera. Runtime detail — but declared as data so
+ * the look is part of the serializable scene.
+ */
+interface LightShadow {
+  /** Shadow map resolution in px (square). Defaults to 1024. */
+  mapSize?: number;
+  /** Depth bias to fight shadow acne. Defaults to 0. */
+  bias?: number;
+  /** Normal-offset bias, softer fix for acne/peter-panning. Defaults to 0. */
+  normalBias?: number;
+  /** Near plane of the shadow camera. */
+  near?: number;
+  /** Far plane of the shadow camera. */
+  far?: number;
+  /**
+   * `directional` only: half-size of the orthographic frustum in world units —
+   * make it large enough to cover the area that should receive shadows.
+   */
+  size?: number;
+}
+/** Shorthand: `true` for defaults, or a settings object. */
+type ShadowConfig = boolean | LightShadow;
+/**
+ * A light in the scene. Extensible via `type`; covers uniform fill (`ambient`,
+ * `hemisphere`), a sun-like source (`directional`), an omni source (`point`) and
+ * a cone spotlight (`spot`). Behavior (dimming, animation) is wired by `id` in
+ * the runtime through `ctx.lights` — the definition stays pure data.
+ */
+type Light = (LightBase & {
+  type: "ambient";
+}) | (LightBase & {
+  type: "hemisphere"; /** Color bounced from below. Defaults to a dark gray. */
+  groundColor?: string;
+}) | (LightBase & {
+  type: "directional"; /** World position the parallel rays emanate from. */
+  position: Vec3; /** Point the light aims at. Defaults to the origin. */
+  target?: Vec3; /** Cast shadows from this light. */
+  shadow?: ShadowConfig;
+}) | (LightBase & {
+  type: "point"; /** World position of the source. */
+  position: Vec3; /** Range in world units; `0` (default) is infinite. */
+  distance?: number; /** Falloff exponent. Defaults to `2` (physically correct). */
+  decay?: number; /** Cast shadows from this light. */
+  shadow?: ShadowConfig;
+}) | (LightBase & {
+  type: "spot"; /** World position of the source. */
+  position: Vec3; /** Point the cone aims at. Defaults to the origin. */
+  target?: Vec3; /** Cone half-angle in radians. */
+  angle?: number; /** Soft edge, `0`..`1`. Defaults to `0`. */
+  penumbra?: number; /** Range in world units; `0` (default) is infinite. */
+  distance?: number; /** Falloff exponent. Defaults to `2`. */
+  decay?: number; /** Cast shadows from this light. */
+  shadow?: ShadowConfig;
+});
+/** The discriminant values a `Light` can take. */
+type LightType = Light["type"];
+declare module "@scenography/scene" {
+  interface Scene {
+    /** Lights in the space — provided by `@scenography/plugin-light`. */
+    lights?: Light[];
+  }
+}
+//#endregion
+//#region src/data/validate.d.ts
+declare const validateLight: (light: Light) => ValidationResult;
+//#endregion
+//#region src/data/plugin.d.ts
+/** The data half of the light plugin: owns the `lights` scene key (a collection). */
+declare const lightData: DataPlugin<Light>;
+//#endregion
+export { LightType as a, LightShadow as i, validateLight as n, Light as r, lightData as t };
+//# sourceMappingURL=index-CfFuhLoP.d.cts.map

package/dist/index-CfFuhLoP.d.mts

@@ -0,0 +1,86 @@
+import { DataPlugin, ValidationResult, Vec3 } from "@scenography/scene";
+
+//#region src/data/light.d.ts
+/** Fields shared by every light variant. */
+interface LightBase {
+  id: string;
+  /** CSS-style color. Defaults to white. */
+  color?: string;
+  /** Brightness multiplier. Sensible defaults vary by `type`. */
+  intensity?: number;
+}
+/**
+ * Shadow-casting settings for a light. Only `directional`, `spot` and `point`
+ * lights can cast. `true` enables shadows with engine defaults; the object form
+ * tunes quality and the shadow camera. Runtime detail — but declared as data so
+ * the look is part of the serializable scene.
+ */
+interface LightShadow {
+  /** Shadow map resolution in px (square). Defaults to 1024. */
+  mapSize?: number;
+  /** Depth bias to fight shadow acne. Defaults to 0. */
+  bias?: number;
+  /** Normal-offset bias, softer fix for acne/peter-panning. Defaults to 0. */
+  normalBias?: number;
+  /** Near plane of the shadow camera. */
+  near?: number;
+  /** Far plane of the shadow camera. */
+  far?: number;
+  /**
+   * `directional` only: half-size of the orthographic frustum in world units —
+   * make it large enough to cover the area that should receive shadows.
+   */
+  size?: number;
+}
+/** Shorthand: `true` for defaults, or a settings object. */
+type ShadowConfig = boolean | LightShadow;
+/**
+ * A light in the scene. Extensible via `type`; covers uniform fill (`ambient`,
+ * `hemisphere`), a sun-like source (`directional`), an omni source (`point`) and
+ * a cone spotlight (`spot`). Behavior (dimming, animation) is wired by `id` in
+ * the runtime through `ctx.lights` — the definition stays pure data.
+ */
+type Light = (LightBase & {
+  type: "ambient";
+}) | (LightBase & {
+  type: "hemisphere"; /** Color bounced from below. Defaults to a dark gray. */
+  groundColor?: string;
+}) | (LightBase & {
+  type: "directional"; /** World position the parallel rays emanate from. */
+  position: Vec3; /** Point the light aims at. Defaults to the origin. */
+  target?: Vec3; /** Cast shadows from this light. */
+  shadow?: ShadowConfig;
+}) | (LightBase & {
+  type: "point"; /** World position of the source. */
+  position: Vec3; /** Range in world units; `0` (default) is infinite. */
+  distance?: number; /** Falloff exponent. Defaults to `2` (physically correct). */
+  decay?: number; /** Cast shadows from this light. */
+  shadow?: ShadowConfig;
+}) | (LightBase & {
+  type: "spot"; /** World position of the source. */
+  position: Vec3; /** Point the cone aims at. Defaults to the origin. */
+  target?: Vec3; /** Cone half-angle in radians. */
+  angle?: number; /** Soft edge, `0`..`1`. Defaults to `0`. */
+  penumbra?: number; /** Range in world units; `0` (default) is infinite. */
+  distance?: number; /** Falloff exponent. Defaults to `2`. */
+  decay?: number; /** Cast shadows from this light. */
+  shadow?: ShadowConfig;
+});
+/** The discriminant values a `Light` can take. */
+type LightType = Light["type"];
+declare module "@scenography/scene" {
+  interface Scene {
+    /** Lights in the space — provided by `@scenography/plugin-light`. */
+    lights?: Light[];
+  }
+}
+//#endregion
+//#region src/data/validate.d.ts
+declare const validateLight: (light: Light) => ValidationResult;
+//#endregion
+//#region src/data/plugin.d.ts
+/** The data half of the light plugin: owns the `lights` scene key (a collection). */
+declare const lightData: DataPlugin<Light>;
+//#endregion
+export { LightType as a, LightShadow as i, validateLight as n, Light as r, lightData as t };
+//# sourceMappingURL=index-CfFuhLoP.d.mts.map

package/dist/index.cjs

@@ -0,0 +1,177 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_data = require("./data-CcMZWQIz.cjs");
+let three = require("three");
+//#region src/buildLight.ts
+const DEFAULT_COLOR = "#ffffff";
+const DEFAULT_SHADOW_MAP = 1024;
+/** Enable and configure shadow casting on a light from its `shadow` data. */
+const applyShadow = (light, config) => {
+	light.castShadow = true;
+	const s = typeof config === "object" ? config : {};
+	light.shadow.mapSize.setScalar(s.mapSize ?? DEFAULT_SHADOW_MAP);
+	if (s.bias !== void 0) light.shadow.bias = s.bias;
+	if (s.normalBias !== void 0) light.shadow.normalBias = s.normalBias;
+	const cam = light.shadow.camera;
+	if (s.near !== void 0) cam.near = s.near;
+	if (s.far !== void 0) cam.far = s.far;
+	if (cam instanceof three.OrthographicCamera && s.size !== void 0) {
+		cam.left = -s.size;
+		cam.right = s.size;
+		cam.top = s.size;
+		cam.bottom = -s.size;
+	}
+	cam.updateProjectionMatrix();
+};
+/**
+* Build the three.js object for a `Light`. Returns a `Group` (even for a single
+* light) so directional/spot lights can carry their `target` in the same node,
+* and so every light is addressed uniformly by `id` for reconciliation.
+*/
+function buildLight(light) {
+	const color = light.color ?? DEFAULT_COLOR;
+	const group = new three.Group();
+	switch (light.type) {
+		case "ambient":
+			group.add(new three.AmbientLight(color, light.intensity ?? 1.4));
+			break;
+		case "hemisphere":
+			group.add(new three.HemisphereLight(color, light.groundColor ?? "#444444", light.intensity ?? 1));
+			break;
+		case "directional": {
+			const l = new three.DirectionalLight(color, light.intensity ?? 1);
+			l.position.set(...light.position);
+			l.target.position.set(...light.target ?? [
+				0,
+				0,
+				0
+			]);
+			if (light.shadow) applyShadow(l, light.shadow);
+			group.add(l, l.target);
+			break;
+		}
+		case "point": {
+			const l = new three.PointLight(color, light.intensity ?? 1, light.distance ?? 0, light.decay ?? 2);
+			l.position.set(...light.position);
+			if (light.shadow) applyShadow(l, light.shadow);
+			group.add(l);
+			break;
+		}
+		case "spot": {
+			const l = new three.SpotLight(color, light.intensity ?? 1, light.distance ?? 0, light.angle ?? Math.PI / 6, light.penumbra ?? 0, light.decay ?? 2);
+			l.position.set(...light.position);
+			l.target.position.set(...light.target ?? [
+				0,
+				0,
+				0
+			]);
+			if (light.shadow) applyShadow(l, light.shadow);
+			group.add(l, l.target);
+			break;
+		}
+	}
+	group.name = `light:${light.id}`;
+	group.userData.scenographyId = light.id;
+	return group;
+}
+//#endregion
+//#region src/LightController.ts
+const isThreeLight = (o) => o.isLight === true;
+/**
+* High-level light control surfaced as `ctx.lights`. Works over the live light
+* objects (queried fresh each call so it keeps working across hot-swaps),
+* tweening intensity in the render loop.
+*/
+var LightController = class {
+	getLights;
+	tweens = /* @__PURE__ */ new Map();
+	/** Intensity captured before a dim, so `restore` can bring it back. */
+	baseline = /* @__PURE__ */ new WeakMap();
+	constructor(getLights) {
+		this.getLights = getLights;
+	}
+	lightsOf(group) {
+		const found = [];
+		group.traverse((o) => {
+			if (isThreeLight(o)) found.push(o);
+		});
+		return found;
+	}
+	all() {
+		return [...this.getLights().values()].flatMap((g) => this.lightsOf(g));
+	}
+	fade(light, to, duration) {
+		if (!duration || duration <= 0) {
+			this.tweens.delete(light);
+			light.intensity = to;
+			return;
+		}
+		this.tweens.set(light, {
+			from: light.intensity,
+			to,
+			elapsed: 0,
+			duration
+		});
+	}
+	/** Set intensity and/or color of every light under `id`. */
+	set(id, props, opts = {}) {
+		const group = this.getLights().get(id);
+		if (!group) return;
+		for (const light of this.lightsOf(group)) {
+			if (props.color !== void 0) light.color.set(props.color);
+			if (props.intensity !== void 0) this.fade(light, props.intensity, opts.duration ?? 0);
+		}
+	}
+	/** Fade every light toward `factor` of its current intensity (default off). */
+	dimAll(opts = {}) {
+		const factor = opts.factor ?? 0;
+		for (const light of this.all()) {
+			const base = this.baseline.get(light) ?? light.intensity;
+			this.baseline.set(light, base);
+			this.fade(light, base * factor, opts.duration ?? 0);
+		}
+	}
+	/** Fade every light back to the intensity captured before the last dim. */
+	restore(opts = {}) {
+		for (const light of this.all()) {
+			const base = this.baseline.get(light);
+			if (base === void 0) continue;
+			this.fade(light, base, opts.duration ?? 0);
+			this.baseline.delete(light);
+		}
+	}
+	/** Advance active fades. Called once per frame with the frame delta in ms. */
+	update(deltaMs) {
+		for (const [light, t] of this.tweens) {
+			t.elapsed += deltaMs;
+			const k = t.duration > 0 ? Math.min(t.elapsed / t.duration, 1) : 1;
+			light.intensity = t.from + (t.to - t.from) * k;
+			if (k >= 1) this.tweens.delete(light);
+		}
+	}
+};
+//#endregion
+//#region src/plugin.ts
+/**
+* The light plugin: builds each `Light` (ambient/hemisphere/directional/point/
+* spot, with shadows) and exposes `ctx.lights` — a controller that dims/sets
+* intensity and color over the live lights, tweening in the render loop.
+*/
+const light = () => ({
+	data: require_data.lightData,
+	build: (definition) => ({ object: buildLight(definition) }),
+	controller: (elements) => {
+		const controller = new LightController(elements);
+		return {
+			api: controller,
+			update: (deltaMs) => controller.update(deltaMs)
+		};
+	}
+});
+//#endregion
+exports.LightController = LightController;
+exports.buildLight = buildLight;
+exports.light = light;
+exports.lightData = require_data.lightData;
+exports.validateLight = require_data.validateLight;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["OrthographicCamera","Group","AmbientLight","HemisphereLight","DirectionalLight","PointLight","SpotLight","lightData"],"sources":["../src/buildLight.ts","../src/LightController.ts","../src/plugin.ts"],"sourcesContent":["import {\n  AmbientLight,\n  DirectionalLight,\n  Group,\n  HemisphereLight,\n  OrthographicCamera,\n  PointLight,\n  SpotLight,\n  type Object3D,\n} from \"three\";\nimport type { Light, LightShadow } from \"./data\";\n\nconst DEFAULT_COLOR = \"#ffffff\";\nconst DEFAULT_SHADOW_MAP = 1024;\n\n/** Enable and configure shadow casting on a light from its `shadow` data. */\nconst applyShadow = (\n  light: DirectionalLight | SpotLight | PointLight,\n  config: boolean | LightShadow,\n): void => {\n  light.castShadow = true;\n  const s: LightShadow = typeof config === \"object\" ? config : {};\n  light.shadow.mapSize.setScalar(s.mapSize ?? DEFAULT_SHADOW_MAP);\n  if (s.bias !== undefined) light.shadow.bias = s.bias;\n  if (s.normalBias !== undefined) light.shadow.normalBias = s.normalBias;\n\n  const cam = light.shadow.camera;\n  if (s.near !== undefined) cam.near = s.near;\n  if (s.far !== undefined) cam.far = s.far;\n  // Directional lights use an orthographic frustum; size it to the lit area.\n  if (cam instanceof OrthographicCamera && s.size !== undefined) {\n    cam.left = -s.size;\n    cam.right = s.size;\n    cam.top = s.size;\n    cam.bottom = -s.size;\n  }\n  cam.updateProjectionMatrix();\n};\n\n/**\n * Build the three.js object for a `Light`. Returns a `Group` (even for a single\n * light) so directional/spot lights can carry their `target` in the same node,\n * and so every light is addressed uniformly by `id` for reconciliation.\n */\nexport function buildLight(light: Light): Object3D {\n  const color = light.color ?? DEFAULT_COLOR;\n  const group = new Group();\n\n  switch (light.type) {\n    case \"ambient\":\n      group.add(new AmbientLight(color, light.intensity ?? 1.4));\n      break;\n    case \"hemisphere\":\n      group.add(\n        new HemisphereLight(color, light.groundColor ?? \"#444444\", light.intensity ?? 1),\n      );\n      break;\n    case \"directional\": {\n      const l = new DirectionalLight(color, light.intensity ?? 1);\n      l.position.set(...light.position);\n      l.target.position.set(...(light.target ?? [0, 0, 0]));\n      if (light.shadow) applyShadow(l, light.shadow);\n      group.add(l, l.target);\n      break;\n    }\n    case \"point\": {\n      const l = new PointLight(color, light.intensity ?? 1, light.distance ?? 0, light.decay ?? 2);\n      l.position.set(...light.position);\n      if (light.shadow) applyShadow(l, light.shadow);\n      group.add(l);\n      break;\n    }\n    case \"spot\": {\n      const l = new SpotLight(\n        color,\n        light.intensity ?? 1,\n        light.distance ?? 0,\n        light.angle ?? Math.PI / 6,\n        light.penumbra ?? 0,\n        light.decay ?? 2,\n      );\n      l.position.set(...light.position);\n      l.target.position.set(...(light.target ?? [0, 0, 0]));\n      if (light.shadow) applyShadow(l, light.shadow);\n      group.add(l, l.target);\n      break;\n    }\n  }\n\n  group.name = `light:${light.id}`;\n  group.userData.scenographyId = light.id;\n  return group;\n}\n","import type { LightSet, LightSetOptions, LightsApi } from \"@scenography/engine\";\nimport type { Color, Light as ThreeLight, Object3D } from \"three\";\n\ninterface Tween {\n  from: number;\n  to: number;\n  elapsed: number;\n  duration: number;\n}\n\nconst isThreeLight = (o: Object3D): o is ThreeLight => (o as ThreeLight).isLight === true;\n\n/**\n * High-level light control surfaced as `ctx.lights`. Works over the live light\n * objects (queried fresh each call so it keeps working across hot-swaps),\n * tweening intensity in the render loop.\n */\nexport class LightController implements LightsApi {\n  private readonly getLights: () => ReadonlyMap<string, Object3D>;\n  private readonly tweens = new Map<ThreeLight, Tween>();\n  /** Intensity captured before a dim, so `restore` can bring it back. */\n  private readonly baseline = new WeakMap<ThreeLight, number>();\n\n  constructor(getLights: () => ReadonlyMap<string, Object3D>) {\n    this.getLights = getLights;\n  }\n\n  private lightsOf(group: Object3D): ThreeLight[] {\n    const found: ThreeLight[] = [];\n    group.traverse((o) => {\n      if (isThreeLight(o)) found.push(o);\n    });\n    return found;\n  }\n\n  private all(): ThreeLight[] {\n    return [...this.getLights().values()].flatMap((g) => this.lightsOf(g));\n  }\n\n  private fade(light: ThreeLight, to: number, duration: number): void {\n    if (!duration || duration <= 0) {\n      this.tweens.delete(light);\n      light.intensity = to;\n      return;\n    }\n    this.tweens.set(light, { from: light.intensity, to, elapsed: 0, duration });\n  }\n\n  /** Set intensity and/or color of every light under `id`. */\n  set(id: string, props: LightSet, opts: LightSetOptions = {}): void {\n    const group = this.getLights().get(id);\n    if (!group) return;\n    for (const light of this.lightsOf(group)) {\n      if (props.color !== undefined) (light.color as Color).set(props.color);\n      if (props.intensity !== undefined) this.fade(light, props.intensity, opts.duration ?? 0);\n    }\n  }\n\n  /** Fade every light toward `factor` of its current intensity (default off). */\n  dimAll(opts: LightSetOptions & { factor?: number } = {}): void {\n    const factor = opts.factor ?? 0;\n    for (const light of this.all()) {\n      const base = this.baseline.get(light) ?? light.intensity;\n      this.baseline.set(light, base);\n      this.fade(light, base * factor, opts.duration ?? 0);\n    }\n  }\n\n  /** Fade every light back to the intensity captured before the last dim. */\n  restore(opts: LightSetOptions = {}): void {\n    for (const light of this.all()) {\n      const base = this.baseline.get(light);\n      if (base === undefined) continue;\n      this.fade(light, base, opts.duration ?? 0);\n      this.baseline.delete(light);\n    }\n  }\n\n  /** Advance active fades. Called once per frame with the frame delta in ms. */\n  update(deltaMs: number): void {\n    for (const [light, t] of this.tweens) {\n      t.elapsed += deltaMs;\n      const k = t.duration > 0 ? Math.min(t.elapsed / t.duration, 1) : 1;\n      light.intensity = t.from + (t.to - t.from) * k;\n      if (k >= 1) this.tweens.delete(light);\n    }\n  }\n}\n","import type { EnginePlugin } from \"@scenography/engine\";\n\nimport { buildLight } from \"./buildLight\";\nimport { LightController } from \"./LightController\";\nimport { lightData, type Light } from \"./data\";\n\n/**\n * The light plugin: builds each `Light` (ambient/hemisphere/directional/point/\n * spot, with shadows) and exposes `ctx.lights` — a controller that dims/sets\n * intensity and color over the live lights, tweening in the render loop.\n */\nexport const light = (): EnginePlugin<Light> => ({\n  data: lightData,\n  build: (definition) => ({ object: buildLight(definition) }),\n  controller: (elements) => {\n    const controller = new LightController(elements);\n    return { api: controller, update: (deltaMs) => controller.update(deltaMs) };\n  },\n});\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,49 @@
+import { a as LightType, i as LightShadow, n as validateLight, r as Light, t as lightData } from "./index-CfFuhLoP.cjs";
+import { EnginePlugin, LightSet, LightSetOptions, LightsApi } from "@scenography/engine";
+import { Object3D } from "three";
+
+//#region src/plugin.d.ts
+/**
+ * The light plugin: builds each `Light` (ambient/hemisphere/directional/point/
+ * spot, with shadows) and exposes `ctx.lights` — a controller that dims/sets
+ * intensity and color over the live lights, tweening in the render loop.
+ */
+declare const light: () => EnginePlugin<Light>;
+//#endregion
+//#region src/buildLight.d.ts
+/**
+ * Build the three.js object for a `Light`. Returns a `Group` (even for a single
+ * light) so directional/spot lights can carry their `target` in the same node,
+ * and so every light is addressed uniformly by `id` for reconciliation.
+ */
+declare function buildLight(light: Light): Object3D;
+//#endregion
+//#region src/LightController.d.ts
+/**
+ * High-level light control surfaced as `ctx.lights`. Works over the live light
+ * objects (queried fresh each call so it keeps working across hot-swaps),
+ * tweening intensity in the render loop.
+ */
+declare class LightController implements LightsApi {
+  private readonly getLights;
+  private readonly tweens;
+  /** Intensity captured before a dim, so `restore` can bring it back. */
+  private readonly baseline;
+  constructor(getLights: () => ReadonlyMap<string, Object3D>);
+  private lightsOf;
+  private all;
+  private fade;
+  /** Set intensity and/or color of every light under `id`. */
+  set(id: string, props: LightSet, opts?: LightSetOptions): void;
+  /** Fade every light toward `factor` of its current intensity (default off). */
+  dimAll(opts?: LightSetOptions & {
+    factor?: number;
+  }): void;
+  /** Fade every light back to the intensity captured before the last dim. */
+  restore(opts?: LightSetOptions): void;
+  /** Advance active fades. Called once per frame with the frame delta in ms. */
+  update(deltaMs: number): void;
+}
+//#endregion
+export { type Light, LightController, type LightShadow, type LightType, buildLight, light, lightData, validateLight };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,49 @@
+import { a as LightType, i as LightShadow, n as validateLight, r as Light, t as lightData } from "./index-CfFuhLoP.mjs";
+import { Object3D } from "three";
+import { EnginePlugin, LightSet, LightSetOptions, LightsApi } from "@scenography/engine";
+
+//#region src/plugin.d.ts
+/**
+ * The light plugin: builds each `Light` (ambient/hemisphere/directional/point/
+ * spot, with shadows) and exposes `ctx.lights` — a controller that dims/sets
+ * intensity and color over the live lights, tweening in the render loop.
+ */
+declare const light: () => EnginePlugin<Light>;
+//#endregion
+//#region src/buildLight.d.ts
+/**
+ * Build the three.js object for a `Light`. Returns a `Group` (even for a single
+ * light) so directional/spot lights can carry their `target` in the same node,
+ * and so every light is addressed uniformly by `id` for reconciliation.
+ */
+declare function buildLight(light: Light): Object3D;
+//#endregion
+//#region src/LightController.d.ts
+/**
+ * High-level light control surfaced as `ctx.lights`. Works over the live light
+ * objects (queried fresh each call so it keeps working across hot-swaps),
+ * tweening intensity in the render loop.
+ */
+declare class LightController implements LightsApi {
+  private readonly getLights;
+  private readonly tweens;
+  /** Intensity captured before a dim, so `restore` can bring it back. */
+  private readonly baseline;
+  constructor(getLights: () => ReadonlyMap<string, Object3D>);
+  private lightsOf;
+  private all;
+  private fade;
+  /** Set intensity and/or color of every light under `id`. */
+  set(id: string, props: LightSet, opts?: LightSetOptions): void;
+  /** Fade every light toward `factor` of its current intensity (default off). */
+  dimAll(opts?: LightSetOptions & {
+    factor?: number;
+  }): void;
+  /** Fade every light back to the intensity captured before the last dim. */
+  restore(opts?: LightSetOptions): void;
+  /** Advance active fades. Called once per frame with the frame delta in ms. */
+  update(deltaMs: number): void;
+}
+//#endregion
+export { type Light, LightController, type LightShadow, type LightType, buildLight, light, lightData, validateLight };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,172 @@
+import { n as validateLight, t as lightData } from "./data-bkULec9x.mjs";
+import { AmbientLight, DirectionalLight, Group, HemisphereLight, OrthographicCamera, PointLight, SpotLight } from "three";
+//#region src/buildLight.ts
+const DEFAULT_COLOR = "#ffffff";
+const DEFAULT_SHADOW_MAP = 1024;
+/** Enable and configure shadow casting on a light from its `shadow` data. */
+const applyShadow = (light, config) => {
+	light.castShadow = true;
+	const s = typeof config === "object" ? config : {};
+	light.shadow.mapSize.setScalar(s.mapSize ?? DEFAULT_SHADOW_MAP);
+	if (s.bias !== void 0) light.shadow.bias = s.bias;
+	if (s.normalBias !== void 0) light.shadow.normalBias = s.normalBias;
+	const cam = light.shadow.camera;
+	if (s.near !== void 0) cam.near = s.near;
+	if (s.far !== void 0) cam.far = s.far;
+	if (cam instanceof OrthographicCamera && s.size !== void 0) {
+		cam.left = -s.size;
+		cam.right = s.size;
+		cam.top = s.size;
+		cam.bottom = -s.size;
+	}
+	cam.updateProjectionMatrix();
+};
+/**
+* Build the three.js object for a `Light`. Returns a `Group` (even for a single
+* light) so directional/spot lights can carry their `target` in the same node,
+* and so every light is addressed uniformly by `id` for reconciliation.
+*/
+function buildLight(light) {
+	const color = light.color ?? DEFAULT_COLOR;
+	const group = new Group();
+	switch (light.type) {
+		case "ambient":
+			group.add(new AmbientLight(color, light.intensity ?? 1.4));
+			break;
+		case "hemisphere":
+			group.add(new HemisphereLight(color, light.groundColor ?? "#444444", light.intensity ?? 1));
+			break;
+		case "directional": {
+			const l = new DirectionalLight(color, light.intensity ?? 1);
+			l.position.set(...light.position);
+			l.target.position.set(...light.target ?? [
+				0,
+				0,
+				0
+			]);
+			if (light.shadow) applyShadow(l, light.shadow);
+			group.add(l, l.target);
+			break;
+		}
+		case "point": {
+			const l = new PointLight(color, light.intensity ?? 1, light.distance ?? 0, light.decay ?? 2);
+			l.position.set(...light.position);
+			if (light.shadow) applyShadow(l, light.shadow);
+			group.add(l);
+			break;
+		}
+		case "spot": {
+			const l = new SpotLight(color, light.intensity ?? 1, light.distance ?? 0, light.angle ?? Math.PI / 6, light.penumbra ?? 0, light.decay ?? 2);
+			l.position.set(...light.position);
+			l.target.position.set(...light.target ?? [
+				0,
+				0,
+				0
+			]);
+			if (light.shadow) applyShadow(l, light.shadow);
+			group.add(l, l.target);
+			break;
+		}
+	}
+	group.name = `light:${light.id}`;
+	group.userData.scenographyId = light.id;
+	return group;
+}
+//#endregion
+//#region src/LightController.ts
+const isThreeLight = (o) => o.isLight === true;
+/**
+* High-level light control surfaced as `ctx.lights`. Works over the live light
+* objects (queried fresh each call so it keeps working across hot-swaps),
+* tweening intensity in the render loop.
+*/
+var LightController = class {
+	getLights;
+	tweens = /* @__PURE__ */ new Map();
+	/** Intensity captured before a dim, so `restore` can bring it back. */
+	baseline = /* @__PURE__ */ new WeakMap();
+	constructor(getLights) {
+		this.getLights = getLights;
+	}
+	lightsOf(group) {
+		const found = [];
+		group.traverse((o) => {
+			if (isThreeLight(o)) found.push(o);
+		});
+		return found;
+	}
+	all() {
+		return [...this.getLights().values()].flatMap((g) => this.lightsOf(g));
+	}
+	fade(light, to, duration) {
+		if (!duration || duration <= 0) {
+			this.tweens.delete(light);
+			light.intensity = to;
+			return;
+		}
+		this.tweens.set(light, {
+			from: light.intensity,
+			to,
+			elapsed: 0,
+			duration
+		});
+	}
+	/** Set intensity and/or color of every light under `id`. */
+	set(id, props, opts = {}) {
+		const group = this.getLights().get(id);
+		if (!group) return;
+		for (const light of this.lightsOf(group)) {
+			if (props.color !== void 0) light.color.set(props.color);
+			if (props.intensity !== void 0) this.fade(light, props.intensity, opts.duration ?? 0);
+		}
+	}
+	/** Fade every light toward `factor` of its current intensity (default off). */
+	dimAll(opts = {}) {
+		const factor = opts.factor ?? 0;
+		for (const light of this.all()) {
+			const base = this.baseline.get(light) ?? light.intensity;
+			this.baseline.set(light, base);
+			this.fade(light, base * factor, opts.duration ?? 0);
+		}
+	}
+	/** Fade every light back to the intensity captured before the last dim. */
+	restore(opts = {}) {
+		for (const light of this.all()) {
+			const base = this.baseline.get(light);
+			if (base === void 0) continue;
+			this.fade(light, base, opts.duration ?? 0);
+			this.baseline.delete(light);
+		}
+	}
+	/** Advance active fades. Called once per frame with the frame delta in ms. */
+	update(deltaMs) {
+		for (const [light, t] of this.tweens) {
+			t.elapsed += deltaMs;
+			const k = t.duration > 0 ? Math.min(t.elapsed / t.duration, 1) : 1;
+			light.intensity = t.from + (t.to - t.from) * k;
+			if (k >= 1) this.tweens.delete(light);
+		}
+	}
+};
+//#endregion
+//#region src/plugin.ts
+/**
+* The light plugin: builds each `Light` (ambient/hemisphere/directional/point/
+* spot, with shadows) and exposes `ctx.lights` — a controller that dims/sets
+* intensity and color over the live lights, tweening in the render loop.
+*/
+const light = () => ({
+	data: lightData,
+	build: (definition) => ({ object: buildLight(definition) }),
+	controller: (elements) => {
+		const controller = new LightController(elements);
+		return {
+			api: controller,
+			update: (deltaMs) => controller.update(deltaMs)
+		};
+	}
+});
+//#endregion
+export { LightController, buildLight, light, lightData, validateLight };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/buildLight.ts","../src/LightController.ts","../src/plugin.ts"],"sourcesContent":["import {\n  AmbientLight,\n  DirectionalLight,\n  Group,\n  HemisphereLight,\n  OrthographicCamera,\n  PointLight,\n  SpotLight,\n  type Object3D,\n} from \"three\";\nimport type { Light, LightShadow } from \"./data\";\n\nconst DEFAULT_COLOR = \"#ffffff\";\nconst DEFAULT_SHADOW_MAP = 1024;\n\n/** Enable and configure shadow casting on a light from its `shadow` data. */\nconst applyShadow = (\n  light: DirectionalLight | SpotLight | PointLight,\n  config: boolean | LightShadow,\n): void => {\n  light.castShadow = true;\n  const s: LightShadow = typeof config === \"object\" ? config : {};\n  light.shadow.mapSize.setScalar(s.mapSize ?? DEFAULT_SHADOW_MAP);\n  if (s.bias !== undefined) light.shadow.bias = s.bias;\n  if (s.normalBias !== undefined) light.shadow.normalBias = s.normalBias;\n\n  const cam = light.shadow.camera;\n  if (s.near !== undefined) cam.near = s.near;\n  if (s.far !== undefined) cam.far = s.far;\n  // Directional lights use an orthographic frustum; size it to the lit area.\n  if (cam instanceof OrthographicCamera && s.size !== undefined) {\n    cam.left = -s.size;\n    cam.right = s.size;\n    cam.top = s.size;\n    cam.bottom = -s.size;\n  }\n  cam.updateProjectionMatrix();\n};\n\n/**\n * Build the three.js object for a `Light`. Returns a `Group` (even for a single\n * light) so directional/spot lights can carry their `target` in the same node,\n * and so every light is addressed uniformly by `id` for reconciliation.\n */\nexport function buildLight(light: Light): Object3D {\n  const color = light.color ?? DEFAULT_COLOR;\n  const group = new Group();\n\n  switch (light.type) {\n    case \"ambient\":\n      group.add(new AmbientLight(color, light.intensity ?? 1.4));\n      break;\n    case \"hemisphere\":\n      group.add(\n        new HemisphereLight(color, light.groundColor ?? \"#444444\", light.intensity ?? 1),\n      );\n      break;\n    case \"directional\": {\n      const l = new DirectionalLight(color, light.intensity ?? 1);\n      l.position.set(...light.position);\n      l.target.position.set(...(light.target ?? [0, 0, 0]));\n      if (light.shadow) applyShadow(l, light.shadow);\n      group.add(l, l.target);\n      break;\n    }\n    case \"point\": {\n      const l = new PointLight(color, light.intensity ?? 1, light.distance ?? 0, light.decay ?? 2);\n      l.position.set(...light.position);\n      if (light.shadow) applyShadow(l, light.shadow);\n      group.add(l);\n      break;\n    }\n    case \"spot\": {\n      const l = new SpotLight(\n        color,\n        light.intensity ?? 1,\n        light.distance ?? 0,\n        light.angle ?? Math.PI / 6,\n        light.penumbra ?? 0,\n        light.decay ?? 2,\n      );\n      l.position.set(...light.position);\n      l.target.position.set(...(light.target ?? [0, 0, 0]));\n      if (light.shadow) applyShadow(l, light.shadow);\n      group.add(l, l.target);\n      break;\n    }\n  }\n\n  group.name = `light:${light.id}`;\n  group.userData.scenographyId = light.id;\n  return group;\n}\n","import type { LightSet, LightSetOptions, LightsApi } from \"@scenography/engine\";\nimport type { Color, Light as ThreeLight, Object3D } from \"three\";\n\ninterface Tween {\n  from: number;\n  to: number;\n  elapsed: number;\n  duration: number;\n}\n\nconst isThreeLight = (o: Object3D): o is ThreeLight => (o as ThreeLight).isLight === true;\n\n/**\n * High-level light control surfaced as `ctx.lights`. Works over the live light\n * objects (queried fresh each call so it keeps working across hot-swaps),\n * tweening intensity in the render loop.\n */\nexport class LightController implements LightsApi {\n  private readonly getLights: () => ReadonlyMap<string, Object3D>;\n  private readonly tweens = new Map<ThreeLight, Tween>();\n  /** Intensity captured before a dim, so `restore` can bring it back. */\n  private readonly baseline = new WeakMap<ThreeLight, number>();\n\n  constructor(getLights: () => ReadonlyMap<string, Object3D>) {\n    this.getLights = getLights;\n  }\n\n  private lightsOf(group: Object3D): ThreeLight[] {\n    const found: ThreeLight[] = [];\n    group.traverse((o) => {\n      if (isThreeLight(o)) found.push(o);\n    });\n    return found;\n  }\n\n  private all(): ThreeLight[] {\n    return [...this.getLights().values()].flatMap((g) => this.lightsOf(g));\n  }\n\n  private fade(light: ThreeLight, to: number, duration: number): void {\n    if (!duration || duration <= 0) {\n      this.tweens.delete(light);\n      light.intensity = to;\n      return;\n    }\n    this.tweens.set(light, { from: light.intensity, to, elapsed: 0, duration });\n  }\n\n  /** Set intensity and/or color of every light under `id`. */\n  set(id: string, props: LightSet, opts: LightSetOptions = {}): void {\n    const group = this.getLights().get(id);\n    if (!group) return;\n    for (const light of this.lightsOf(group)) {\n      if (props.color !== undefined) (light.color as Color).set(props.color);\n      if (props.intensity !== undefined) this.fade(light, props.intensity, opts.duration ?? 0);\n    }\n  }\n\n  /** Fade every light toward `factor` of its current intensity (default off). */\n  dimAll(opts: LightSetOptions & { factor?: number } = {}): void {\n    const factor = opts.factor ?? 0;\n    for (const light of this.all()) {\n      const base = this.baseline.get(light) ?? light.intensity;\n      this.baseline.set(light, base);\n      this.fade(light, base * factor, opts.duration ?? 0);\n    }\n  }\n\n  /** Fade every light back to the intensity captured before the last dim. */\n  restore(opts: LightSetOptions = {}): void {\n    for (const light of this.all()) {\n      const base = this.baseline.get(light);\n      if (base === undefined) continue;\n      this.fade(light, base, opts.duration ?? 0);\n      this.baseline.delete(light);\n    }\n  }\n\n  /** Advance active fades. Called once per frame with the frame delta in ms. */\n  update(deltaMs: number): void {\n    for (const [light, t] of this.tweens) {\n      t.elapsed += deltaMs;\n      const k = t.duration > 0 ? Math.min(t.elapsed / t.duration, 1) : 1;\n      light.intensity = t.from + (t.to - t.from) * k;\n      if (k >= 1) this.tweens.delete(light);\n    }\n  }\n}\n","import type { EnginePlugin } from \"@scenography/engine\";\n\nimport { buildLight } from \"./buildLight\";\nimport { LightController } from \"./LightController\";\nimport { lightData, type Light } from \"./data\";\n\n/**\n * The light plugin: builds each `Light` (ambient/hemisphere/directional/point/\n * spot, with shadows) and exposes `ctx.lights` — a controller that dims/sets\n * intensity and color over the live lights, tweening in the render loop.\n */\nexport const light = (): EnginePlugin<Light> => ({\n  data: lightData,\n  build: (definition) => ({ object: buildLight(definition) }),\n  controller: (elements) => {\n    const controller = new LightController(elements);\n    return { api: controller, update: (deltaMs) => controller.update(deltaMs) };\n  },\n});\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@scenography/plugin-light",
+  "version": "0.2.0",
+  "description": "Light plugin for scenography: ambient/hemisphere/directional/point/spot lights with shadows, and ctx.lights runtime control.",
+  "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"
+      }
+    },
+    "./data": {
+      "import": {
+        "types": "./dist/data.d.mts",
+        "default": "./dist/data.mjs"
+      },
+      "require": {
+        "types": "./dist/data.d.cts",
+        "default": "./dist/data.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"
+  }
+}