@synnaxlabs/x 0.54.2 → 0.56.0

package/src/spatial/types.gen.ts

@@ -11,10 +11,56 @@
 
 import { z } from "zod";
 
+import { type numeric } from "@/numeric";
+
+export const X_LOCATIONS = ["left", "right"] as const;
+export const xLocationZ = z.enum(X_LOCATIONS);
+export type XLocation = z.infer<typeof xLocationZ>;
+
+export const Y_LOCATIONS = ["top", "bottom"] as const;
+export const yLocationZ = z.enum(Y_LOCATIONS);
+export type YLocation = z.infer<typeof yLocationZ>;
+
+export const STICKY_UNITS = ["px", "decimal"] as const;
+export const stickyUnitZ = z.enum(STICKY_UNITS);
+export type StickyUnit = z.infer<typeof stickyUnitZ>;
+
 export const OUTER_LOCATIONS = ["top", "right", "bottom", "left"] as const;
 export const outerLocationZ = z.enum(OUTER_LOCATIONS);
 export type OuterLocation = z.infer<typeof outerLocationZ>;
 
+export const DIRECTIONS = ["x", "y"] as const;
+export const directionZ = z.enum(DIRECTIONS);
+export type Direction = z.infer<typeof directionZ>;
+
+export const ANGULAR_DIRECTIONS = ["clockwise", "counterclockwise"] as const;
+export const angularDirectionZ = z.enum(ANGULAR_DIRECTIONS);
+export type AngularDirection = z.infer<typeof angularDirectionZ>;
+
+export const CENTER_LOCATIONS = ["center"] as const;
+export const centerLocationZ = z.enum(CENTER_LOCATIONS);
+export type CenterLocation = z.infer<typeof centerLocationZ>;
+
+export const LOCATIONS = ["top", "right", "bottom", "left", "center"] as const;
+export const locationZ = z.enum(LOCATIONS);
+export type Location = z.infer<typeof locationZ>;
+
+export const ALIGNMENTS = ["start", "center", "end"] as const;
+export const alignmentZ = z.enum(ALIGNMENTS);
+export type Alignment = z.infer<typeof alignmentZ>;
+
+export const ORDERS = ["first", "last"] as const;
+export const orderZ = z.enum(ORDERS);
+export type Order = z.infer<typeof orderZ>;
+
+export const DIMENSIONS = ["width", "height"] as const;
+export const dimensionZ = z.enum(DIMENSIONS);
+export type Dimension = z.infer<typeof dimensionZ>;
+
+export const SIGNED_DIMENSIONS = ["signedWidth", "signedHeight"] as const;
+export const signedDimensionZ = z.enum(SIGNED_DIMENSIONS);
+export type SignedDimension = z.infer<typeof signedDimensionZ>;
+
 /**
  * XY is a 2D coordinate point with x and y values. Used for positioning
  * elements in two-dimensional space.
@@ -26,3 +72,97 @@ export const xyZ = z.object({
   y: z.number(),
 });
 export interface XY extends z.infer<typeof xyZ> {}
+
+/** CornerLocation is an anchor corner for positioning. */
+export const cornerLocationZ = z.object({
+  /** x is the horizontal anchor. */
+  x: xLocationZ,
+  /** y is the vertical anchor. */
+  y: yLocationZ,
+});
+export interface CornerLocation extends z.infer<typeof cornerLocationZ> {}
+
+/** StickyUnits specifies the measurement units for sticky positioning. */
+export const stickyUnitsZ = z.object({
+  /** x is the horizontal unit. */
+  x: stickyUnitZ,
+  /** y is the vertical unit. */
+  y: stickyUnitZ,
+});
+export interface StickyUnits extends z.infer<typeof stickyUnitsZ> {}
+
+/** Dimensions is a 2D size with width and height values. */
+export const dimensionsZ = z.object({
+  /** width is the width in pixels. */
+  width: z.number(),
+  /** height is the height in pixels. */
+  height: z.number(),
+});
+export interface Dimensions extends z.infer<typeof dimensionsZ> {}
+
+/**
+ * SignedDimensions is a 2D size whose width and height components carry sign, allowing
+ * negative values to express direction.
+ */
+export const signedDimensionsZ = z.object({
+  /** signedWidth is the signed width. */
+  signedWidth: z.number(),
+  /** signedHeight is the signed height. */
+  signedHeight: z.number(),
+});
+export interface SignedDimensions extends z.infer<typeof signedDimensionsZ> {}
+
+/**
+ * ClientXY is a 2D coordinate point expressed in client (viewport) space, matching
+ * the shape of DOM mouse events.
+ */
+export const clientXYZ = z.object({
+  /** clientX is the horizontal coordinate in client (viewport) space. */
+  clientX: z.number(),
+  /** clientY is the vertical coordinate in client (viewport) space. */
+  clientY: z.number(),
+});
+export interface ClientXY extends z.infer<typeof clientXYZ> {}
+
+/**
+ * Bounds is a closed-open interval [lower, upper) over an ordered numeric value
+ * space. The TypeScript binding is generic over T so callers can express
+ * bounds over either number or bigint values; other languages emit a
+ * concrete float64-based type.
+ */
+export const boundsZ = <T extends numeric.Value = number>(t?: z.ZodType<T>) =>
+  z.object({
+    /** lower is the inclusive lower bound. */
+    lower: t ?? z.number(),
+    /** upper is the exclusive upper bound. */
+    upper: t ?? z.number(),
+  });
+export interface Bounds<T extends numeric.Value = number> {
+  lower: T;
+  upper: T;
+}
+
+/** Viewport is the camera state of a viewport. */
+export const viewportZ = z.object({
+  /** zoom is the zoom level where 1.0 equals 100%. */
+  zoom: z.number().default(1),
+  /** position is the (x, y) pan offset of the viewport. */
+  position: xyZ,
+});
+export interface Viewport extends z.infer<typeof viewportZ> {}
+
+/**
+ * StickyXY is a position that can be anchored to different corners of a
+ * container with configurable units (pixels or decimal fractions).
+ */
+export const stickyXYZ = z.object({
+  /** x is the horizontal coordinate. */
+  x: z.number(),
+  /** y is the vertical coordinate. */
+  y: z.number(),
+  /** root is the optional anchor corner for the position. */
+  root: cornerLocationZ.optional(),
+  /** units is the optional unit specification for the coordinates. */
+  units: stickyUnitsZ.optional(),
+});
+export interface StickyXY extends z.infer<typeof stickyXYZ> {}

