@ksp-gonogo/kerbcast-react 1.11.1 → 1.12.0-rc.2

package/README.md

@@ -82,6 +82,18 @@ cannot loop with the request. A resize within about a second of the stream
 changing that matches its new shape counts as following it. Layout changes
 outside that window always report.
 
+The feed frame (the element fullscreen targets) carries two attributes for
+hosts and tests:
+
+- `data-kc-signal`: `live`, `stalled` (no frame has left the decoder for
+  half a second, or none yet since the source attached) or `none` (no
+  source). It is measured after any encoded transform the host installs, so
+  a transform that holds frames back shows as `stalled` while it holds them.
+  The video keeps presenting frames while it shows static, so its frame
+  counts cannot tell a picture from static, and inbound-rtp `framesDecoded`
+  averaged over seconds misses gaps this short; this attribute can
+- `data-fullscreen`: present while the feed is fullscreen
+
 An imperative `CameraFeedHandle` (via `ref`) exposes `stepCamera`,
 `setPanAxis`, `setZoomRate`, `nudgePan`, and `nudgeZoom` for wiring feeds
 to a gamepad or keyboard.
@@ -92,6 +104,65 @@ while a camera is tracking. `cameraFilter` narrows the selectable cameras
 (picker, stepper, auto-latch). `showActions={false}` hides the whole action
 bar without affecting resolution reporting.
 
+## Anchored markers
+
+`anchors` marks things in the game on the feed's picture (see the core
+SDK's "Anchored markers" for the kinds and fields). The feed sets them on
+the camera it shows, clears them when it moves on or unmounts, and draws a
+marker where each one lands in every displayed frame: four corner marks
+sized from `apparentRadiusPx` (never below 14 px), green when clear, red and
+dashed when occluded.
+
+`anchorOverlay` has the same shape as `targetBracketOverlay`: `corners`
+restyles the four marks (`top`, `right`, `bottom`, `left`, each
+`{ colour, dashed, hidden, shape }`), `render` adds SVG in screen pixels,
+`readout` puts text under the marker, and `shape` sets every mark to
+`"corners"` or `"triangles"`. Each is called per anchor with the raw result
+and a context: its screen geometry, the fitted content rect, the displayed
+frame's UT and the screen position of every drawn anchor. `owners` also
+draws anchors set in game by those owners. What a colour means is yours to
+decide; Kerbcast only reports geometry.
+
+A direction reticle on a docking port: four triangles, each side coloured
+from the port's axes.
+
+```tsx
+const anchors = useMemo(
+  () => [{ id: "port", kind: AnchorKind.Part, vessel: targetPid, part: portPid, orientation: true }],
+  [targetPid, portPid],
+);
+
+<CameraFeed
+  flightId={dockingCam}
+  anchors={anchors}
+  anchorOverlay={{
+    shape: "triangles",
+    corners: (a) => {
+      /* The port faces the lens along -z; tilt shows in its forward's x and y. */
+      const [fx = 0, fy = 0] = a.forward ?? [];
+      const side = (off: number) => ({ colour: Math.abs(off) < 0.02 ? "lime" : "orange" });
+      return { top: side(fy), bottom: side(fy), left: side(fx), right: side(fx) };
+    },
+    readout: (a) => (a.distanceM != null ? `${a.distanceM.toFixed(1)} m` : null),
+  }}
+/>
+```
+
+For a video of your own, `AnchorMarkers` draws a frame's anchors over any
+`<video>` and `useDisplayedFrame(enabled, flightId, video)` gives the
+displayed frame with its results.
+
+On command feeds the target brackets follow the subject's anchor while it
+is visible and no command lock is held, so the box stays on the craft where
+the picture shows it even while an aim points elsewhere. With the craft out
+of frame or occluded, or under the lock, the box is the 1.11 one: centred on
+the aim, sized from the aimed range, red and dashed when the aim line is
+occluded. `targetBracketOverlay` is unchanged; its context gains `subject`,
+the observed anchor, so you can draw it as a second mark.
+
+An observed anchor out of view (see the core SDK) carries no position and
+draws no marker; it is still in `ctx.frame.anchors`.
+
 ## `KerbalFaceFeed`
 
 A single-kerbal face-camera primitive: one crew face in a square frame, keyed

