@glissade/scene 0.57.0 → 0.57.1-pre.0

package/dist/describe.js

@@ -23,7 +23,7 @@ import { easings, listValueTypes } from "@glissade/core";
 * never pulled onto the base embed path — a scene that never calls `describe()`
 * pays zero bytes for it.
 */
-const RAW_VERSION = "0.57.0";
+const RAW_VERSION = "0.57.1-pre.0";
 const PACKAGE_VERSION = RAW_VERSION.includes("GLISSADE_".concat("VERSION")) ? "0.0.0-dev" : RAW_VERSION;
 /**
 * Parse the documented positional-arg count from a helper `usage` string — the
@@ -586,13 +586,13 @@ const HELPERS = [
 		name: "particles",
 		summary: "A small SEEDED, BAKED particle emitter (FACTORY, no `new`): composes each() (count fixed slot nodes at `${id}/${i}`) + bake() (seeded physics → position/opacity/scale/rotation tracks on those SAME ids). Every slot is a real node with real tracks → a real exportable Lottie layer, faithful BY CONSTRUCTION (no render-only/custom-draw path). `count` is the MAX-CONCURRENT ring-buffer pool (bounded 200 — over THROWS, never clamps), NOT total emitted; opacity-0-for-the-whole-window slots are pruned so the layer count stays proportional. Seed defaults to hashStr(id); byte-identical run-to-run, a different seed varies. ESCAPE HATCH: `appearance` (any Node/glyph template), `step` (raw per-particle sim), `...` velocity/forces/lifetime. Tree-shakeable (@glissade/scene/motion).",
 		import: "@glissade/scene/motion",
-		usage: "particles(spec: { id, count, box: {w,h}, duration, fps, origin: [fx,fy], lifetime: number | [min,max], velocity: { speed:[min,max], angle:[min,max] (deg) }, appearance: (i, ctx) => Node | { node, opacityOverLife?, scaleOverLife? }, rate?, burst?: number | {at,n}[], seed?, area?, forces?: { gravity?, drag?, wind? }, spin?, opacityOverLife?, scaleOverLife?, step?: (p, dt, rng) => void }): { node: Group, tracks: Track[], end }  —  supply rate and/or burst; count > 200 throws."
+		usage: "particles(spec: { id, count, box: {w,h}, duration, fps, origin: [fx,fy], lifetime: number | [min,max], velocity: { speed:[min,max], angle:[min,max] (deg) }, appearance: (i, ctx) => Node | { node, opacityOverLife?, scaleOverLife? }, rate?, burst?: number | {at,n}[], seed?, area?, safeBottom? (relative [0,1] safe-area clamp — no spawn below this Y), forces?: { gravity?, drag?, wind? }, spin?, opacityOverLife?, scaleOverLife?, step?: (p, dt, rng) => void }): { node: Group, tracks: Track[], end }  —  supply rate and/or burst; count > 200 throws; safeBottom out-of-[0,1] or above the spawn-band top throws."
 	},
 	{
 		name: "drift",
-		summary: "Particles preset: ambient low-opacity motes floating gently up (a bokeh companion). Continuous low-rate; DEFAULTS to a small max-concurrent count (24) so the exported layer count stays proportional, NOT 200 near-empty layers. `appearance` is the primary control (a themed dot); `...rest` forwards to particles() (velocity/forces/lifetime/step). Factory (no `new`). Tree-shakeable (@glissade/scene/motion).",
+		summary: "Particles preset: ambient low-opacity motes floating gently up (a bokeh companion). Continuous low-rate; DEFAULTS to a small max-concurrent count (24) so the exported layer count stays proportional, NOT 200 near-empty layers. SAFE-AREA (0.57.1): the DEFAULT spawn band is centered + shallow (bottom ~0.68H) so bare drift() clears a standard lower-third caption safe-area by itself; pass `safeBottom` (relative [0,1]) to pin a consumer's exact captionTop, or override `area`/`origin` for a custom spawn region. `appearance` is the primary control (a themed dot); `...rest` forwards to particles() (velocity/forces/lifetime/area/safeBottom/step). Factory (no `new`). Tree-shakeable (@glissade/scene/motion).",
 		import: "@glissade/scene/motion",
-		usage: "drift(opts: { box: {w,h}, duration, fps, count?, rate?, origin?, color?, radius?, seed?, id?, ...rest (lifetime/velocity/forces/appearance/step) }): { node: Group, tracks: Track[], end }"
+		usage: "drift(opts: { box: {w,h}, duration, fps, count?, rate?, origin?, color?, radius?, seed?, id?, area?, safeBottom? (relative [0,1] — no motes below this Y, e.g. just above captionTop), ...rest (lifetime/velocity/forces/appearance/step) }): { node: Group, tracks: Track[], end }"
 	},
 	{
 		name: "sparks",

package/dist/motion.d.ts

@@ -305,6 +305,15 @@ interface ParticleSpec {
   origin: Place;
   /** Optional spread around the origin (px). */
   area?: AreaSpec;