package/src/spatial/xy/xy.ts

@@ -12,19 +12,19 @@ import { z } from "zod";
 import {
   type AngularDirection,
   type ClientXY,
-  clientXyZ,
-  type CrudeDirection,
+  clientXYZ,
   dimensionsZ,
   type Direction,
   type NumberCouple,
   numberCouple,
   signedDimensionsZ,
+  type XY,
+  xyZ,
 } from "@/spatial/base";
-import { direction as dir } from "@/spatial/direction";
+import { direction as dir, type direction } from "@/spatial/direction";
 import { type location } from "@/spatial/location";
-import { type XY, xyZ } from "@/spatial/types.gen";
 
-export { type ClientXY as Client, clientXyZ, type XY, xyZ };
+export { type ClientXY as Client, clientXYZ, type XY, xyZ };
 
 /** A crude representation of a {@link XY} coordinate as a zod schema. */
 export const crudeZ = z.union([
@@ -33,7 +33,7 @@ export const crudeZ = z.union([
   numberCouple,
   dimensionsZ,
   signedDimensionsZ,
-  clientXyZ,
+  clientXYZ,
 ]);
 
 /** A crude representation of a {@link XY} coordinate. */
@@ -141,7 +141,7 @@ export const translate: Translate = (a, b, v, ...cb): XY => {
  * @returns the given coordinate the given direction set to the given value.
  * @example set({ x: 1, y: 2 }, "x", 3) // { x: 3, y: 2 }
  */
-export const set = (c: Crude, direction: CrudeDirection, value: number): XY => {
+export const set = (c: Crude, direction: direction.Crude, value: number): XY => {
   const xy = construct(c);
   const d = dir.construct(direction);
   if (d === "x") return { x: value, y: xy.y };

package/src/status/status.spec.ts

@@ -448,4 +448,69 @@ describe("status", () => {
       });
     });
   });
+
+  describe("toError", () => {
+    it("should use the wrapped status message as the Error message", () => {
+      const inner = new Error("raw");
+      const s = status.fromException(inner, "Failed to fetch");
+      const err = status.toError(s);
+
+      expect(err.message).toBe("Failed to fetch");
+    });
+
+    it("should copy name from the inner error", () => {
+      class NotFoundError extends Error {
+        constructor(message: string) {
+          super(message);
+          this.name = "NotFoundError";
+        }
+      }
+      const inner = new NotFoundError("missing");
+      const s = status.fromException(inner, "Failed to fetch");
+      const err = status.toError(s);
+
+      expect(err.name).toBe("NotFoundError");
+    });
+
+    it("should copy stack from the inner error", () => {
+      const inner = new Error("raw");
+      inner.stack = "Error: raw\n    at someFn (file.ts:1:1)";
+      const s = status.fromException(inner, "Failed to fetch");
+      const err = status.toError(s);
+
+      expect(err.stack).toBe("Error: raw\n    at someFn (file.ts:1:1)");
+    });
+
+    it("should not leak the toError call-site stack when inner stack is missing", () => {
+      const inner = new Error("raw");
+      inner.stack = undefined;
+      const s = status.fromException(inner, "Failed to fetch");
+      const err = status.toError(s);
+
+      expect(err.stack).toBeUndefined();
+    });
+
+    it("should set cause to the original status", () => {
+      const inner = new Error("raw");
+      const s = status.fromException(inner, "Failed to fetch");
+      const err = status.toError(s);
+
+      expect(err.cause).toBe(s);
+    });
+
+    it("should round-trip through throw/catch", () => {
+      const inner = new TypeError("not a function");
+      const s = status.fromException(inner, "Failed to invoke");
+
+      try {
+        throw status.toError(s);
+      } catch (caught) {
+        expect(caught).toBeInstanceOf(Error);
+        const e = caught as Error;
+        expect(e.name).toBe("TypeError");
+        expect(e.message).toBe("Failed to invoke");
+        expect(e.cause).toBe(s);
+      }
+    });
+  });
 });

