@futdevpro/fsm-dynamo 1.20.120 → 1.20.122

package/build/_modules/game/_collections/label-placement.util.d.ts

@@ -0,0 +1,47 @@
+import { DyFM_LabelPlacement_Rect, DyFM_LabelPlacement_Request, DyFM_LabelPlacement_Result } from '../_models/label-placement.interface';
+/**
+ * BFR-PH-007 — HUD-exclusion-aware placement of world-linked labels (pickup "+6 Wood", damage numbers…), pure and
+ * renderer-independent (the caller measures the label and registers its HUD rectangles; any renderer draws the result).
+ *
+ * Measured (Portalhold, 1280×720): a pickup label landed under the Basics panel — the onboarding overlay positions only
+ * its own bubble, and the viewport transform knows no exclusions. The rules here:
+ * - the label stays FULLY inside the viewport and never intersects a protected rectangle or an earlier label of the
+ *   burst (each widened by `gap`) — it never silently lands on a button;
+ * - the PREFERRED spot is centred above the anchor; a still-valid previous spot is kept first (no jitter on
+ *   resize / zoom / reduced motion);
+ * - otherwise the valid candidate closest to the preferred spot wins, ties broken by a fixed order (deterministic);
+ * - nowhere valid ⇒ an explicit `no-space` result (the caller keeps the information in the HUD / log), never an
+ *   overlap; invalid geometry ⇒ `invalid-geometry` with the reason.
+ */
+export declare class DyFM_LabelPlacement_Util {
+    /** The default clearance between the label and the anchor / a blocked rectangle (pixels). */
+    static readonly defaultGap: number;
+    /** Places one label (see the class description for the rules). */
+    static place(request: DyFM_LabelPlacement_Request): DyFM_LabelPlacement_Result;
+    /** Whether two rectangles overlap when each is widened by `gap` (touching at exactly `gap` is allowed). */
+    static intersects(a: DyFM_LabelPlacement_Rect, b: DyFM_LabelPlacement_Rect, gap?: number): boolean;
+    /** Whether a rectangle is fully on screen and clear of every protected area and earlier label (widened by `gap`). */
+    private static isClear;
+    /** The spot the label wants: centred horizontally above the anchor, `gap` above it. */
+    private static preferredRect;
+    /**
+     * The candidates in the fixed try-order: previous · above · below · right · left (each kept inside the viewport
+     * along its free axis) · then clear of each protected area and each earlier label (above / below / left / right).
+     */
+    private static candidates;
+    /** The ids of the protected areas a rectangle would cover (attribution — why a label moved). */
+    private static blockingIds;
+    /** A value kept between `min` and `max`. */
+    private static clamp;
+    /** Whether every value is a finite number. */
+    private static allFinite;
+    /** Whether a rectangle is present, finite, and has a non-negative size. */
+    private static isFiniteRect;
+    /** Whether the rectangle lies fully inside the viewport. */
+    private static inside;
+    /** The distance between two rectangle centres. */
+    private static centreDistance;
+    /** The first invalid input, as a readable reason; `null` when the geometry is usable. */
+    private static findInvalidGeometry;
+}
+//# sourceMappingURL=label-placement.util.d.ts.map

package/build/_modules/game/_collections/label-placement.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-placement.util.d.ts","sourceRoot":"","sources":["../../../../src/_modules/game/_collections/label-placement.util.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,wBAAwB,EACxB,2BAA2B,EAC3B,0BAA0B,EAE3B,MAAM,sCAAsC,CAAC;AAQ9C;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAwB;IACnC,6FAA6F;IAC7F,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAK;IAEvC,kEAAkE;IAClE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,2BAA2B,GAAG,0BAA0B;IAqF9E,2GAA2G;IAC3G,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,wBAAwB,EAAE,CAAC,EAAE,wBAAwB,EAAE,GAAG,GAAE,MAAU,GAAG,OAAO;IAKrG,qHAAqH;IACrH,OAAO,CAAC,MAAM,CAAC,OAAO;IActB,uFAAuF;IACvF,OAAO,CAAC,MAAM,CAAC,aAAa;IAS5B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU;IAwCzB,gGAAgG;IAChG,OAAO,CAAC,MAAM,CAAC,WAAW;IAW1B,4CAA4C;IAC5C,OAAO,CAAC,MAAM,CAAC,KAAK;IAIpB,8CAA8C;IAC9C,OAAO,CAAC,MAAM,CAAC,SAAS;IAIxB,2EAA2E;IAC3E,OAAO,CAAC,MAAM,CAAC,YAAY;IAK3B,4DAA4D;IAC5D,OAAO,CAAC,MAAM,CAAC,MAAM;IAKrB,kDAAkD;IAClD,OAAO,CAAC,MAAM,CAAC,cAAc;IAI7B,yFAAyF;IACzF,OAAO,CAAC,MAAM,CAAC,mBAAmB;CAsCnC"}

