@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/tests/unit/color/xyz/analyze.spec.ts

@@ -0,0 +1,33 @@
+import { expect, test } from "vitest"
+
+import {
+  xyzColorValueToRelativeLuminance,
+  xyzColorValueToTristimulusSum,
+  xyzColorValueToXyChromaticityValue,
+} from "#Source/color/index.ts"
+
+test("xyzColorValueToRelativeLuminance returns y channel", () => {
+  expect(xyzColorValueToRelativeLuminance({ x: 0.25, y: 0.3, z: 0.4, alpha: 1 })).toBe(0.3)
+  expect(xyzColorValueToRelativeLuminance({ x: 0, y: 0, z: 0, alpha: 1 })).toBe(0)
+})
+
+test("xyzColorValueToTristimulusSum returns x plus y plus z", () => {
+  expect(xyzColorValueToTristimulusSum({ x: 0.25, y: 0.3, z: 0.4, alpha: 1 })).toBe(0.95)
+  expect(xyzColorValueToTristimulusSum({ x: 0, y: 0, z: 0, alpha: 1 })).toBe(0)
+})
+
+test("xyzColorValueToXyChromaticityValue returns xy chromaticity coordinates", () => {
+  expect(xyzColorValueToXyChromaticityValue({ x: 0.25, y: 0.3, z: 0.4, alpha: 1 })).toEqual({
+    x: 0.263_158,
+    y: 0.315_789,
+  })
+
+  expect(xyzColorValueToXyChromaticityValue({ x: 0.412_456, y: 0.212_673, z: 0.019_334, alpha: 1 })).toEqual({
+    x: 0.64,
+    y: 0.33,
+  })
+
+  expect(() => xyzColorValueToXyChromaticityValue({ x: 0, y: 0, z: 0, alpha: 1 })).toThrow(
+    "XYZ tristimulus sum must be greater than 0 to compute xy chromaticity",
+  )
+})

package/tests/unit/color/xyz/construct.spec.ts

@@ -0,0 +1,10 @@
+import { expect, test } from "vitest"
+
+import { createXyzColorValue } from "#Source/color/index.ts"
+
+test("createXyzColorValue validates non-negative channels", () => {
+  expect(createXyzColorValue({ x: 0.25, y: 0.3, z: 0.4, alpha: 1 }))
+    .toEqual({ x: 0.25, y: 0.3, z: 0.4, alpha: 1 })
+
+  expect(() => createXyzColorValue({ x: -0.1, y: 0.3, z: 0.4, alpha: 1 })).toThrow(RangeError)
+})

package/tests/unit/color/xyz/convert.spec.ts

@@ -0,0 +1,18 @@
+import { expect, test } from "vitest"
+
+import {
+  linearRgbColorValueToXyzColorValue,
+  xyzColorValueToLinearRgbColorValue,
+} from "#Source/color/index.ts"
+
+test("xyzColorValueToLinearRgbColorValue converts XYZ values to Linear RGB", () => {
+  expect(xyzColorValueToLinearRgbColorValue({ x: 0.333_784_22, y: 0.371_900_46, z: 0.621_726_04, alpha: 1 }))
+    .toEqual({ red: 0.2, green: 0.4, blue: 0.6, alpha: 1 })
+})
+
+test("linearRgbColorValueToXyzColorValue converts Linear RGB values to XYZ", () => {
+  expect(linearRgbColorValueToXyzColorValue({ red: 0.2, green: 0.4, blue: 0.6, alpha: 1 }))
+    .toEqual({ x: 0.333_784, y: 0.371_9, z: 0.621_726, alpha: 1 })
+
+  expect(() => linearRgbColorValueToXyzColorValue({ red: Number.NaN, green: 0.4, blue: 0.6, alpha: 1 })).toThrow(RangeError)
+})

package/tests/unit/credential/api-key.spec.ts