package/src/status/status.ts

@@ -97,6 +97,26 @@ export const fromException = (
   return create<typeof exceptionDetailsSchema, "error">(crude);
 };
 
+/**
+ * Converts an exception-shaped status (one built via {@link fromException}) back
+ * into a thrown-shaped {@link Error}. The returned error carries the status's
+ * wrapped message, copies `name` and `stack` from the inner error preserved on
+ * `details.error`, and stashes the full status on `cause` for callers that need
+ * the rich shape.
+ *
+ * Use this when bridging the status pipeline back into a context that expects
+ * a real Error — typically before `throw`-ing across an error boundary.
+ */
+export const toError = (
+  s: Status<typeof exceptionDetailsSchema, z.ZodLiteral<"error">>,
+): Error => {
+  const inner = s.details.error;
+  const err = new Error(s.message, { cause: s });
+  err.name = inner.name;
+  err.stack = inner.stack;
+  return err;
+};
+
 export const create = <
   DetailsSchema extends z.ZodType = z.ZodNever,
   V extends Variant = Variant,

package/src/strings/strings.spec.ts

@@ -103,3 +103,22 @@ describe("trimPrefix", () => {
   it("should handle numbers in prefix", () =>
     expect(strings.trimPrefix("123abc", "123")).toBe("abc"));
 });
+
+describe("escapeHTML", () => {
+  it("should escape ampersands", () =>
+    expect(strings.escapeHTML("a&b")).toBe("a&b"));
+
+  it("should escape angle brackets", () =>
+    expect(strings.escapeHTML("<div>")).toBe("&lt;div&gt;"));
+
+  it("should escape quotes", () =>
+    expect(strings.escapeHTML(`"it's"`)).toBe("&quot;it&#39;s&quot;"));
+
+  it("should return the original string when no special characters", () =>
+    expect(strings.escapeHTML("hello")).toBe("hello"));
+
+  it("should escape all special characters together", () =>
+    expect(strings.escapeHTML(`<a href="x">&`)).toBe(
+      "&lt;a href=&quot;x&quot;&gt;&amp;",
+    ));
+});

package/src/strings/strings.ts

@@ -108,3 +108,19 @@ export const trimPrefix = (str: string, prefix: string): string => {
   if (str.startsWith(prefix)) return str.slice(prefix.length);
   return str;
 };
+
+/**
+ * Escapes HTML special characters in a string to prevent XSS and ensure
+ * correct rendering in HTML contexts.
+ *
+ * @param s - The string to escape.
+ * @returns The escaped string with &, <, >, ", and ' replaced by their
+ * HTML entity equivalents.
+ */
+export const escapeHTML = (s: string): string =>
+  s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");