package/build/_modules/game/_collections/label-placement.util.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyFM_LabelPlacement_Util = void 0;
+/**
+ * BFR-PH-007 — HUD-exclusion-aware placement of world-linked labels (pickup "+6 Wood", damage numbers…), pure and
+ * renderer-independent (the caller measures the label and registers its HUD rectangles; any renderer draws the result).
+ *
+ * Measured (Portalhold, 1280×720): a pickup label landed under the Basics panel — the onboarding overlay positions only
+ * its own bubble, and the viewport transform knows no exclusions. The rules here:
+ * - the label stays FULLY inside the viewport and never intersects a protected rectangle or an earlier label of the
+ *   burst (each widened by `gap`) — it never silently lands on a button;
+ * - the PREFERRED spot is centred above the anchor; a still-valid previous spot is kept first (no jitter on
+ *   resize / zoom / reduced motion);
+ * - otherwise the valid candidate closest to the preferred spot wins, ties broken by a fixed order (deterministic);
+ * - nowhere valid ⇒ an explicit `no-space` result (the caller keeps the information in the HUD / log), never an
+ *   overlap; invalid geometry ⇒ `invalid-geometry` with the reason.
+ */
+class DyFM_LabelPlacement_Util {
+    /** The default clearance between the label and the anchor / a blocked rectangle (pixels). */
+    static defaultGap = 4;
+    /** Places one label (see the class description for the rules). */
+    static place(request) {
+        const invalid = DyFM_LabelPlacement_Util.findInvalidGeometry(request);
+        if (invalid) {
+            return { placed: false, reason: 'invalid-geometry', detail: invalid, blockedBy: [] };
+        }
+        const gap = request.gap ?? DyFM_LabelPlacement_Util.defaultGap;
+        const exclusions = request.exclusions ?? [];
+        const occupied = request.occupied ?? [];
+        const preferred = DyFM_LabelPlacement_Util.preferredRect(request, gap);
+        const blockedBy = DyFM_LabelPlacement_Util.blockingIds(preferred, exclusions, gap);
+        if (request.label.width > request.viewport.width || request.label.height > request.viewport.height) {
+            return {
+                placed: false,
+                reason: 'no-space',
+                detail: `the label (${request.label.width}×${request.label.height}) is larger than the viewport `
+                    + `(${request.viewport.width}×${request.viewport.height})`,
+                blockedBy: blockedBy,
+            };
+        }
+        /** A candidate is usable when it is on screen and clear of every blocked rectangle. */
+        const isValid = (rect) => DyFM_LabelPlacement_Util.isClear({
+            rect: rect, viewport: request.viewport, exclusions: exclusions, occupied: occupied, gap: gap,
+        });
+        const candidates = DyFM_LabelPlacement_Util.candidates(request, gap);
+        const previous = candidates[0]?.side === 'previous' && isValid(candidates[0].rect) ? candidates[0] : undefined;
+        let best = previous;
+        if (!best) {
+            let bestDistance = Number.POSITIVE_INFINITY;
+            for (const candidate of candidates) {
+                if (candidate.side === 'previous' || !isValid(candidate.rect)) {
+                    continue;
+                }
+                const distance = DyFM_LabelPlacement_Util.centreDistance(candidate.rect, preferred);
+                // strictly smaller only ⇒ on a tie the EARLIER candidate stays (fixed order = deterministic)
+                if (distance < bestDistance) {
+                    best = candidate;
+                    bestDistance = distance;
+                }
+            }
+        }
+        if (!best) {
+            const everyBlocker = [...blockedBy];
+            for (const candidate of candidates) {
+                for (const id of DyFM_LabelPlacement_Util.blockingIds(candidate.rect, exclusions, gap)) {
+                    if (!everyBlocker.includes(id)) {
+                        everyBlocker.push(id);
+                    }
+                }
+            }
+            return {
+                placed: false,
+                reason: 'no-space',
+                detail: `no position inside the viewport is clear of the ${exclusions.length} protected area(s) `
+                    + `and ${occupied.length} earlier label(s)`,
+                blockedBy: everyBlocker,
+            };
+        }
+        const displacement = {
+            x: best.rect.x - preferred.x,
+            y: best.rect.y - preferred.y,
+        };
+        return {
+            placed: true,
+            rect: { ...best.rect },
+            side: best.side,
+            displacement: displacement,
+            displaced: displacement.x !== 0 || displacement.y !== 0,
+            blockedBy: blockedBy,
+        };
+    }
+    /** Whether two rectangles overlap when each is widened by `gap` (touching at exactly `gap` is allowed). */
+    static intersects(a, b, gap = 0) {
+        return a.x < b.x + b.width + gap && a.x + a.width + gap > b.x
+            && a.y < b.y + b.height + gap && a.y + a.height + gap > b.y;
+    }
+    /** Whether a rectangle is fully on screen and clear of every protected area and earlier label (widened by `gap`). */
+    static isClear(set) {
+        return DyFM_LabelPlacement_Util.inside(set.rect, set.viewport)
+            && !set.exclusions.some((each) => DyFM_LabelPlacement_Util.intersects(set.rect, each.rect, set.gap))
+            && !set.occupied.some((each) => DyFM_LabelPlacement_Util.intersects(set.rect, each, set.gap));
+    }
+    /** The spot the label wants: centred horizontally above the anchor, `gap` above it. */
+    static preferredRect(request, gap) {
+        return {
+            x: request.anchor.x - request.label.width / 2,
+            y: request.anchor.y - gap - request.label.height,
+            width: request.label.width,
+            height: request.label.height,
+        };
+    }
+    /**
+     * The candidates in the fixed try-order: previous · above · below · right · left (each kept inside the viewport
+     * along its free axis) · then clear of each protected area and each earlier label (above / below / left / right).
+     */
+    static candidates(request, gap) {
+        const width = request.label.width;
+        const height = request.label.height;
+        const anchor = request.anchor;
+        const vp = request.viewport;
+        /** A label-sized rectangle at a top-left corner. */
+        const rect = (x, y) => ({ x: x, y: y, width: width, height: height });
+        // centred on the anchor along the free axis, but kept on screen
+        const centredX = DyFM_LabelPlacement_Util.clamp(anchor.x - width / 2, vp.x, vp.x + vp.width - width);
+        const centredY = DyFM_LabelPlacement_Util.clamp(anchor.y - height / 2, vp.y, vp.y + vp.height - height);
+        const list = [];
+        if (request.previous) {
+            list.push({ rect: rect(request.previous.x, request.previous.y), side: 'previous' });
+        }
+        list.push({ rect: rect(centredX, anchor.y - gap - height), side: 'above' }, { rect: rect(centredX, anchor.y + gap), side: 'below' }, { rect: rect(anchor.x + gap, centredY), side: 'right' }, { rect: rect(anchor.x - gap - width, centredY), side: 'left' });
+        const blockers = [
+            ...(request.exclusions ?? []).map((each) => each.rect),
+            ...(request.occupied ?? []),
+        ];
+        for (const blocker of blockers) {
+            list.push({ rect: rect(centredX, blocker.y - gap - height), side: 'clear-of-exclusion' }, { rect: rect(centredX, blocker.y + blocker.height + gap), side: 'clear-of-exclusion' }, { rect: rect(blocker.x - gap - width, centredY), side: 'clear-of-exclusion' }, { rect: rect(blocker.x + blocker.width + gap, centredY), side: 'clear-of-exclusion' });
+        }
+        return list;
+    }
+    /** The ids of the protected areas a rectangle would cover (attribution — why a label moved). */
+    static blockingIds(rect, exclusions, gap) {
+        return exclusions
+            .filter((each) => DyFM_LabelPlacement_Util.intersects(rect, each.rect, gap))
+            .map((each) => each.id);
+    }
+    /** A value kept between `min` and `max`. */
+    static clamp(value, min, max) {
+        return Math.min(Math.max(value, min), max);
+    }
+    /** Whether every value is a finite number. */
+    static allFinite(...values) {
+        return values.every((value) => Number.isFinite(value));
+    }
+    /** Whether a rectangle is present, finite, and has a non-negative size. */
+    static isFiniteRect(rect) {
+        return !!rect && DyFM_LabelPlacement_Util.allFinite(rect.x, rect.y, rect.width, rect.height)
+            && rect.width >= 0 && rect.height >= 0;
+    }
+    /** Whether the rectangle lies fully inside the viewport. */
+    static inside(rect, vp) {
+        return rect.x >= vp.x && rect.y >= vp.y && rect.x + rect.width <= vp.x + vp.width
+            && rect.y + rect.height <= vp.y + vp.height;
+    }
+    /** The distance between two rectangle centres. */
+    static centreDistance(a, b) {
+        return Math.hypot((a.x + a.width / 2) - (b.x + b.width / 2), (a.y + a.height / 2) - (b.y + b.height / 2));
+    }
+    /** The first invalid input, as a readable reason; `null` when the geometry is usable. */
+    static findInvalidGeometry(request) {
+        const finite = DyFM_LabelPlacement_Util.allFinite;
+        const finiteRect = DyFM_LabelPlacement_Util.isFiniteRect;
+        if (!request?.anchor || !finite(request.anchor.x, request.anchor.y)) {
+            return 'the anchor must be a finite point';
+        }
+        if (!request.label || !finite(request.label.width, request.label.height)
+            || !(request.label.width > 0) || !(request.label.height > 0)) {
+            return 'the label needs a measured, positive size';
+        }
+        if (!finiteRect(request.viewport) || !(request.viewport.width > 0) || !(request.viewport.height > 0)) {
+            return 'the viewport needs a finite, positive size';
+        }
+        if (request.gap !== undefined && (!finite(request.gap) || request.gap < 0)) {
+            return 'the gap must be a finite, non-negative number';
+        }
+        const badExclusion = (request.exclusions ?? [])
+            .find((each) => !each?.id || !finiteRect(each.rect));
+        if (badExclusion) {
+            return `the protected area "${badExclusion?.id ?? '?'}" needs an id and a finite, non-negative rectangle`;
+        }
+        if ((request.occupied ?? []).some((each) => !finiteRect(each))) {
+            return 'every occupied rectangle must be finite and non-negative';
+        }
+        if (request.previous && !finite(request.previous.x, request.previous.y)) {
+            return 'the previous position must be a finite point';
+        }
+        return null;
+    }
+}
+exports.DyFM_LabelPlacement_Util = DyFM_LabelPlacement_Util;
+//# sourceMappingURL=label-placement.util.js.map