@@ -0,0 +1,37 @@
+import { expect, test, vi } from "vitest"
+
+import { generateApiKey, maskApiKey } from "#Source/credential/index.ts"
+
+test("generateApiKey creates a stable sk-prefixed key shape", () => {
+  vi.spyOn(crypto, "getRandomValues").mockImplementation(buffer => {
+    if (buffer === null) {
+      return buffer
+    }
+
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    const target = buffer as Uint8Array
+    target.forEach((_, index) => {
+      target[index] = index
+    })
+    return buffer
+  })
+
+  const apiKey = generateApiKey({})
+  const customApiKey = generateApiKey({ prefix: "pk_", alphabet: "ABC123", bodyLength: 6 })
+
+  expect(apiKey.startsWith("sk-")).toBe(true)
+  expect(apiKey).toHaveLength(51)
+  expect(apiKey).toMatch(/^sk-[0-9A-Za-z]{48}$/)
+  expect(customApiKey).toBe("pk_ABC123")
+  expect(() => generateApiKey({ alphabet: "", bodyLength: 6 })).toThrow("Expected alphabet to contain at least one character")
+})
+
+test("maskApiKey hides the middle of a valid key and rejects malformed input", () => {
+  const apiKey = `sk-${"ab"}${"0".repeat(44)}yz`
+  const customOptions = { prefix: "pk_", alphabet: "ABC123", bodyLength: 6 } as const
+
+  expect(maskApiKey(apiKey)).toBe("sk-ab********************************************yz")
+  expect(maskApiKey("pk_ABC123", customOptions)).toBe("pk_AB**23")
+  expect(() => maskApiKey("not-an-api-key")).toThrow("Invalid API key format")
+  expect(() => maskApiKey(`sk-${"#".repeat(48)}`)).toThrow("Invalid API key format")
+})

package/tests/unit/credential/bearer.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "vitest"
+
+import { formatBearerCredential, isBearerCredential, parseBearerCredential } from "#Source/credential/index.ts"
+
+test("isBearerCredential recognizes bearer credential strings", () => {
+  expect(isBearerCredential("Bearer token-value")).toBe(true)
+  expect(isBearerCredential("bearer token-value")).toBe(true)
+  expect(isBearerCredential("Basic token-value")).toBe(false)
+  expect(isBearerCredential("token-value")).toBe(false)
+})
+
+test("formatBearerCredential prefixes a raw token with the Bearer scheme", () => {
+  expect(formatBearerCredential("token-value")).toBe("Bearer token-value")
+  expect(formatBearerCredential("  token-value  ")).toBe("Bearer token-value")
+  expect(() => formatBearerCredential("   ")).toThrow("Expected token to contain at least one non-whitespace character")
+})
+
+test("parseBearerCredential extracts the raw token only from bearer credentials", () => {
+  expect(parseBearerCredential("Bearer token-value")).toBe("token-value")
+  expect(parseBearerCredential("bearer token-value")).toBe("token-value")
+  expect(parseBearerCredential("Basic token-value")).toBeUndefined()
+  expect(parseBearerCredential(undefined)).toBeUndefined()
+})

package/tests/unit/credential/json-web-token.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "vitest"
+
+import { formatBearerCredential, JsonWebToken } from "#Source/credential/index.ts"
+
+test("JsonWebToken.signToken creates a compact JWT string", async () => {
+  const jwt = new JsonWebToken({ secret: "credential-secret", expiresIn: 3_600 })
+
+  const token = await jwt.signToken("user-1")
+
+  expect(token.split(".")).toHaveLength(3)
+  expect(typeof token).toBe("string")
+})
+
+test("JsonWebToken.parseToken returns userId for valid tokens and undefined for invalid input", async () => {
+  const jwt = new JsonWebToken({ secret: "credential-secret", expiresIn: 3_600 })
+  const token = await jwt.signToken("user-1")
+
+  await expect(jwt.parseToken(token)).resolves.toBe("user-1")
+  await expect(jwt.parseToken(formatBearerCredential(token))).resolves.toBeUndefined()
+  await expect(jwt.parseToken(undefined)).resolves.toBeUndefined()
+  await expect(jwt.parseToken("broken.token.value")).resolves.toBeUndefined()
+  await expect(new JsonWebToken({ secret: "other-secret", expiresIn: 3_600 }).parseToken(token)).resolves.toBeUndefined()
+})