+  /**
+   * Safe-area clamp (0.57.1): no particle spawns BELOW this RELATIVE Y (`safeBottom *
+   * box.h`), so ambient motes never drift into a lower-third caption band. Relative
+   * [0,1] — NOT a pixel Y. Must sit at/below the spawn band's top (a `safeBottom` above
+   * the band top leaves no valid spawn region → throws). The framework can't know a
+   * consumer's captionTop, so this is the opt-in PRECISE clamp; the `drift` preset also
+   * ships a conservative DEFAULT band that clears a standard lower-third by itself.
+   */
+  safeBottom?: number;
   /** Polar initial velocity — `speed` px/s, `angle` degrees (0 = +x / right). */
   velocity: {
     speed: readonly [number, number];
@@ -347,6 +356,8 @@ interface ParticlePresetRest {
   forces?: ParticleForces;
   spin?: readonly [number, number];
   area?: AreaSpec;
+  /** Safe-area clamp (relative [0,1]) — no spawn below this Y. See ParticleSpec.safeBottom. */
+  safeBottom?: number;
   opacityOverLife?: OverLife;
   scaleOverLife?: OverLife;
   appearance?: (i: number, ctx: ParticleAppearanceContext) => Node | ParticleAppearance;
@@ -363,7 +374,7 @@ interface DriftOptions extends ParticlePresetRest {
   count?: number;
   /** Continuous emission rate, particles/sec (default 8). */
   rate?: number;
-  /** Spawn point, relative viewport coords (default centered-lower [0.5,0.6]). */
+  /** Spawn point, relative viewport coords (default centered [0.5,0.5] — the conservative caption-safe band). */
   origin?: Place;
   /** Themed mote color (default a soft blue). */
   color?: string;

package/dist/motion.js

@@ -403,6 +403,13 @@ function particles(spec) {
 		assertFiniteNum(spec.area.w, "area.w");
 		assertFiniteNum(spec.area.h, "area.h");
 	} else if (spec.area?.kind === "disc") assertFiniteNum(spec.area.radius, "area.radius");
+	if (spec.safeBottom !== void 0) {
+		const sb = assertFiniteNum(spec.safeBottom, "safeBottom");
+		if (sb < 0 || sb > 1) throw new ParticleError(`particles(): safeBottom must be a RELATIVE fraction in [0,1] (got ${sb}) — it is safeBottom*box.h, not a pixel Y (did you pass a captionTop in px?).`);
+		const areaHalfHRel = spec.area?.kind === "box" ? spec.area.h / 2 / spec.box.h : spec.area?.kind === "disc" ? spec.area.radius / spec.box.h : 0;
+		const bandTopRel = spec.origin[1] - areaHalfHRel;
+		if (sb < bandTopRel) throw new ParticleError(`particles(): safeBottom ${sb} is above the spawn band top (${bandTopRel.toFixed(3)}) — no valid spawn region (raise safeBottom, or lower the origin/shrink the area).`);
+	}
 	const emitTimes = buildEmitTimes(spec);
 	const opacityCurves = new Array(count);
 	const scaleCurves = new Array(count);
@@ -434,6 +441,7 @@ function particles(spec) {
 	const ox = spec.origin[0] * spec.box.w;
 	const oy = spec.origin[1] * spec.box.h;
 	const area = spec.area;
+	const safeBottomPx = spec.safeBottom !== void 0 ? spec.safeBottom * spec.box.h : void 0;
 	const emitDue = (w, rng) => {
 		const t = w.frame / spec.fps;
 		while (w.next < emitTimes.length && emitTimes[w.next] <= t + 1e-9) {
@@ -455,6 +463,7 @@ function particles(spec) {
 				px += Math.cos(th) * rr;
 				py += Math.sin(th) * rr;
 			}
+			if (safeBottomPx !== void 0 && py > safeBottomPx) py = safeBottomPx;
 			s.x = px;
 			s.y = py;
 			s.rot = 0;
@@ -556,6 +565,7 @@ function mergeSpec(base, rest) {
 		...rest.forces !== void 0 ? { forces: rest.forces } : {},
 		...rest.spin !== void 0 ? { spin: rest.spin } : {},
 		...rest.area !== void 0 ? { area: rest.area } : {},
+		...rest.safeBottom !== void 0 ? { safeBottom: rest.safeBottom } : {},
 		...rest.opacityOverLife !== void 0 ? { opacityOverLife: rest.opacityOverLife } : {},
 		...rest.scaleOverLife !== void 0 ? { scaleOverLife: rest.scaleOverLife } : {},
 		...rest.appearance !== void 0 ? { appearance: rest.appearance } : {},
@@ -584,7 +594,7 @@ function drift(opts) {
 		duration: opts.duration,
 		fps: opts.fps,
 		rate: opts.rate ?? 8,
-		origin: opts.origin ?? [.5, .6],
+		origin: opts.origin ?? [.5, .5],
 		lifetime: [3, 6],
 		velocity: {
 			speed: [4, 14],
@@ -594,7 +604,7 @@ function drift(opts) {
 		area: {
 			kind: "box",
 			w: opts.box.w * .8,
-			h: opts.box.h * .5
+			h: opts.box.h * .36
 		},
 		opacityOverLife: fadeCurve(.5, .2, .35),
 		appearance: dotAppearance(color, radius)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.57.0",
+  "version": "0.57.1-pre.0",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -77,7 +77,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.57.0"
+    "@glissade/core": "0.57.1-pre.0"
   },
   "repository": {
     "type": "git",