package/dist/AnchorMarkers.d.ts

@@ -0,0 +1,128 @@
+import { type DisplayedFrameUt, type FittedFrame, type FrameAnchor, type FrameFit, type FrameUtSource } from "@ksp-gonogo/kerbcast";
+import { type ReactNode } from "react";
+/** Default colours; each is overridable through the named CSS custom property. */
+export declare const ANCHOR_MARKER_COLOURS: {
+    readonly clear: "var(--kerbcast-anchor-clear, #4caf50)";
+    readonly occluded: "var(--kerbcast-anchor-occluded, #f44336)";
+};
+/** The four marks around an anchor, clockwise from the top. */
+export type AnchorCorner = "top" | "right" | "bottom" | "left";
+/**
+ * How a mark is drawn. `corners`: a right-angle corner of a box around the
+ * anchor, like the command brackets; each key names the corner that starts
+ * its side going clockwise, so `top` is the top left, `right` the top right,
+ * `bottom` the bottom right and `left` the bottom left. `triangles`: a
+ * triangle outside the box on that side, pointing at the anchor.
+ */
+export type AnchorMarkerShape = "corners" | "triangles";
+export interface AnchorCornerStyle {
+    colour: string;
+    dashed: boolean;
+    shape: AnchorMarkerShape;
+}
+/** Changes to one default mark; unset fields keep the default. */
+export interface AnchorCornerOverride {
+    colour?: string;
+    dashed?: boolean;
+    hidden?: boolean;
+    shape?: AnchorMarkerShape;
+}
+export type AnchorCornerOverrides = Partial<Record<AnchorCorner, AnchorCornerOverride>>;
+/** The marker box for one anchor, in the overlay SVG's pixels (the video element's box). */
+export interface AnchorMarkerGeometry {
+    /** Where the anchor is on screen. Off the box when it is out of frame. */
+    cx: number;
+    cy: number;
+    /** Half the box side: the anchor's apparent radius on screen, never below a minimum. */
+    half: number;
+    /** Length of each corner stroke, and the side of each triangle. */
+    arm: number;
+    stroke: number;
+}
+/** An anchor with its place on screen. */
+export interface PlacedAnchor {
+    anchor: FrameAnchor;
+    x: number;
+    y: number;
+}
+/** Everything an anchor overlay needs to line up with the drawn markers. */
+export interface AnchorContext {
+    geometry: AnchorMarkerGeometry;
+    /** Where the frame lands in the element, after `object-fit`. */
+    content: FittedFrame;
+    /** Size of the overlay SVG, the video element's box. */
+    width: number;
+    height: number;
+    /** Mission UT of the displayed frame the anchors describe. */
+    displayUt: number;
+    utSource: FrameUtSource;
+    /** Every drawn anchor in this frame with its screen position. */
+    anchors: readonly PlacedAnchor[];
+    /** The displayed frame, with its raw per-frame results and size. */
+    frame: DisplayedFrameUt;
+}
+/**
+ * Consumer changes to a feed's anchor markers. Each part is optional and is
+ * called for every drawn anchor on every displayed frame. What an anchor
+ * means, and which colour says so, is the consumer's: Kerbcast only reports
+ * where it is.
+ */
+export interface AnchorOverlay {
+    /** Default shape of every mark. Default `"corners"`. */
+    shape?: AnchorMarkerShape;
+    /** Restyle or hide the four marks of one anchor. */
+    corners?: AnchorCornerOverrides | ((anchor: FrameAnchor, ctx: AnchorContext) => AnchorCornerOverrides | null | undefined);
+    /**
+     * SVG content drawn above the marks, in the same pixel space. Runs for an
+     * anchor out of frame or behind the lens too (its marks are left out then),
+     * so an overlay can point to it from the edge. An observed result out of
+     * view carries no position and is not drawn at all; it is still in
+     * `ctx.frame.anchors`.
+     */
+    render?: (anchor: FrameAnchor, ctx: AnchorContext) => ReactNode;
+    /** Text under the marker, or null for none. Default none. */
+    readout?: (anchor: FrameAnchor, ctx: AnchorContext) => string | null;
+    /**
+     * Game-side owners whose anchors are drawn as well as this client's own,
+     * e.g. `["my-mod"]`. Default: only this client's.
+     */
+    owners?: readonly string[];
+    /**
+     * Draw Kerbcast's own `aim` anchor too when `"kerbcast"` is among
+     * `owners`. Off by default: the brackets already mark the aim.
+     */
+    showAim?: boolean;
+}
+/** The marker box for an anchor at `centre` with `radiusPx` capture pixels on a `frameHeight`-tall frame. */
+export declare function anchorMarkerGeometry(centre: {
+    x: number;
+    y: number;
+}, radiusPx: number, frameHeight: number, content: FittedFrame): AnchorMarkerGeometry;
+export interface AnchorMarkersProps {
+    /** The displayed frame whose anchors to draw. */
+    frame: DisplayedFrameUt | null;
+    video: HTMLVideoElement | null;
+    overlay?: AnchorOverlay | null;
+    /** How the video fits its box. Default: read from the element's CSS. */
+    fit?: FrameFit;
+}
+/**
+ * Markers for the anchors in one displayed frame: by default four corner
+ * marks around each anchor sized from its apparent radius, green when clear
+ * and red and dashed when occluded. Positions come from the frame's own
+ * stamp, so they match the picture under any delay.
+ */
+export declare function AnchorMarkers({ frame, video, overlay, fit }: AnchorMarkersProps): import("react").JSX.Element | null;
+/**
+ * The displayed frame of `flightId` on `video`, re-rendering on every
+ * presented frame while `enabled`. Kept to the component that draws from it,
+ * so a feed's other UI does not re-render at the frame rate.
+ */
+export declare function useDisplayedFrame(enabled: boolean, flightId: number | null, video: HTMLVideoElement | null): DisplayedFrameUt | null;
+/** Self-subscribing markers for a feed: watches its displayed frames and draws their anchors. */
+export declare function LiveAnchorMarkers({ flightId, video, overlay, fit, }: {
+    flightId: number | null;
+    video: HTMLVideoElement | null;
+    overlay?: AnchorOverlay | null;
+    fit?: FrameFit;
+}): import("react").JSX.Element;