package/tests/unit/credential/password.spec.ts

@@ -0,0 +1,41 @@
+import { expect, test, vi } from "vitest"
+
+import { Password } from "#Source/credential/index.ts"
+
+test("Password.generateSalt returns a hexadecimal salt string of the requested byte length", () => {
+  vi.spyOn(crypto, "getRandomValues").mockImplementation(buffer => {
+    if (buffer === null) {
+      return buffer
+    }
+
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    const target = buffer as Uint8Array
+    target.fill(0xAB)
+    return buffer
+  })
+
+  const salt = Password.generateSalt(8)
+
+  expect(salt).toBe("abababababababab")
+  expect(salt).toHaveLength(16)
+})
+
+test("Password.hashPasswordWithSalt derives a stable PBKDF2-SHA-512 hash for the same input", async () => {
+  const salt = "00112233445566778899AABBCCDDEEFF"
+  const hash1 = await Password.hashPasswordWithSalt("secret", salt)
+  const hash2 = await Password.hashPasswordWithSalt("secret", salt)
+  const hash3 = await Password.hashPasswordWithSalt("other", salt)
+
+  expect(hash1).toHaveLength(128)
+  expect(hash1).toMatch(/^[0-9A-F]+$/i)
+  expect(hash1).toBe(hash2)
+  expect(hash1).not.toBe(hash3)
+})
+
+test("Password.comparePassword distinguishes matching and mismatching passwords", async () => {
+  const salt = "00112233445566778899AABBCCDDEEFF"
+  const hash = await Password.hashPasswordWithSalt("secret", salt)
+
+  await expect(Password.comparePassword("secret", hash, salt)).resolves.toBe(true)
+  await expect(Password.comparePassword("other", hash, salt)).resolves.toBe(false)
+})

package/tests/unit/cron/cron.spec.ts

