@ossy/platform 3.15.0 → 3.17.0

package/src/metering/get-workspace-task-metering.task.spec.js

@@ -0,0 +1,43 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+
+const getProjectionMock = jest.fn()
+
+jest.unstable_mockModule('@ossy/event-store', () => ({
+  getProjection: getProjectionMock,
+}))
+
+const { run } = await import('./get-workspace-task-metering.task.js')
+
+describe('get-workspace-task-metering task', () => {
+  beforeEach(() => {
+    getProjectionMock.mockReset()
+  })
+
+  it('requires a workspaceId', async () => {
+    await expect(run({ payload: {} })).rejects.toMatchObject({ status: 400 })
+  })
+
+  it('returns a zeroed bucket for a workspace with no task runs yet', async () => {
+    getProjectionMock.mockResolvedValue(null)
+    const result = await run({ payload: { workspaceId: 'ws-1', month: '2026-09' } })
+    expect(result).toEqual({
+      workspaceId: 'ws-1',
+      month: '2026-09',
+      requests: 0,
+      failures: 0,
+      durationMs: 0,
+      byModule: {},
+    })
+  })
+
+  it('returns the current month bucket from the projection', async () => {
+    getProjectionMock.mockResolvedValue({
+      byMonth: {
+        '2026-09': { requests: 12, failures: 1, durationMs: 4500, byModule: { '@ossy/media-tasks': { requests: 12, durationMs: 4500 } } },
+      },
+    })
+
+    const result = await run({ req: { workspaceId: 'ws-1' }, payload: { month: '2026-09' } })
+    expect(result).toMatchObject({ workspaceId: 'ws-1', month: '2026-09', requests: 12, durationMs: 4500 })
+  })
+})

package/src/metering/index.js

@@ -0,0 +1,11 @@
+export { MeteringService } from './metering-service.js'
+export { currentUsageMonth } from './usage-month.js'
+export { LlmUsageProjection } from './llm-usage.aggregate.js'
+export { TaskMeteringProjection } from './task-metering.aggregate.js'
+export {
+  DEFAULT_LLM_WORKSPACE_MONTHLY_TOKEN_CAP,
+  assertLlmUsageBudget,
+  llmWorkspaceMonthlyTokenCap,
+  resolveLlmMonthlyTokenLimit,
+  resolveWorkspaceIdForBudget,
+} from './assert-llm-usage-budget.js'

package/src/metering/llm-usage.aggregate.js