package/build/_modules/game/_collections/label-placement.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-placement.util.js","sourceRoot":"","sources":["../../../../src/_modules/game/_collections/label-placement.util.ts"],"names":[],"mappings":"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"}

package/build/_modules/game/_models/label-placement.interface.d.ts

@@ -0,0 +1,60 @@
+import { DyFM_Viewport_Point } from './viewport.interface';
+/** BFR-PH-007 — an axis-aligned screen rectangle (pixels; `x` / `y` = the top-left corner). */
+export interface DyFM_LabelPlacement_Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** BFR-PH-007 — a protected screen area a label must never cover (a HUD panel, a button…), with a stable id. */
+export interface DyFM_LabelPlacement_Exclusion {
+    id: string;
+    rect: DyFM_LabelPlacement_Rect;
+}
+/** BFR-PH-007 — the candidate side a placed label ended up on, relative to its anchor. */
+export type DyFM_LabelPlacement_Side = 'previous' | 'above' | 'below' | 'right' | 'left' | 'clear-of-exclusion';
+/** BFR-PH-007 — one placement request: a world-linked label (e.g. "+6 Wood") at its screen anchor. */
+export interface DyFM_LabelPlacement_Request {
+    /** The screen point the label belongs to (the world position projected to the screen). */
+    anchor: DyFM_Viewport_Point;
+    /** The MEASURED label size (pixels). */
+    label: {
+        width: number;
+        height: number;
+    };
+    /** The visible area; the label must stay fully inside it. */
+    viewport: DyFM_LabelPlacement_Rect;
+    /** Protected areas (HUD) — never covered. */
+    exclusions?: DyFM_LabelPlacement_Exclusion[];
+    /** Rectangles already taken in this burst (earlier labels) — a new label stacks clear of them. */
+    occupied?: DyFM_LabelPlacement_Rect[];
+    /** The minimum clearance between the label and the anchor / any blocked rectangle (pixels). Default: `4`. */
+    gap?: number;
+    /** The label's previous top-left (the frame before) — kept when still valid, so a label never jitters. */
+    previous?: DyFM_Viewport_Point | null;
+}
+/** BFR-PH-007 — the label fits: where it goes and what moved it. */
+export interface DyFM_LabelPlacement_Placed {
+    placed: true;
+    /** The label rectangle to draw. */
+    rect: DyFM_LabelPlacement_Rect;
+    side: DyFM_LabelPlacement_Side;
+    /** How far the label centre moved from the preferred spot (centred above the anchor). */
+    displacement: DyFM_Viewport_Point;
+    /** `true` when the preferred spot was blocked or off-screen. */
+    displaced: boolean;
+    /** The exclusion ids that blocked the preferred spot (attribution — why the label moved). */
+    blockedBy: string[];
+}
+/** BFR-PH-007 — the label does NOT fit anywhere valid: the caller keeps the information elsewhere (HUD / log). */
+export interface DyFM_LabelPlacement_NotPlaced {
+    placed: false;
+    reason: 'no-space' | 'invalid-geometry';
+    /** A readable explanation (which input is invalid, or that every candidate was blocked). */
+    detail: string;
+    /** The exclusion ids that blocked candidates (empty for invalid geometry). */
+    blockedBy: string[];
+}
+/** BFR-PH-007 — the placement answer: placed, or an explicit "nowhere to put it" (never a silent overlap). */
+export type DyFM_LabelPlacement_Result = DyFM_LabelPlacement_Placed | DyFM_LabelPlacement_NotPlaced;
+//# sourceMappingURL=label-placement.interface.d.ts.map