@@ -0,0 +1,84 @@
+import { expect, test } from "vitest"
+
+import { Cron } from "#Source/cron/index.ts"
+
+const internalCreateFutureMinute = (minutesAhead: number): Date => {
+  const date = new Date(Date.now() + minutesAhead * 60_000)
+  date.setSeconds(0, 0)
+  return date
+}
+
+const internalCreatePastMinute = (minutesAgo: number): Date => {
+  const date = new Date(Date.now() - minutesAgo * 60_000)
+  date.setSeconds(0, 0)
+  return date
+}
+
+test("Cron creates schedule models from both cron expressions and one-shot dates", () => {
+  const expressionCron = new Cron({ pattern: "*/5 * * * *" })
+  const singleShotCron = new Cron({ pattern: internalCreateFutureMinute(5) })
+
+  expect(expressionCron).toBeInstanceOf(Cron)
+  expect(singleShotCron).toBeInstanceOf(Cron)
+})
+
+test("Cron.prevRun returns undefined before a one-shot schedule is reached", () => {
+  const scheduledAt = internalCreateFutureMinute(5)
+  const cron = new Cron({ pattern: scheduledAt })
+
+  expect(cron.prevRun()).toBeUndefined()
+})
+
+test("Cron.prevRuns returns historical one-shot runs that have already happened", () => {
+  const scheduledAt = internalCreatePastMinute(5)
+  const cron = new Cron({ pattern: scheduledAt })
+  const previousRuns = cron.prevRuns(2)
+
+  expect(previousRuns).toHaveLength(1)
+  expect(previousRuns[0]?.getTime()).toBe(scheduledAt.getTime())
+})
+
+test("Cron.currentRun stays undefined when the model is only queried and not executing a task", () => {
+  const cron = new Cron({ pattern: internalCreateFutureMinute(5) })
+
+  expect(cron.currentRun()).toBeUndefined()
+})
+
+test("Cron.nextRun returns the next upcoming one-shot run", () => {
+  const scheduledAt = internalCreateFutureMinute(5)
+  const cron = new Cron({ pattern: scheduledAt })
+
+  expect(cron.nextRun()?.getTime()).toBe(scheduledAt.getTime())
+})
+
+test("Cron.nextRuns returns upcoming expression runs in ascending order", () => {
+  const cron = new Cron({ pattern: "*/5 * * * *" })
+  const nextRuns = cron.nextRuns(2)
+
+  expect(nextRuns).toHaveLength(2)
+  expect(nextRuns[0]?.getTime()).toBeLessThan(nextRuns[1]?.getTime() ?? 0)
+  expect(cron.match(nextRuns[0]!)).toBe(true)
+  expect(cron.match(nextRuns[1]!)).toBe(true)
+})
+
+test("Cron.match reflects cron-expression semantics including domAndDow behavior", () => {
+  const yearlyCron = new Cron({ pattern: "0 0 1 1 *" })
+  const andCron = new Cron({ pattern: "0 0 1 * MON", domAndDow: true })
+  const orCron = new Cron({ pattern: "0 0 1 * MON", domAndDow: false })
+  const yearlyHit = new Date(2_026, 0, 1, 0, 0, 0, 0)
+  const yearlyMiss = new Date(2_026, 0, 1, 0, 1, 0, 0)
+  const mondayFirst = new Date(2_026, 5, 1, 0, 0, 0, 0)
+  const mondayNotFirst = new Date(2_026, 5, 8, 0, 0, 0, 0)
+  const firstNotMonday = new Date(2_026, 8, 1, 0, 0, 0, 0)
+
+  expect(yearlyCron.match(yearlyHit)).toBe(true)
+  expect(yearlyCron.match(yearlyMiss)).toBe(false)
+
+  expect(andCron.match(mondayFirst)).toBe(true)
+  expect(andCron.match(mondayNotFirst)).toBe(false)
+  expect(andCron.match(firstNotMonday)).toBe(false)
+
+  expect(orCron.match(mondayFirst)).toBe(true)
+  expect(orCron.match(mondayNotFirst)).toBe(true)
+  expect(orCron.match(firstNotMonday)).toBe(true)
+})

package/tests/unit/css/class.spec.ts