@@ -0,0 +1,127 @@
+import { currentUsageMonth } from './usage-month.js'
+
+export { currentUsageMonth }
+
+/**
+ * ADR 0017 — per-workspace LLM token usage, folded at write.
+ *
+ * Bounded, time-bucketed projection over `@ossy/platform/schema/meter-event`
+ * `Recorded` events. Only events carrying LLM usage (`promptTokens` /
+ * `completionTokens`, set via `TaskRunService` → `MeteringService.record()`
+ * when a task result includes `usage`) affect state — everything else is a
+ * no-op `Apply` (durationMs/success-only meter events for non-LLM tasks).
+ *
+ * Named generically (not after a specific provider) — today's LLM tasks
+ * (`run-prompt`, `visual-content-descriptors`) call OpenRouter, but nothing
+ * in this metering layer assumes that; swapping the provider integration
+ * later needs no rename here.
+ *
+ * Scope: one document per workspace. Snapshot size is bounded by
+ * months × distinct models, not one row per request — mirrors
+ * `@ossy/analytics`'s `PageViewLocationProjection` day-bucket shape.
+ *
+ * Read via `getProjection(workspaceId, LlmUsageProjection.ProjectionId)`
+ * (`@ossy/event-store`). This is the same data backing both the workspace
+ * settings dashboard stat and `assertLlmUsageBudget`'s hard cap check.
+ *
+ * See `TaskMeteringProjection` (`./task-metering.aggregate.js`) for the
+ * general, all-tasks count/duration counterpart to this LLM-specific one.
+ */
+export class LlmUsageProjection {
+
+  static kind = 'projection'
+  static ProjectionId = '@ossy/platform/data/llm-usage'
+
+  static sources = [
+    { type: '@ossy/platform/schema/meter-event', event: 'Recorded' },
+  ]
+
+  /**
+   * @param {object} event
+   * @returns {string | null}
+   */
+  static scopeFromEvent (event) {
+    const workspaceId = event.payload?.belongsTo ?? event.payload?.workspaceId
+    return typeof workspaceId === 'string' && workspaceId ? workspaceId : null
+  }
+
+  static cacheKeys (scopeId) {
+    return [
+      `projection:${LlmUsageProjection.ProjectionId}:${scopeId}`,
+      'action:@ossy/platform/actions/get-workspace-llm-usage',
+    ]
+  }
+
+  /**
+   * @param {string} scopeId workspaceId
+   */
+  static initialState (scopeId) {
+    return { workspaceId: scopeId, byMonth: {} }
+  }
+
+  /**
+   * @param {object} event
+   * @param {{ workspaceId?: string, byMonth?: Record<string, MonthBucket> }} state
+   * @returns {{ workspaceId: string, byMonth: Record<string, MonthBucket> }}
+   */
+  static Apply (event, state) {
+    const payload = event.payload ?? {}
+    const promptTokens = typeof payload.promptTokens === 'number' ? payload.promptTokens : null
+    const completionTokens = typeof payload.completionTokens === 'number' ? payload.completionTokens : null
+    if (promptTokens == null && completionTokens == null) {
+      // Not an LLM-usage meter event (e.g. a plain task/action record) — no-op.
+      return { workspaceId: state.workspaceId, byMonth: state.byMonth ?? {} }
+    }
+
+    const totalTokens = typeof payload.totalTokens === 'number'
+      ? payload.totalTokens
+      : (promptTokens ?? 0) + (completionTokens ?? 0)
+
+    const at = Number(event.created)
+    const month = new Date(Number.isFinite(at) && at > 0 ? at : Date.now()).toISOString().slice(0, 7)
+
+    const byMonth = { ...(state.byMonth ?? {}) }
+    const bucket = byMonth[month] ?? emptyBucket()
+    const modelKey = typeof payload.model === 'string' && payload.model ? payload.model : 'unknown'
+    const modelBucket = bucket.byModel[modelKey] ?? emptyModelBucket()
+
+    byMonth[month] = {
+      requests: bucket.requests + 1,
+      promptTokens: bucket.promptTokens + (promptTokens ?? 0),
+      completionTokens: bucket.completionTokens + (completionTokens ?? 0),
+      totalTokens: bucket.totalTokens + totalTokens,
+      byModel: {
+        ...bucket.byModel,
+        [modelKey]: {
+          requests: modelBucket.requests + 1,
+          promptTokens: modelBucket.promptTokens + (promptTokens ?? 0),
+          completionTokens: modelBucket.completionTokens + (completionTokens ?? 0),
+        },
+      },
+    }
+
+    return { workspaceId: state.workspaceId, byMonth }
+  }
+}
+
+/** @returns {MonthBucket} */
+function emptyBucket () {
+  return { requests: 0, promptTokens: 0, completionTokens: 0, totalTokens: 0, byModel: {} }
+}
+
+function emptyModelBucket () {
+  return { requests: 0, promptTokens: 0, completionTokens: 0 }
+}
+
+/**
+ * @typedef {{
+ *   requests: number,
+ *   promptTokens: number,
+ *   completionTokens: number,
+ *   totalTokens: number,
+ *   byModel: Record<string, { requests: number, promptTokens: number, completionTokens: number }>,
+ * }} MonthBucket
+ */
+
+export { LlmUsageProjection as Aggregate }
+export const id = 'platform/data/llm-usage'

package/src/metering/llm-usage.aggregate.spec.js