package/dist/AnchorMarkers.js

@@ -0,0 +1,162 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { COMMAND_AIM_ANCHOR_ID, KERBCAST_ANCHOR_OWNER, anchorPoint, fitFrame, frameToScreen, } from "@ksp-gonogo/kerbcast";
+import { useEffect, useState } from "react";
+import styled from "styled-components";
+import { useKerbcastClient } from "./context";
+import { useVideoBox, videoFit } from "./videoBox";
+const MARKER_STROKE_PX = 2;
+const MARKER_MIN_HALF_PX = 14;
+const MARKER_ARM_FRACTION = 0.3;
+const MARKER_MIN_ARM_PX = 6;
+const READOUT_GAP_PX = 11;
+/** Default colours; each is overridable through the named CSS custom property. */
+export const ANCHOR_MARKER_COLOURS = {
+    clear: "var(--kerbcast-anchor-clear, #4caf50)",
+    occluded: "var(--kerbcast-anchor-occluded, #f44336)",
+};
+/** The marker box for an anchor at `centre` with `radiusPx` capture pixels on a `frameHeight`-tall frame. */
+export function anchorMarkerGeometry(centre, radiusPx, frameHeight, content) {
+    const scale = frameHeight > 0 ? content.height / frameHeight : 1;
+    const half = Math.max(MARKER_MIN_HALF_PX, radiusPx * scale);
+    const arm = Math.max(MARKER_MIN_ARM_PX, MARKER_ARM_FRACTION * half * 2);
+    return { cx: centre.x, cy: centre.y, half, arm, stroke: MARKER_STROKE_PX };
+}
+const CORNERS = ["top", "right", "bottom", "left"];
+/** SVG path data for one mark. Corners are open strokes; triangles are closed. */
+function markPath(corner, shape, g) {
+    const { cx, cy, half: h, arm: a } = g;
+    if (shape === "triangles") {
+        const t = a * 0.8;
+        const w = a / 2;
+        switch (corner) {
+            case "top":
+                return `M${cx} ${cy - h}L${cx - w} ${cy - h - t}L${cx + w} ${cy - h - t}Z`;
+            case "right":
+                return `M${cx + h} ${cy}L${cx + h + t} ${cy - w}L${cx + h + t} ${cy + w}Z`;
+            case "bottom":
+                return `M${cx} ${cy + h}L${cx + w} ${cy + h + t}L${cx - w} ${cy + h + t}Z`;
+            default:
+                return `M${cx - h} ${cy}L${cx - h - t} ${cy + w}L${cx - h - t} ${cy - w}Z`;
+        }
+    }
+    const l = cx - h, r = cx + h, tp = cy - h, b = cy + h;
+    switch (corner) {
+        case "top":
+            return `M${l} ${tp + a}L${l} ${tp}L${l + a} ${tp}`;
+        case "right":
+            return `M${r - a} ${tp}L${r} ${tp}L${r} ${tp + a}`;
+        case "bottom":
+            return `M${r} ${b - a}L${r} ${b}L${r - a} ${b}`;
+        default:
+            return `M${l + a} ${b}L${l} ${b}L${l} ${b - a}`;
+    }
+}
+/** Whether a feed shows this anchor: this client's own, or one from a listed owner, Kerbcast's aim only on request. */
+function drawn(a, overlay) {
+    if (a.owner === undefined)
+        return true;
+    if (a.owner === KERBCAST_ANCHOR_OWNER && a.id === COMMAND_AIM_ANCHOR_ID && !overlay?.showAim)
+        return false;
+    return overlay?.owners?.includes(a.owner) ?? false;
+}
+/**
+ * Markers for the anchors in one displayed frame: by default four corner
+ * marks around each anchor sized from its apparent radius, green when clear
+ * and red and dashed when occluded. Positions come from the frame's own
+ * stamp, so they match the picture under any delay.
+ */
+export function AnchorMarkers({ frame, video, overlay, fit }) {
+    const { boxW, boxH, mediaW, mediaH } = useVideoBox(video);
+    if (!frame?.anchors?.length)
+        return null;
+    const frameW = frame.frameWidth || mediaW;
+    const frameH = frame.frameHeight || mediaH;
+    if (!(frameW > 0 && frameH > 0 && boxW > 0 && boxH > 0))
+        return null;
+    const content = fitFrame(boxW, boxH, frameW, frameH, fit ?? videoFit(video));
+    /* An observed result out of view has no position, so it has no marker. */
+    const placed = [];
+    for (const a of frame.anchors) {
+        const point = drawn(a, overlay) ? anchorPoint(a) : null;
+        if (point)
+            placed.push({ anchor: a, ...frameToScreen(point, frameW, frameH, content) });
+    }
+    if (placed.length === 0)
+        return null;
+    const shape = overlay?.shape ?? "corners";
+    const items = placed.map(({ anchor, x, y }) => {
+        const geometry = anchorMarkerGeometry({ x, y }, anchor.apparentRadiusPx ?? 0, frameH, content);
+        const ctx = {
+            geometry,
+            content,
+            width: boxW,
+            height: boxH,
+            displayUt: frame.ut,
+            utSource: frame.source,
+            anchors: placed,
+            frame,
+        };
+        const overrides = typeof overlay?.corners === "function" ? overlay.corners(anchor, ctx) : overlay?.corners;
+        const base = anchor.occluded
+            ? { colour: ANCHOR_MARKER_COLOURS.occluded, dashed: true, shape }
+            : { colour: ANCHOR_MARKER_COLOURS.clear, dashed: false, shape };
+        const visible = anchor.inFrame && !anchor.behind;
+        const readout = overlay?.readout ? overlay.readout(anchor, ctx) : null;
+        return { anchor, geometry, ctx, overrides, base, visible, readout };
+    });
+    return (_jsxs(_Fragment, { children: [_jsx(MarkerSvg, { "aria-hidden": "true", "data-anchor-markers": "", width: boxW, height: boxH, children: items.map(({ anchor, geometry, ctx, overrides, base, visible }) => (_jsxs("g", { "data-anchor": anchor.id, "data-owner": anchor.owner, children: [visible &&
+                            CORNERS.map((corner) => {
+                                const o = overrides?.[corner];
+                                if (o?.hidden)
+                                    return null;
+                                const s = o?.shape ?? base.shape;
+                                const colour = o?.colour ?? base.colour;
+                                const dashed = o?.dashed ?? base.dashed;
+                                const filled = s === "triangles";
+                                return (_jsx("path", { "data-corner": corner, "data-shape": s, d: markPath(corner, s, geometry), strokeWidth: geometry.stroke, strokeDasharray: dashed ? "3 2" : undefined, style: filled ? { fill: dashed ? "none" : colour, stroke: colour } : { fill: "none", stroke: colour } }, corner));
+                            }), overlay?.render && _jsx("g", { "data-anchor-overlay": "", children: overlay.render(anchor, ctx) })] }, `${anchor.owner ?? ""}/${anchor.id}`))) }), items.map(({ anchor, geometry, readout, visible }) => readout &&
+                visible && (_jsx(Readout, { "data-anchor-readout": anchor.id, style: { left: geometry.cx, top: geometry.cy + geometry.half + READOUT_GAP_PX }, children: readout }, `${anchor.owner ?? ""}/${anchor.id}`)))] }));
+}
+/**
+ * The displayed frame of `flightId` on `video`, re-rendering on every
+ * presented frame while `enabled`. Kept to the component that draws from it,
+ * so a feed's other UI does not re-render at the frame rate.
+ */
+export function useDisplayedFrame(enabled, flightId, video) {
+    const client = useKerbcastClient();
+    const [frame, setFrame] = useState(null);
+    useEffect(() => {
+        setFrame(null);
+        if (!enabled || flightId === null || !video)
+            return;
+        return client.watchDisplayedFrames(flightId, video, (f) => 
+        /* Skip re-renders between frames that carry the same results. */
+        setFrame((prev) => prev && prev.anchors === f.anchors && prev.rtpTimestamp === f.rtpTimestamp ? prev : f));
+    }, [client, enabled, flightId, video]);
+    return frame;
+}
+/** Self-subscribing markers for a feed: watches its displayed frames and draws their anchors. */
+export function LiveAnchorMarkers({ flightId, video, overlay, fit, }) {
+    const frame = useDisplayedFrame(true, flightId, video);
+    return _jsx(AnchorMarkers, { frame: frame, video: video, overlay: overlay, fit: fit });
+}
+const MarkerSvg = styled.svg `
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: 1;
+  overflow: visible;
+  pointer-events: none;
+`;
+const Readout = styled.div `
+  position: absolute;
+  z-index: 1;
+  transform: translateX(-50%);
+  white-space: nowrap;
+  color: #fff;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.12em;
+  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.9);
+  pointer-events: none;
+`;