@@ -0,0 +1,157 @@
+import { expect, test } from "vitest"
+
+import {
+  addClass,
+  classArrayToClassObject,
+  classArrayToClassString,
+  classObjectToClassArray,
+  classObjectToClassString,
+  classStringToClassArray,
+  classStringToClassObject,
+  containClass,
+  formatClassToTarget,
+  neatenClassString,
+  prefixClassWith,
+  removeClass,
+  removePrefixOfClass,
+  replaceClass,
+  toClassArray,
+  toClassObject,
+  toClassString,
+  toggleClass,
+} from "#Source/css/index.ts"
+
+test("neatenClassString normalizes dots and spaces", () => {
+  expect(neatenClassString("mobius-base mobius-theme--light")).toBe("mobius-base mobius-theme--light")
+  expect(neatenClassString(".mobius-base.mobius-theme--light")).toBe("mobius-base mobius-theme--light")
+  expect(neatenClassString("  .mobius-base   mobius-theme--light  ")).toBe("mobius-base mobius-theme--light")
+})
+
+test("classStringToClassArray splits normalized class strings", () => {
+  expect(classStringToClassArray("mobius-base mobius-theme--light")).toEqual(["mobius-base", "mobius-theme--light"])
+  expect(classStringToClassArray(".mobius-base.mobius-theme--light")).toEqual(["mobius-base", "mobius-theme--light"])
+  expect(classStringToClassArray("  .mobius-base   mobius-theme--light  ")).toEqual(["mobius-base", "mobius-theme--light"])
+})
+
+test("classArrayToClassObject marks every class as true", () => {
+  expect(classArrayToClassObject(["mobius-base", "mobius-theme--light"]))
+    .toEqual({ "mobius-base": true, "mobius-theme--light": true })
+  expect(classArrayToClassObject(["mobius-base", ""]))
+    .toEqual({ "mobius-base": true })
+  expect(classArrayToClassObject([])).toEqual({})
+})
+
+test("classStringToClassObject converts strings through normalized array form", () => {
+  expect(classStringToClassObject("mobius-base mobius-theme--light"))
+    .toEqual({ "mobius-base": true, "mobius-theme--light": true })
+  expect(classStringToClassObject(".mobius-base.mobius-theme--light"))
+    .toEqual({ "mobius-base": true, "mobius-theme--light": true })
+})
+
+test("classObjectToClassArray keeps only truthy class names", () => {
+  expect(classObjectToClassArray({ active: true, disabled: false, primary: true }))
+    .toEqual(["active", "primary"])
+  expect(classObjectToClassArray({ "": true, active: true, disabled: false })).toEqual(["active"])
+  expect(classObjectToClassArray({ disabled: false })).toEqual([])
+})
+
+test("classArrayToClassString joins non-empty items with spaces", () => {
+  expect(classArrayToClassString(["mobius-base", "mobius-theme--light"]))
+    .toBe("mobius-base mobius-theme--light")
+  expect(classArrayToClassString(["mobius-base", "", "mobius-theme--light"]))
+    .toBe("mobius-base mobius-theme--light")
+})
+
+test("classObjectToClassString serializes only truthy keys", () => {
+  expect(classObjectToClassString({ active: true, disabled: false, primary: true }))
+    .toBe("active primary")
+  expect(classObjectToClassString({ "": true, active: true, disabled: false })).toBe("active")
+  expect(classObjectToClassString({ disabled: false })).toBe("")
+})
+
+test("toClassString preserves string input and serializes other shapes", () => {
+  expect(toClassString("  .button   active  ")).toBe("  .button   active  ")
+  expect(toClassString(["button", "active"])).toBe("button active")
+  expect(toClassString({ button: true, active: true, disabled: false })).toBe("button active")
+})
+
+test("toClassArray normalizes strings and clones arrays", () => {
+  const classArray = ["button", "", "active"]
+  const result = toClassArray(classArray)
+
+  expect(toClassArray(".button.active")).toEqual(["button", "active"])
+  expect(result).toEqual(["button", "active"])
+  expect(result).not.toBe(classArray)
+  expect(toClassArray({ button: true, active: true, disabled: false })).toEqual(["button", "active"])
+})
+
+test("toClassObject normalizes strings and clones objects", () => {
+  const classObject = { button: true, active: false, "": true }
+  const result = toClassObject(classObject)
+
+  expect(toClassObject("button active")).toEqual({ button: true, active: true })
+  expect(toClassObject(["button", "active"])).toEqual({ button: true, active: true })
+  expect(result).toEqual({ button: true, active: false })
+  expect(result).not.toBe(classObject)
+})
+
+test("formatClassToTarget returns the same external shape as target", () => {
+  expect(formatClassToTarget("", ["button", "active"])).toBe("button active")
+  expect(formatClassToTarget([], "button active")).toEqual(["button", "active"])
+  expect(formatClassToTarget({}, ["button", "active"])).toEqual({ button: true, active: true })
+})
+
+test("prefixClassWith adds prefixes only when missing", () => {
+  expect(prefixClassWith("pm-", "button active")).toBe("pm-button pm-active")
+  expect(prefixClassWith("pm-", ["button", "", "pm-active"])).toEqual(["pm-button", "pm-active"])
+  expect(prefixClassWith("pm-", { button: true, "": true, "pm-active": false }))
+    .toEqual({ "pm-button": true, "pm-active": false })
+})
+
+test("removePrefixOfClass removes prefixes only when present", () => {
+  expect(removePrefixOfClass("pm-", "pm-button pm-active plain")).toBe("button active plain")
+  expect(removePrefixOfClass("pm-", ["pm-button", "pm-", "plain"]))
+    .toEqual(["button", "plain"])
+  expect(removePrefixOfClass("pm-", { "pm-button": true, plain: false, "pm-": true }))
+    .toEqual({ button: true, plain: false })
+})
+
+test("addClass merges class names while preserving target shape", () => {
+  expect(addClass("button", "active primary")).toBe("button active primary")
+  expect(addClass(["button", ""], { active: true, primary: true, "": false }))
+    .toEqual(["button", "active", "primary"])
+  expect(addClass({ button: true }, ["active", "primary"]))
+    .toEqual({ button: true, active: true, primary: true })
+})
+
+test("removeClass removes selected class names while preserving target shape", () => {
+  expect(removeClass("button active primary", "active")).toBe("button primary")
+  expect(removeClass(["button", "active", "primary"], { active: true })).toEqual(["button", "primary"])
+  expect(removeClass({ button: true, active: true, primary: true }, ["active"]))
+    .toEqual({ button: true, active: false, primary: true })
+})
+
+test("toggleClass flips membership for each target class", () => {
+  expect(toggleClass("button active", "active primary")).toBe("button primary")
+  expect(toggleClass(["button", "active"], ["active", "", "primary"]))
+    .toEqual(["button", "primary"])
+  expect(toggleClass({ button: true, active: true }, ["active", "primary"]))
+    .toEqual({ button: true, active: false, primary: true })
+})
+
+test("replaceClass supports tuple arrays, string arrays, records, and string removals", () => {
+  expect(replaceClass("button active", [["active", "selected"]])).toBe("button selected")
+  expect(replaceClass("button active primary", ["active", "primary"])).toBe("button")
+  expect(replaceClass(["button", "active"], { active: "selected" })).toEqual(["button", "selected"])
+  expect(replaceClass({ button: true, active: true }, "active")).toEqual({ active: false, button: true })
+  expect(replaceClass({ "": true, button: true, active: false }, { "": "selected", active: "featured" }))
+    .toEqual({ button: true, featured: false })
+  expect(replaceClass("button active primary", [["active", ""], ["primary", "featured"]]))
+    .toBe("button featured")
+})
+
+test("containClass checks whether all required class names are present", () => {
+  expect(containClass("button active", "button active primary")).toBe(true)
+  expect(containClass(["button", "missing"], { button: true, active: true })).toBe(false)
+  expect(containClass({ button: true }, ["button", "active"])).toBe(true)
+})