package/build/_modules/game/_models/label-placement.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-placement.interface.d.ts","sourceRoot":"","sources":["../../../../src/_modules/game/_models/label-placement.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,+FAA+F;AAC/F,MAAM,WAAW,wBAAwB;IACvC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gHAAgH;AAChH,MAAM,WAAW,6BAA6B;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,wBAAwB,CAAC;CAChC;AAED,0FAA0F;AAC1F,MAAM,MAAM,wBAAwB,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,oBAAoB,CAAC;AAEhH,sGAAsG;AACtG,MAAM,WAAW,2BAA2B;IAC1C,0FAA0F;IAC1F,MAAM,EAAE,mBAAmB,CAAC;IAC5B,wCAAwC;IACxC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,6DAA6D;IAC7D,QAAQ,EAAE,wBAAwB,CAAC;IACnC,6CAA6C;IAC7C,UAAU,CAAC,EAAE,6BAA6B,EAAE,CAAC;IAC7C,kGAAkG;IAClG,QAAQ,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACtC,6GAA6G;IAC7G,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACvC;AAED,oEAAoE;AACpE,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,IAAI,CAAC;IACb,mCAAmC;IACnC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,IAAI,EAAE,wBAAwB,CAAC;IAC/B,yFAAyF;IACzF,YAAY,EAAE,mBAAmB,CAAC;IAClC,gEAAgE;IAChE,SAAS,EAAE,OAAO,CAAC;IACnB,6FAA6F;IAC7F,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,kHAAkH;AAClH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,KAAK,CAAC;IACd,MAAM,EAAE,UAAU,GAAG,kBAAkB,CAAC;IACxC,4FAA4F;IAC5F,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,8GAA8G;AAC9G,MAAM,MAAM,0BAA0B,GAAG,0BAA0B,GAAG,6BAA6B,CAAC"}