@@ -0,0 +1,95 @@
+import { describe, expect, it } from '@jest/globals'
+import { LlmUsageProjection, currentUsageMonth } from './llm-usage.aggregate.js'
+
+describe('LlmUsageProjection', () => {
+  it('scopes by workspaceId (belongsTo)', () => {
+    expect(LlmUsageProjection.scopeFromEvent({ payload: { belongsTo: 'ws-1' } })).toBe('ws-1')
+    expect(LlmUsageProjection.scopeFromEvent({ payload: {} })).toBeNull()
+  })
+
+  it('is a no-op for meter events without token usage (non-LLM tasks)', () => {
+    const state = LlmUsageProjection.initialState('ws-1')
+    const next = LlmUsageProjection.Apply({
+      created: Date.parse('2026-09-05T12:00:00.000Z'),
+      payload: { kind: 'task', taskId: '@ossy/booking/tasks/confirm', durationMs: 12, success: true },
+    }, state)
+    expect(next).toEqual({ workspaceId: 'ws-1', byMonth: {} })
+  })
+
+  it('folds prompt/completion tokens into the event month, keyed by model', () => {
+    const state = LlmUsageProjection.initialState('ws-1')
+    const next = LlmUsageProjection.Apply({
+      created: Date.parse('2026-09-05T12:00:00.000Z'),
+      payload: {
+        belongsTo: 'ws-1',
+        model: 'openai/gpt-4o-mini',
+        promptTokens: 100,
+        completionTokens: 20,
+        totalTokens: 120,
+      },
+    }, state)
+
+    expect(next.byMonth['2026-09']).toEqual({
+      requests: 1,
+      promptTokens: 100,
+      completionTokens: 20,
+      totalTokens: 120,
+      byModel: {
+        'openai/gpt-4o-mini': { requests: 1, promptTokens: 100, completionTokens: 20 },
+      },
+    })
+  })
+
+  it('accumulates across requests and models within the same month', () => {
+    const first = LlmUsageProjection.Apply({
+      created: Date.parse('2026-09-05T12:00:00.000Z'),
+      payload: { belongsTo: 'ws-1', model: 'openai/gpt-4o-mini', promptTokens: 100, completionTokens: 20 },
+    }, LlmUsageProjection.initialState('ws-1'))
+
+    const second = LlmUsageProjection.Apply({
+      created: Date.parse('2026-09-20T08:00:00.000Z'),
+      payload: { belongsTo: 'ws-1', model: 'google/gemini-2.5-flash-lite', promptTokens: 50, completionTokens: 10 },
+    }, first)
+
+    expect(second.byMonth['2026-09']).toEqual({
+      requests: 2,
+      promptTokens: 150,
+      completionTokens: 30,
+      totalTokens: 180,
+      byModel: {
+        'openai/gpt-4o-mini': { requests: 1, promptTokens: 100, completionTokens: 20 },
+        'google/gemini-2.5-flash-lite': { requests: 1, promptTokens: 50, completionTokens: 10 },
+      },
+    })
+  })
+
+  it('buckets separately across months', () => {
+    const first = LlmUsageProjection.Apply({
+      created: Date.parse('2026-08-31T23:00:00.000Z'),
+      payload: { belongsTo: 'ws-1', model: 'openai/gpt-4o-mini', promptTokens: 100, completionTokens: 20 },
+    }, LlmUsageProjection.initialState('ws-1'))
+
+    const second = LlmUsageProjection.Apply({
+      created: Date.parse('2026-09-01T01:00:00.000Z'),
+      payload: { belongsTo: 'ws-1', model: 'openai/gpt-4o-mini', promptTokens: 5, completionTokens: 1 },
+    }, first)
+
+    expect(Object.keys(second.byMonth).sort()).toEqual(['2026-08', '2026-09'])
+    expect(second.byMonth['2026-08'].totalTokens).toBe(120)
+    expect(second.byMonth['2026-09'].totalTokens).toBe(6)
+  })
+
+  it('invalidates the workspace usage action cache', () => {
+    expect(LlmUsageProjection.cacheKeys('ws-1')).toEqual([
+      'projection:@ossy/platform/data/llm-usage:ws-1',
+      'action:@ossy/platform/actions/get-workspace-llm-usage',
+    ])
+  })
+})
+
+describe('currentUsageMonth', () => {
+  it('passes through an explicit month, else defaults to the current UTC month', () => {
+    expect(currentUsageMonth('2026-01')).toBe('2026-01')
+    expect(currentUsageMonth()).toBe(new Date().toISOString().slice(0, 7))
+  })
+})