package/dist/CameraFeed.d.ts

@@ -1,6 +1,7 @@
-import type { CameraState, KerbcastClient } from "@ksp-gonogo/kerbcast";
+import type { Anchor, CameraState, DisplayedFrameUt, KerbcastClient } from "@ksp-gonogo/kerbcast";
 import { type FeedAction } from "./FeedActionBar";
 import { type CommandBracketOverlay } from "./CommandBrackets";
+import { type AnchorOverlay } from "./AnchorMarkers";
 /**
  * The consumer-supplied action shape, and the shared top-right action bar
  * both `CameraFeed` and `KerbalFaceFeed` render, live in `FeedActionBar`.
@@ -150,8 +151,9 @@ export interface CameraFeedProps {
     enableRecording?: boolean;
     /**
      * Record this feed at the operator's full render size for the duration of
-     * the built-in REC control's recording (overrides only the display-size
-     * demand; still yields to the adaptive framerate shed). Off by default.
+     * the built-in REC control's recording (overrides the display-size
+     * demand and any viewer quality preset; still capped by an operator
+     * render-size cap and the adaptive shed). Off by default.
      * Threaded straight into `start(flightId, { forceFullResolution })`; has
      * no effect unless `enableRecording` is also set. While the feed is armed
      * (force sent, waiting for the resolution bump) the tile shows an
@@ -199,14 +201,53 @@ export interface CameraFeedProps {
      * brackets. See {@link CommandBracketOverlay}.
      */
     targetBracketOverlay?: CommandBracketOverlay;