package/src/telem/clockSkew.spec.ts

@@ -0,0 +1,58 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { describe, expect, it } from "vitest";
+
+import { ClockSkewCalculator, TimeSpan, TimeStamp } from "@/telem";
+
+describe("ClockSkewCalculator", () => {
+  it("should correctly calculate clock skew from a single measurement", () => {
+    let mockTime = TimeStamp.seconds(0);
+    const calc = new ClockSkewCalculator(() => mockTime);
+    calc.start();
+    mockTime = TimeStamp.seconds(10);
+    // Remote midpoint is 3s, local midpoint is 5s, so skew is 2s
+    calc.end(TimeStamp.seconds(3));
+    expect(calc.skew).toEqual(TimeSpan.seconds(2));
+    expect(calc.exceeds(TimeSpan.seconds(1))).toBe(true);
+    expect(calc.exceeds(TimeSpan.seconds(3))).toBe(false);
+  });
+
+  it("should report zero skew when times match perfectly", () => {
+    let mockTime = TimeStamp.seconds(0);
+    const calc = new ClockSkewCalculator(() => mockTime);
+    calc.start();
+    mockTime = TimeStamp.seconds(10);
+    // Remote midpoint matches local midpoint at 5s
+    calc.end(TimeStamp.seconds(5));
+    expect(calc.skew).toEqual(TimeSpan.ZERO);
+    expect(calc.exceeds(TimeSpan.seconds(1))).toBe(false);
+  });
+
+  it("should return the most recent measurement", () => {
+    let mockTime = TimeStamp.seconds(0);
+    const calc = new ClockSkewCalculator(() => mockTime);
+    calc.start();
+    mockTime = TimeStamp.seconds(10);
+    calc.end(TimeStamp.seconds(3));
+    expect(calc.skew).toEqual(TimeSpan.seconds(2));
+    mockTime = TimeStamp.seconds(0);
+    calc.start();
+    mockTime = TimeStamp.seconds(10);
+    // Remote midpoint is 7s, local midpoint is 5s, so skew is -2s
+    calc.end(TimeStamp.seconds(7));
+    expect(calc.skew).toEqual(TimeSpan.seconds(-2));
+  });
+
+  it("should return zero skew when no measurements taken", () => {
+    const calc = new ClockSkewCalculator();
+    expect(calc.skew).toEqual(TimeSpan.ZERO);
+    expect(calc.exceeds(TimeSpan.seconds(1))).toBe(false);
+  });
+});

package/src/telem/clockSkew.ts

@@ -0,0 +1,46 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { type CrudeTimeSpan, TimeSpan, TimeStamp } from "@/telem/telem";
+
+/**
+ * Calculates and tracks clock skew between two systems using a midpoint
+ * synchronization algorithm. Useful for distributed systems where clock
+ * synchronization is critical.
+ */
+export class ClockSkewCalculator {
+  private readonly now: () => TimeStamp;
+  private localStartT: TimeStamp = new TimeStamp(0);
+  private lastSkew: TimeSpan = TimeSpan.ZERO;
+
+  constructor(now: () => TimeStamp = () => TimeStamp.now()) {
+    this.now = now;
+  }
+
+  start(): void {
+    this.localStartT = this.now();
+  }
+
+  end(remoteMidpointT: TimeStamp): void {
+    const localEndT = this.now();
+    const halfSpan = localEndT.span(this.localStartT).valueOf() / 2n;
+    const thisMidpointT = this.localStartT.add(halfSpan);
+    this.lastSkew = new TimeSpan(thisMidpointT.valueOf() - remoteMidpointT.valueOf());
+  }
+
+  get skew(): TimeSpan {
+    return this.lastSkew;
+  }
+
+  exceeds(threshold: CrudeTimeSpan): boolean {
+    const skewVal = this.skew.valueOf();
+    const abs = skewVal < 0n ? -skewVal : skewVal;
+    return abs > new TimeSpan(threshold).valueOf();
+  }
+}

package/src/telem/external.ts

@@ -7,6 +7,15 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+export * from "@/telem/clockSkew";
 export { type GLBufferController } from "@/telem/gl";
 export * from "@/telem/series";
 export * from "@/telem/telem";
+export {
+  TIME_ZONES,
+  TIMESTAMP_FORMATS,
+  type TimestampFormat,
+  timestampFormatZ,
+  type TimeZone,
+  timeZoneZ,
+} from "@/telem/types.gen";