package/tests/unit/environment/basic.spec.ts

@@ -0,0 +1,20 @@
+import { expect, test } from "vitest"
+
+import { useFactory } from "#Source/environment/basic.ts"
+
+test("useFactory executes selected branch by availability", () => {
+  const useEnabled = useFactory(() => 42, () => true)
+  const useDisabled = useFactory(() => 42, () => false)
+
+  const enabledResult = useEnabled(
+    (value) => value + 1,
+    () => -1,
+  )
+  const disabledResult = useDisabled(
+    (value) => value + 1,
+    () => -1,
+  )
+
+  expect(enabledResult).toBe(43)
+  expect(disabledResult).toBe(-1)
+})

package/tests/unit/environment/device.spec.ts

@@ -0,0 +1,146 @@
+import { expect, test, vi } from "vitest"
+
+import {
+  getDeviceInfo,
+  getDeviceNavigatorInfo,
+  getDeviceScreenInfo,
+  parseUserAgent,
+} from "#Source/environment/device.ts"
+
+const setupForGetDeviceNavigatorInfo = (): (() => void) => {
+  vi.stubGlobal("navigator", {
+    oscpu: "Windows NT 10.0",
+    hardwareConcurrency: 8,
+    deviceMemory: 16,
+    maxTouchPoints: 5,
+    platform: "Win32",
+    devicePosture: { type: "continuous" },
+    connection: {
+      downlink: 10,
+      downlinkMax: 100,
+      effectiveType: "4g",
+      rtt: 40,
+      saveData: false,
+      type: "wifi",
+    },
+    onLine: true,
+    cookieEnabled: true,
+    language: "en-US",
+    languages: ["en-US", "zh-CN"],
+    pdfViewerEnabled: true,
+    userAgent:
+      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+  })
+
+  return () => {
+    vi.unstubAllGlobals()
+  }
+}
+test("getDeviceNavigatorInfo collects navigator metadata", () => {
+  const restore = setupForGetDeviceNavigatorInfo()
+
+  const info = getDeviceNavigatorInfo()
+
+  expect(info.oscpu).toBe("Windows NT 10.0")
+  expect(info.hardwareConcurrency).toBe(8)
+  expect(info.connectionType).toBe("wifi")
+  expect(info.languages).toEqual(["en-US", "zh-CN"])
+
+  restore()
+})
+
+test("parseUserAgent normalizes user-agent metadata", () => {
+  const userAgent =
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36"
+
+  const info = parseUserAgent(userAgent)
+
+  expect(info.ua).toBe(userAgent)
+  expect(typeof info.browserIsBot).toBe("boolean")
+  expect(typeof info.browserIsChromeFamily).toBe("boolean")
+  expect(typeof info.deviceIsAppleSilicon).toBe("boolean")
+})
+
+const setupForGetDeviceScreenInfo = (): (() => void) => {
+  vi.stubGlobal("document", {
+    documentElement: {
+      clientWidth: 1_200,
+      clientHeight: 700,
+      scrollWidth: 2_000,
+      scrollHeight: 3_000,
+    },
+  })
+  vi.stubGlobal("window", {
+    devicePixelRatio: 2,
+    screen: {
+      width: 1_920,
+      height: 1_080,
+      availWidth: 1_900,
+      availHeight: 1_060,
+      orientation: { type: "landscape-primary" },
+    },
+    outerWidth: 1_400,
+    outerHeight: 900,
+    innerWidth: 1_200,
+    innerHeight: 700,
+    visualViewport: {
+      width: 1_180,
+      height: 680,
+      offsetLeft: 10,
+      offsetTop: 8,
+      pageLeft: 0,
+      pageTop: 0,
+      scale: 1,
+    },
+  })
+  vi.stubGlobal("getComputedStyle", () => ({
+    getPropertyValue: (name: string): string => {
+      if (name.includes("top")) {
+        return "10"
+      }
+      if (name.includes("bottom")) {
+        return "20"
+      }
+      if (name.includes("left")) {
+        return "30"
+      }
+      if (name.includes("right")) {
+        return "40"
+      }
+      return "0"
+    },
+  }))
+
+  return () => {
+    vi.unstubAllGlobals()
+  }
+}
+test("getDeviceScreenInfo collects screen and viewport metadata", () => {
+  const restore = setupForGetDeviceScreenInfo()
+
+  const info = getDeviceScreenInfo()
+
+  expect(info.pixelRatio).toBe(2)
+  expect(info.screenWidth).toBe(1_920)
+  expect(info.viewportAvailableWidth).toBe(1_200)
+  expect(info.safeAreaTop).toBe(10)
+  expect(info.safeAreaRight).toBe(40)
+
+  restore()
+})
+
+test("getDeviceInfo aggregates navigator, user-agent, and screen metadata", () => {
+  const restore1 = setupForGetDeviceNavigatorInfo()
+  const restore2 = setupForGetDeviceScreenInfo()
+
+  const userAgent =
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36"
+  const info = getDeviceInfo(userAgent)
+
+  expect(info.navigator.language).toBe("en-US")
+  expect(info.userAgent.ua).toBe(userAgent)
+  expect(info.screen.viewportHeight).toBe(700)
+
+  restore1()
+  restore2()
+})