+    /**
+     * What a command camera feed says while the camera has no subject to aim
+     * at yet and shows its placeholder framing (a launch site camera on its
+     * pad, a station looking at the horizon). Drawn over the picture, never
+     * into the video, so recordings stay clean. Default "Waiting for target";
+     * `null` or an empty string shows nothing.
+     */
+    waitingForTargetLabel?: string | null;
+    /**
+     * What the feed says while its camera has no video slot on this connection
+     * (`KerbcastCameraHandle.waitingForSlot`): the pool is at its ceiling or
+     * cannot grow. The feed takes the next slot another feed gives up. Drawn
+     * over the picture; `null` or an empty string shows nothing.
+     */
+    noSlotLabel?: string | null;
     /**
      * Mission UT the displayed video was captured at, for a host running its
      * own delayed playout. Picks which command-track transition is in force and
      * ages the readout. Defaults to the displayed frame's own capture UT where
      * the browser reports frame RTP timestamps, else the client's capture
-     * clock interpolated to now.
+     * clock interpolated to now. While a command lock is held the brackets and
+     * readout come from the displayed frame's own state, which a UT alone does
+     * not carry: such a host passes `displayFrame` instead.
      */
     displayUt?: number;
+    /**
+     * The frame a host's own delayed playout is showing, as
+     * `watchDisplayedFrames` reported it when it arrived. Wins over
+     * `displayUt`: its `ut` picks the transition in force and its `command`
+     * draws the brackets and readout, so they never run ahead of the picture.
+     */
+    displayFrame?: DisplayedFrameUt | null;
+    /**
+     * Things to mark on this feed's picture: parts, craft, points on a body or
+     * directions. Set for the displayed camera as this client's anchors and
+     * cleared when the feed shows another camera or unmounts; the game
+     * projects each through the camera that rendered every frame, and a
+     * default marker is drawn where it lands. One set per camera per client:
+     * two feeds on the same camera share it, the last to set winning. At
+     * most 16. Pass a stable or memoised array; it is compared by value.
+     */
+    anchors?: Anchor[];
+    /**
+     * Restyle the anchor markers, add SVG of your own, put text under them,
+     * or draw anchors set in game too. See {@link AnchorOverlay}.
+     */
+    anchorOverlay?: AnchorOverlay;
 }
 export interface CameraFeedHandle {
     stepCamera(delta: number): void;