package/src/metering/metering-service.js

@@ -23,6 +23,10 @@ export const MeteringService = {
    *   actionInvocationId?: string | null,
    *   taskRunId?: string | null,
    *   trigger?: string | null,
+   *   model?: string | null,
+   *   promptTokens?: number | null,
+   *   completionTokens?: number | null,
+   *   totalTokens?: number | null,
    * }} record
    */
   async record (record) {
@@ -38,6 +42,10 @@ export const MeteringService = {
       actionInvocationId = null,
       taskRunId = null,
       trigger = null,
+      model = null,
+      promptTokens = null,
+      completionTokens = null,
+      totalTokens = null,
     } = record
 
     const moduleId = taskId
@@ -59,6 +67,11 @@ export const MeteringService = {
       actionInvocationId,
       taskRunId,
       trigger,
+      // ADR 0017 — optional LLM/usage-metering fields; null for non-metered runs.
+      model,
+      promptTokens,
+      completionTokens,
+      totalTokens,
       recordedAt: Date.now(),
     }
 

package/src/metering/metering-service.spec.js

@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+
+const appendResourceEventMock = jest.fn().mockResolvedValue(undefined)
+
+jest.unstable_mockModule('@ossy/event-store', () => ({
+  EventStore: { AppendResourceEvent: appendResourceEventMock },
+}))
+
+jest.unstable_mockModule('@ossy/observability', () => ({
+  createLogger: () => ({ debug () {}, info () {}, warn () {}, error () {} }),
+  metrics: { increment () {}, timing () {} },
+}))
+
+const { MeteringService } = await import('./metering-service.js')
+
+describe('MeteringService.record', () => {
+  beforeEach(() => {
+    appendResourceEventMock.mockClear()
+  })
+
+  it('defaults usage fields to null for a plain task/action record', async () => {
+    await MeteringService.record({
+      kind: 'task',
+      taskId: '@ossy/booking/tasks/confirm',
+      workspaceId: 'ws-1',
+      durationMs: 12,
+      success: true,
+    })
+
+    expect(appendResourceEventMock).toHaveBeenCalledTimes(1)
+    const [{ payload }] = appendResourceEventMock.mock.calls[0]
+    expect(payload).toMatchObject({
+      model: null,
+      promptTokens: null,
+      completionTokens: null,
+      totalTokens: null,
+    })
+  })
+
+  it('carries model/token usage onto the meter-event payload', async () => {
+    await MeteringService.record({
+      kind: 'task',
+      taskId: '@ossy/media-tasks/tasks/run-prompt',
+      workspaceId: 'ws-1',
+      durationMs: 800,
+      success: true,
+      model: 'openai/gpt-4o-mini',
+      promptTokens: 100,
+      completionTokens: 20,
+      totalTokens: 120,
+    })
+
+    const [{ payload }] = appendResourceEventMock.mock.calls[0]
+    expect(payload).toMatchObject({
+      belongsTo: 'ws-1',
+      model: 'openai/gpt-4o-mini',
+      promptTokens: 100,
+      completionTokens: 20,
+      totalTokens: 120,
+    })
+  })
+})

package/src/metering/task-metering.aggregate.js

@@ -0,0 +1,108 @@
+import { currentUsageMonth } from './usage-month.js'
+
+export { currentUsageMonth }
+
+/**
+ * ADR 0017 (amendment) — general, all-tasks execution volume per workspace,
+ * folded at write. Where `LlmUsageProjection` only folds meter events
+ * carrying LLM token usage, this folds **every** `kind: 'task'` meter event
+ * `MeteringService.record()` writes — regardless of whether the task used
+ * an LLM — into a bounded, monthly-bucketed count + total execution
+ * time. Intended as a second, non-token billing dimension ("how much
+ * automation did this workspace run") independent of AI usage.
+ *
+ * Snapshot size is bounded by months × distinct modules, mirroring
+ * `LlmUsageProjection` / `@ossy/analytics`'s day-bucket shape.
+ */
+export class TaskMeteringProjection {
+
+  static kind = 'projection'
+  static ProjectionId = '@ossy/platform/data/task-metering'
+
+  static sources = [
+    { type: '@ossy/platform/schema/meter-event', event: 'Recorded' },
+  ]
+
+  /**
+   * @param {object} event
+   * @returns {string | null}
+   */
+  static scopeFromEvent (event) {
+    const workspaceId = event.payload?.belongsTo ?? event.payload?.workspaceId
+    return typeof workspaceId === 'string' && workspaceId ? workspaceId : null
+  }
+
+  static cacheKeys (scopeId) {
+    return [
+      `projection:${TaskMeteringProjection.ProjectionId}:${scopeId}`,
+      'action:@ossy/platform/actions/get-workspace-task-metering',
+    ]
+  }
+
+  /**
+   * @param {string} scopeId workspaceId
+   */
+  static initialState (scopeId) {
+    return { workspaceId: scopeId, byMonth: {} }
+  }
+
+  /**
+   * @param {object} event
+   * @param {{ workspaceId?: string, byMonth?: Record<string, TaskMonthBucket> }} state
+   * @returns {{ workspaceId: string, byMonth: Record<string, TaskMonthBucket> }}
+   */
+  static Apply (event, state) {
+    const payload = event.payload ?? {}
+    if (payload.kind !== 'task') {
+      // Action invocations are metered too, but this dimension is task
+      // execution volume only.
+      return { workspaceId: state.workspaceId, byMonth: state.byMonth ?? {} }
+    }
+
+    const at = Number(event.created)
+    const month = new Date(Number.isFinite(at) && at > 0 ? at : Date.now()).toISOString().slice(0, 7)
+
+    const byMonth = { ...(state.byMonth ?? {}) }
+    const bucket = byMonth[month] ?? emptyBucket()
+    const moduleKey = typeof payload.moduleId === 'string' && payload.moduleId ? payload.moduleId : 'unknown'
+    const moduleBucket = bucket.byModule[moduleKey] ?? emptyModuleBucket()
+    const durationMs = typeof payload.durationMs === 'number' ? payload.durationMs : 0
+    const failed = payload.success === false
+
+    byMonth[month] = {
+      requests: bucket.requests + 1,
+      failures: bucket.failures + (failed ? 1 : 0),
+      durationMs: bucket.durationMs + durationMs,
+      byModule: {
+        ...bucket.byModule,
+        [moduleKey]: {
+          requests: moduleBucket.requests + 1,
+          durationMs: moduleBucket.durationMs + durationMs,
+        },
+      },
+    }
+
+    return { workspaceId: state.workspaceId, byMonth }
+  }
+}
+
+/** @returns {TaskMonthBucket} */
+function emptyBucket () {
+  return { requests: 0, failures: 0, durationMs: 0, byModule: {} }
+}
+
+function emptyModuleBucket () {
+  return { requests: 0, durationMs: 0 }
+}
+
+/**
+ * @typedef {{
+ *   requests: number,
+ *   failures: number,
+ *   durationMs: number,
+ *   byModule: Record<string, { requests: number, durationMs: number }>,
+ * }} TaskMonthBucket
+ */
+
+export { TaskMeteringProjection as Aggregate }
+export const id = 'platform/data/task-metering'

package/src/metering/task-metering.aggregate.spec.js

@@ -0,0 +1,71 @@
+import { describe, expect, it } from '@jest/globals'
+import { TaskMeteringProjection } from './task-metering.aggregate.js'
+import { currentUsageMonth } from './usage-month.js'
+
+describe('TaskMeteringProjection', () => {
+  it('scopes by workspaceId (belongsTo)', () => {
+    expect(TaskMeteringProjection.scopeFromEvent({ payload: { belongsTo: 'ws-1' } })).toBe('ws-1')
+    expect(TaskMeteringProjection.scopeFromEvent({ payload: {} })).toBeNull()
+  })
+
+  it('is a no-op for action-kind meter events (task execution volume only)', () => {
+    const state = TaskMeteringProjection.initialState('ws-1')
+    const next = TaskMeteringProjection.Apply({
+      created: Date.parse('2026-09-05T12:00:00.000Z'),
+      payload: { kind: 'action', actionId: '@ossy/booking/actions/create', durationMs: 12 },
+    }, state)
+    expect(next).toEqual({ workspaceId: 'ws-1', byMonth: {} })
+  })
+
+  it('counts every task run and sums duration, regardless of success', () => {
+    const first = TaskMeteringProjection.Apply({
+      created: Date.parse('2026-09-05T12:00:00.000Z'),
+      payload: { kind: 'task', taskId: '@ossy/media-tasks/tasks/run-prompt', moduleId: '@ossy/media-tasks', durationMs: 800, success: true },
+    }, TaskMeteringProjection.initialState('ws-1'))
+
+    const second = TaskMeteringProjection.Apply({
+      created: Date.parse('2026-09-20T08:00:00.000Z'),
+      payload: { kind: 'task', taskId: '@ossy/booking/tasks/confirm', moduleId: '@ossy/booking', durationMs: 50, success: false },
+    }, first)
+
+    expect(second.byMonth['2026-09']).toEqual({
+      requests: 2,
+      failures: 1,
+      durationMs: 850,
+      byModule: {
+        '@ossy/media-tasks': { requests: 1, durationMs: 800 },
+        '@ossy/booking': { requests: 1, durationMs: 50 },
+      },
+    })
+  })
+
+  it('buckets separately across months', () => {
+    const first = TaskMeteringProjection.Apply({
+      created: Date.parse('2026-08-31T23:00:00.000Z'),
+      payload: { kind: 'task', moduleId: '@ossy/media-tasks', durationMs: 100, success: true },
+    }, TaskMeteringProjection.initialState('ws-1'))
+
+    const second = TaskMeteringProjection.Apply({
+      created: Date.parse('2026-09-01T01:00:00.000Z'),
+      payload: { kind: 'task', moduleId: '@ossy/media-tasks', durationMs: 20, success: true },
+    }, first)
+
+    expect(Object.keys(second.byMonth).sort()).toEqual(['2026-08', '2026-09'])
+    expect(second.byMonth['2026-08'].durationMs).toBe(100)
+    expect(second.byMonth['2026-09'].durationMs).toBe(20)
+  })
+
+  it('invalidates the workspace task-metering action cache', () => {
+    expect(TaskMeteringProjection.cacheKeys('ws-1')).toEqual([
+      'projection:@ossy/platform/data/task-metering:ws-1',
+      'action:@ossy/platform/actions/get-workspace-task-metering',
+    ])
+  })
+})
+
+describe('currentUsageMonth (re-exported)', () => {
+  it('passes through an explicit month, else defaults to the current UTC month', () => {
+    expect(currentUsageMonth('2026-01')).toBe('2026-01')
+    expect(currentUsageMonth()).toBe(new Date().toISOString().slice(0, 7))
+  })
+})

package/src/metering/usage-month.js

@@ -0,0 +1,7 @@
+/**
+ * @param {string} [month] `YYYY-MM`; defaults to the current UTC month.
+ * @returns {string}
+ */
+export function currentUsageMonth (month) {
+  return typeof month === 'string' && month ? month : new Date().toISOString().slice(0, 7)
+}

package/src/runtime.js

@@ -12,6 +12,7 @@ import { loadSite, invalidateSite } from './site-loader.js'
 import { createLogger } from '@ossy/observability'
 import { mountHealthEndpoint } from './health.js'
 import { readWorkspaceIdFromCookies } from './user-app-settings.js'
+import { detectMobileDevice } from './ssr/detect-mobile-device.js'
 
 const log = createLogger('platform')
 
@@ -214,6 +215,7 @@ export async function startRuntime ({ port } = {}) {
         taskGraphEdges: cloneSerializable(manifest.taskGraphEdges || []),
         url: requestUrl,
         isAuthenticated: !!req.isAuthenticated,
+        isMobileDevice: detectMobileDevice(req),
         language,
         messages: cloneSerializable(messages),
         ...(fallbackMessages ? { fallbackMessages: cloneSerializable(fallbackMessages) } : {}),

package/src/server.js

@@ -37,6 +37,7 @@ import {
   withTimeout,
 } from './request-diagnostics.js'
 import { mergeWorkspaceSchemas } from '@ossy/workspaces/merge-workspace-schemas'
+import { detectMobileDevice } from './ssr/detect-mobile-device.js'
 import {
   buildEnableablePackageSet,
   setEnableablePackages,
@@ -578,6 +579,7 @@ export async function startServer (options = {}) {
           taskGraphEdges: cloneSerializable(manifest.taskGraphEdges || []),
           url: requestUrl,
           isAuthenticated: !!req.isAuthenticated,
+          isMobileDevice: detectMobileDevice(req),
           language,
           messages: cloneSerializable(messages),
           ...(fallbackMessages ? { fallbackMessages: cloneSerializable(fallbackMessages) } : {}),

package/src/ssr/detect-mobile-device.js

@@ -0,0 +1,39 @@
+/**
+ * SSR device detection for the app shell (fixes #871 — desktop sidenav
+ * flashing on mobile because SSR always assumed a desktop viewport).
+ *
+ * Primary signal: the `Sec-CH-UA-Mobile` client hint (Chromium browsers
+ * send it on every request once `Accept-CH` opts in, no round trip needed).
+ * It is a structured boolean: `?1` (mobile) or `?0` (desktop).
+ *
+ * Fallback: a `User-Agent` regex for browsers that don't send the client
+ * hint (Safari, Firefox). This is a best-effort guess only — the client
+ * still re-resolves the real value via `matchMedia` after mount.
+ */
+
+const MOBILE_USER_AGENT_PATTERN = /Mobi|Android|iPhone|iPad|iPod/i
+
+/**
+ * @param {string | undefined | null} headerValue raw `Sec-CH-UA-Mobile` header value
+ * @returns {boolean | null} `true`/`false` when the hint is present, `null` when absent/malformed
+ */
+export function parseSecChUaMobile (headerValue) {
+  if (typeof headerValue !== 'string') return null
+  const trimmed = headerValue.trim()
+  if (trimmed === '?1') return true
+  if (trimmed === '?0') return false
+  return null
+}
+
+/**
+ * @param {import('express').Request | undefined} req
+ * @returns {boolean} best-effort guess of whether the request came from a mobile device
+ */
+export function detectMobileDevice (req) {
+  const secChUaMobile = req?.headers?.['sec-ch-ua-mobile'] ?? req?.get?.('Sec-CH-UA-Mobile')
+  const hinted = parseSecChUaMobile(secChUaMobile)
+  if (hinted !== null) return hinted
+
+  const userAgent = req?.headers?.['user-agent'] ?? req?.get?.('User-Agent') ?? ''
+  return MOBILE_USER_AGENT_PATTERN.test(userAgent)
+}