package/build/_modules/game/_models/label-placement.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=label-placement.interface.js.map

package/build/_modules/game/_models/label-placement.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-placement.interface.js","sourceRoot":"","sources":["../../../../src/_modules/game/_models/label-placement.interface.ts"],"names":[],"mappings":""}

package/build/_modules/game/index.d.ts

@@ -18,6 +18,7 @@ export * from './_models/work-order-scheduler.control-model';
 export * from './_models/build-reservation.interface';
 export * from './_models/viewport.interface';
 export * from './_models/viewport.control-model';
+export * from './_models/label-placement.interface';
 export * from './_models/input-action.interface';
 export * from './_models/input-action-registry.control-model';
 export * from './_models/guided-onboarding.interface';
@@ -28,4 +29,5 @@ export * from './_collections/audio-mixer.util';
 export * from './_collections/audio-scale.util';
 export * from './_collections/game-save.util';
 export * from './_collections/build-reservation.util';
+export * from './_collections/label-placement.util';
 //# sourceMappingURL=index.d.ts.map

package/build/_modules/game/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":"AACA,cAAc,6BAA6B,CAAC;AAG5C,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,uCAAuC,CAAC;AACtD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0CAA0C,CAAC;AACzD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,uCAAuC,CAAC;AACtD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AAGzD,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uCAAuC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":"AACA,cAAc,6BAA6B,CAAC;AAG5C,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,uCAAuC,CAAC;AACtD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0CAA0C,CAAC;AACzD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,uCAAuC,CAAC;AACtD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,cAAc,kCAAkC,CAAC;AACjD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,uCAAuC,CAAC;AACtD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AAGzD,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC"}

package/build/_modules/game/index.js

@@ -23,6 +23,7 @@ tslib_1.__exportStar(require("./_models/work-order-scheduler.control-model"), ex
 tslib_1.__exportStar(require("./_models/build-reservation.interface"), exports);
 tslib_1.__exportStar(require("./_models/viewport.interface"), exports);
 tslib_1.__exportStar(require("./_models/viewport.control-model"), exports);
+tslib_1.__exportStar(require("./_models/label-placement.interface"), exports);
 tslib_1.__exportStar(require("./_models/input-action.interface"), exports);
 tslib_1.__exportStar(require("./_models/input-action-registry.control-model"), exports);
 tslib_1.__exportStar(require("./_models/guided-onboarding.interface"), exports);
@@ -34,4 +35,5 @@ tslib_1.__exportStar(require("./_collections/audio-mixer.util"), exports);
 tslib_1.__exportStar(require("./_collections/audio-scale.util"), exports);
 tslib_1.__exportStar(require("./_collections/game-save.util"), exports);
 tslib_1.__exportStar(require("./_collections/build-reservation.util"), exports);
+tslib_1.__exportStar(require("./_collections/label-placement.util"), exports);
 //# sourceMappingURL=index.js.map

package/build/_modules/game/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":";;;AAAA,QAAQ;AACR,sEAA4C;AAE5C,SAAS;AACT,iFAAuD;AACvD,mFAAyD;AACzD,gFAAsD;AACtD,8EAAoD;AACpD,0EAAgD;AAChD,kFAAwD;AACxD,gFAAsD;AACtD,qFAA2D;AAC3D,yFAA+D;AAC/D,4EAAkD;AAClD,gFAAsD;AACtD,+EAAqD;AACrD,mFAAyD;AACzD,wEAA8C;AAC9C,mFAAyD;AACzD,uFAA6D;AAC7D,gFAAsD;AACtD,uEAA6C;AAC7C,2EAAiD;AACjD,2EAAiD;AACjD,wFAA8D;AAC9D,gFAAsD;AACtD,oFAA0D;AAC1D,+EAAqD;AACrD,mFAAyD;AAEzD,cAAc;AACd,0EAAgD;AAChD,0EAAgD;AAChD,wEAA8C;AAC9C,gFAAsD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":";;;AAAA,QAAQ;AACR,sEAA4C;AAE5C,SAAS;AACT,iFAAuD;AACvD,mFAAyD;AACzD,gFAAsD;AACtD,8EAAoD;AACpD,0EAAgD;AAChD,kFAAwD;AACxD,gFAAsD;AACtD,qFAA2D;AAC3D,yFAA+D;AAC/D,4EAAkD;AAClD,gFAAsD;AACtD,+EAAqD;AACrD,mFAAyD;AACzD,wEAA8C;AAC9C,mFAAyD;AACzD,uFAA6D;AAC7D,gFAAsD;AACtD,uEAA6C;AAC7C,2EAAiD;AACjD,8EAAoD;AACpD,2EAAiD;AACjD,wFAA8D;AAC9D,gFAAsD;AACtD,oFAA0D;AAC1D,+EAAqD;AACrD,mFAAyD;AAEzD,cAAc;AACd,0EAAgD;AAChD,0EAAgD;AAChD,wEAA8C;AAC9C,gFAAsD;AACtD,8EAAoD"}

package/build-esm/_modules/game/_collections/label-placement.util.js

@@ -0,0 +1,195 @@
+/**
+ * BFR-PH-007 — HUD-exclusion-aware placement of world-linked labels (pickup "+6 Wood", damage numbers…), pure and
+ * renderer-independent (the caller measures the label and registers its HUD rectangles; any renderer draws the result).
+ *
+ * Measured (Portalhold, 1280×720): a pickup label landed under the Basics panel — the onboarding overlay positions only
+ * its own bubble, and the viewport transform knows no exclusions. The rules here:
+ * - the label stays FULLY inside the viewport and never intersects a protected rectangle or an earlier label of the
+ *   burst (each widened by `gap`) — it never silently lands on a button;
+ * - the PREFERRED spot is centred above the anchor; a still-valid previous spot is kept first (no jitter on
+ *   resize / zoom / reduced motion);
+ * - otherwise the valid candidate closest to the preferred spot wins, ties broken by a fixed order (deterministic);
+ * - nowhere valid ⇒ an explicit `no-space` result (the caller keeps the information in the HUD / log), never an
+ *   overlap; invalid geometry ⇒ `invalid-geometry` with the reason.
+ */
+export class DyFM_LabelPlacement_Util {
+    /** The default clearance between the label and the anchor / a blocked rectangle (pixels). */
+    static defaultGap = 4;
+    /** Places one label (see the class description for the rules). */
+    static place(request) {
+        const invalid = DyFM_LabelPlacement_Util.findInvalidGeometry(request);
+        if (invalid) {
+            return { placed: false, reason: 'invalid-geometry', detail: invalid, blockedBy: [] };
+        }
+        const gap = request.gap ?? DyFM_LabelPlacement_Util.defaultGap;
+        const exclusions = request.exclusions ?? [];
+        const occupied = request.occupied ?? [];
+        const preferred = DyFM_LabelPlacement_Util.preferredRect(request, gap);
+        const blockedBy = DyFM_LabelPlacement_Util.blockingIds(preferred, exclusions, gap);
+        if (request.label.width > request.viewport.width || request.label.height > request.viewport.height) {
+            return {
+                placed: false,
+                reason: 'no-space',
+                detail: `the label (${request.label.width}×${request.label.height}) is larger than the viewport `
+                    + `(${request.viewport.width}×${request.viewport.height})`,
+                blockedBy: blockedBy,
+            };
+        }
+        /** A candidate is usable when it is on screen and clear of every blocked rectangle. */
+        const isValid = (rect) => DyFM_LabelPlacement_Util.isClear({
+            rect: rect, viewport: request.viewport, exclusions: exclusions, occupied: occupied, gap: gap,
+        });
+        const candidates = DyFM_LabelPlacement_Util.candidates(request, gap);
+        const previous = candidates[0]?.side === 'previous' && isValid(candidates[0].rect) ? candidates[0] : undefined;
+        let best = previous;
+        if (!best) {
+            let bestDistance = Number.POSITIVE_INFINITY;
+            for (const candidate of candidates) {
+                if (candidate.side === 'previous' || !isValid(candidate.rect)) {
+                    continue;
+                }
+                const distance = DyFM_LabelPlacement_Util.centreDistance(candidate.rect, preferred);
+                // strictly smaller only ⇒ on a tie the EARLIER candidate stays (fixed order = deterministic)
+                if (distance < bestDistance) {
+                    best = candidate;
+                    bestDistance = distance;
+                }
+            }
+        }
+        if (!best) {
+            const everyBlocker = [...blockedBy];
+            for (const candidate of candidates) {
+                for (const id of DyFM_LabelPlacement_Util.blockingIds(candidate.rect, exclusions, gap)) {
+                    if (!everyBlocker.includes(id)) {
+                        everyBlocker.push(id);
+                    }
+                }
+            }
+            return {
+                placed: false,
+                reason: 'no-space',
+                detail: `no position inside the viewport is clear of the ${exclusions.length} protected area(s) `
+                    + `and ${occupied.length} earlier label(s)`,
+                blockedBy: everyBlocker,
+            };
+        }
+        const displacement = {
+            x: best.rect.x - preferred.x,
+            y: best.rect.y - preferred.y,
+        };
+        return {
+            placed: true,
+            rect: { ...best.rect },
+            side: best.side,
+            displacement: displacement,
+            displaced: displacement.x !== 0 || displacement.y !== 0,
+            blockedBy: blockedBy,
+        };
+    }
+    /** Whether two rectangles overlap when each is widened by `gap` (touching at exactly `gap` is allowed). */
+    static intersects(a, b, gap = 0) {
+        return a.x < b.x + b.width + gap && a.x + a.width + gap > b.x
+            && a.y < b.y + b.height + gap && a.y + a.height + gap > b.y;
+    }
+    /** Whether a rectangle is fully on screen and clear of every protected area and earlier label (widened by `gap`). */
+    static isClear(set) {
+        return DyFM_LabelPlacement_Util.inside(set.rect, set.viewport)
+            && !set.exclusions.some((each) => DyFM_LabelPlacement_Util.intersects(set.rect, each.rect, set.gap))
+            && !set.occupied.some((each) => DyFM_LabelPlacement_Util.intersects(set.rect, each, set.gap));
+    }
+    /** The spot the label wants: centred horizontally above the anchor, `gap` above it. */
+    static preferredRect(request, gap) {
+        return {
+            x: request.anchor.x - request.label.width / 2,
+            y: request.anchor.y - gap - request.label.height,
+            width: request.label.width,
+            height: request.label.height,
+        };
+    }
+    /**
+     * The candidates in the fixed try-order: previous · above · below · right · left (each kept inside the viewport
+     * along its free axis) · then clear of each protected area and each earlier label (above / below / left / right).
+     */
+    static candidates(request, gap) {
+        const width = request.label.width;
+        const height = request.label.height;
+        const anchor = request.anchor;
+        const vp = request.viewport;
+        /** A label-sized rectangle at a top-left corner. */
+        const rect = (x, y) => ({ x: x, y: y, width: width, height: height });
+        // centred on the anchor along the free axis, but kept on screen
+        const centredX = DyFM_LabelPlacement_Util.clamp(anchor.x - width / 2, vp.x, vp.x + vp.width - width);
+        const centredY = DyFM_LabelPlacement_Util.clamp(anchor.y - height / 2, vp.y, vp.y + vp.height - height);
+        const list = [];
+        if (request.previous) {
+            list.push({ rect: rect(request.previous.x, request.previous.y), side: 'previous' });
+        }
+        list.push({ rect: rect(centredX, anchor.y - gap - height), side: 'above' }, { rect: rect(centredX, anchor.y + gap), side: 'below' }, { rect: rect(anchor.x + gap, centredY), side: 'right' }, { rect: rect(anchor.x - gap - width, centredY), side: 'left' });
+        const blockers = [
+            ...(request.exclusions ?? []).map((each) => each.rect),
+            ...(request.occupied ?? []),
+        ];
+        for (const blocker of blockers) {
+            list.push({ rect: rect(centredX, blocker.y - gap - height), side: 'clear-of-exclusion' }, { rect: rect(centredX, blocker.y + blocker.height + gap), side: 'clear-of-exclusion' }, { rect: rect(blocker.x - gap - width, centredY), side: 'clear-of-exclusion' }, { rect: rect(blocker.x + blocker.width + gap, centredY), side: 'clear-of-exclusion' });
+        }
+        return list;
+    }
+    /** The ids of the protected areas a rectangle would cover (attribution — why a label moved). */
+    static blockingIds(rect, exclusions, gap) {
+        return exclusions
+            .filter((each) => DyFM_LabelPlacement_Util.intersects(rect, each.rect, gap))
+            .map((each) => each.id);
+    }
+    /** A value kept between `min` and `max`. */
+    static clamp(value, min, max) {
+        return Math.min(Math.max(value, min), max);
+    }
+    /** Whether every value is a finite number. */
+    static allFinite(...values) {
+        return values.every((value) => Number.isFinite(value));
+    }
+    /** Whether a rectangle is present, finite, and has a non-negative size. */
+    static isFiniteRect(rect) {
+        return !!rect && DyFM_LabelPlacement_Util.allFinite(rect.x, rect.y, rect.width, rect.height)
+            && rect.width >= 0 && rect.height >= 0;
+    }
+    /** Whether the rectangle lies fully inside the viewport. */
+    static inside(rect, vp) {
+        return rect.x >= vp.x && rect.y >= vp.y && rect.x + rect.width <= vp.x + vp.width
+            && rect.y + rect.height <= vp.y + vp.height;
+    }
+    /** The distance between two rectangle centres. */
+    static centreDistance(a, b) {
+        return Math.hypot((a.x + a.width / 2) - (b.x + b.width / 2), (a.y + a.height / 2) - (b.y + b.height / 2));
+    }
+    /** The first invalid input, as a readable reason; `null` when the geometry is usable. */
+    static findInvalidGeometry(request) {
+        const finite = DyFM_LabelPlacement_Util.allFinite;
+        const finiteRect = DyFM_LabelPlacement_Util.isFiniteRect;
+        if (!request?.anchor || !finite(request.anchor.x, request.anchor.y)) {
+            return 'the anchor must be a finite point';
+        }
+        if (!request.label || !finite(request.label.width, request.label.height)
+            || !(request.label.width > 0) || !(request.label.height > 0)) {
+            return 'the label needs a measured, positive size';
+        }
+        if (!finiteRect(request.viewport) || !(request.viewport.width > 0) || !(request.viewport.height > 0)) {
+            return 'the viewport needs a finite, positive size';
+        }
+        if (request.gap !== undefined && (!finite(request.gap) || request.gap < 0)) {
+            return 'the gap must be a finite, non-negative number';
+        }
+        const badExclusion = (request.exclusions ?? [])
+            .find((each) => !each?.id || !finiteRect(each.rect));
+        if (badExclusion) {
+            return `the protected area "${badExclusion?.id ?? '?'}" needs an id and a finite, non-negative rectangle`;
+        }
+        if ((request.occupied ?? []).some((each) => !finiteRect(each))) {
+            return 'every occupied rectangle must be finite and non-negative';
+        }
+        if (request.previous && !finite(request.previous.x, request.previous.y)) {
+            return 'the previous position must be a finite point';
+        }
+        return null;
+    }
+}

package/build-esm/_modules/game/_models/label-placement.interface.js

@@ -0,0 +1 @@
+export {};

package/build-esm/_modules/game/index.js

@@ -20,6 +20,7 @@ export * from './_models/work-order-scheduler.control-model';
 export * from './_models/build-reservation.interface';
 export * from './_models/viewport.interface';
 export * from './_models/viewport.control-model';
+export * from './_models/label-placement.interface';
 export * from './_models/input-action.interface';
 export * from './_models/input-action-registry.control-model';
 export * from './_models/guided-onboarding.interface';
@@ -31,3 +32,4 @@ export * from './_collections/audio-mixer.util';
 export * from './_collections/audio-scale.util';
 export * from './_collections/game-save.util';
 export * from './_collections/build-reservation.util';
+export * from './_collections/label-placement.util';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/fsm-dynamo",
-  "version": "1.20.120",
+  "version": "1.20.122",
   "description": "Full Stack Model Collection for Dynamic (NodeJS-Typescript) Framework called Dynamo, by Future Development Ltd.",
   "DyBu_settings": {
     "packageType": "full-stack-package",
@@ -371,7 +371,7 @@
     "uuid": "~11.1.1"
   },
   "devDependencies": {
-    "@futdevpro/dynamo-eslint": "1.20.57",
+    "@futdevpro/dynamo-eslint": "1.20.65",
     "@types/jasmine": "~4.3.5",
     "@typescript-eslint/eslint-plugin": "^8.41.0",
     "@typescript-eslint/parser": "^8.41.0",