@ossy/platform 3.9.0 → 3.11.1

package/README.md

@@ -60,6 +60,8 @@ Optional environment variables used by the platform itself:
 | Variable | Description |
 |---|---|
 | `DB_URL` | MongoDB connection string. Required for tasks and aggregates. |
+| `MONGO_MAX_POOL_SIZE` | Per-process MongoDB driver pool size (default `50`). Each ECS task shares one client for the event store and change stream — raise only if you see wait-queue latency. |
+| `MONGO_MAX_IDLE_TIME_MS` | Optional. When set to a positive ms value, closes idle pool sockets after that idle time. Unset by default (no idle churn). |
 | `API_URL` + `OSSY_API_KEY` | Optional HTTP bot SDK for tasks. When unset, tasks get an in-process SDK that calls `ActionService` / storage in the same process (local app-test and same-server changestream). |
 | `PORT` | HTTP port. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "3.9.0",
+  "version": "3.11.1",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -27,6 +27,7 @@
     "./test/flow-runner.js": "./src/test/flow-runner.js",
     "./test/playwright.config.js": "./src/test/playwright.config.js",
     "./locale": "./src/locale.js",
+    "./verify-sign-in-session": "./src/verify-sign-in-session.js",
     "./storage-keys": "./src/storage/storage-keys.js",
     "./mcp": "./src/mcp/mount-platform-mcp.js"
   },
@@ -45,16 +46,16 @@
     "@aws-sdk/util-format-url": "^3.972.17",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@ossy/config": "^3.0.9",
-    "@ossy/event-store": "^3.8.0",
+    "@ossy/event-store": "^3.11.1",
     "@ossy/locale": "^3.4.0",
     "@ossy/manifest": "^3.9.0",
     "@ossy/observability": "^3.0.9",
     "@ossy/policies": "^3.0.9",
     "@ossy/schema": "^3.8.0",
-    "@ossy/sdk": "^3.5.0",
-    "@ossy/tokens": "^3.5.0",
-    "@ossy/users": "^3.8.0",
-    "@ossy/workspaces": "^3.9.0",
+    "@ossy/sdk": "^3.11.1",
+    "@ossy/tokens": "^3.11.1",
+    "@ossy/users": "^3.11.1",
+    "@ossy/workspaces": "^3.11.1",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
@@ -75,5 +76,5 @@
     "Dockerfile",
     "docker-healthcheck.js"
   ],
-  "gitHead": "f404be69becb27a1fd853a6ff1903554e76e7d17"
+  "gitHead": "f279de3535b6bc76631cbc6b943dae8f92a1565f"
 }

package/src/index.js

@@ -8,6 +8,7 @@ export { validateSchemasForImport, ALLOWED_FIELD_TYPES, normalizeFieldType, reso
 export { IntegrationService } from './integration.service.js'
 export { ConfigService } from './config.service.js'
 export { ActionService } from './actions/action.service.js'
+export { applyVerifySignInSessionCookies } from './verify-sign-in-session.js'
 export { TokenService } from './token.service.js'
 export { UsersMiddleware } from './users.middleware.js'
 export { WorkspacesMiddleware } from './workspaces.middleware.js'
@@ -15,8 +16,10 @@ export { matchesCron } from './tasks/cron.js'
 export { matchesGlob, globToRegex, policyToQueryClause } from './tasks/glob.js'
 export {
   USER_SETTINGS_COOKIE,
+  WORKSPACE_ID_COOKIE,
   AUTH_COOKIE,
   readUserAppSettings,
+  readWorkspaceIdFromCookies,
   mergeUserAppSettingsCookie,
   clearWorkspaceFromUserAppSettings,
   setAuthCookie,

package/src/proxy-internal.js

@@ -2,6 +2,7 @@ import { createLogger } from '@ossy/observability'
 import {
   mergeUserAppSettingsCookie,
   readUserAppSettings,
+  readWorkspaceIdFromCookies,
 } from './user-app-settings.js'
 
 const log = createLogger('platform')
@@ -26,7 +27,10 @@ export function ProxyInternal () {
         return
       }
 
-      const requestedSettings = req.body
+      const requestedSettings = { ...req.body }
+      // Active workspace is selected via /users/select-workspace (and sign-in).
+      // Shell Sync must not send workspaceId — strip if a client does.
+      delete requestedSettings.workspaceId
       mergeUserAppSettingsCookie(req, res, requestedSettings)
 
       res.status(201)
@@ -37,8 +41,9 @@ export function ProxyInternal () {
     if (req.originalUrl.startsWith('/@ossy/users/me/app-settings') && req.method === 'GET') {
       log.info('[@ossy/platform][proxy] GET /@ossy/users/me/app-settings')
       const userSettings = readUserAppSettings(req)
+      const workspaceId = readWorkspaceIdFromCookies(req)
       res.status(200)
-      res.json(userSettings)
+      res.json(workspaceId ? { ...userSettings, workspaceId } : userSettings)
       return
     }
 

package/src/runtime.js

@@ -11,6 +11,7 @@ import { ProxyInternal } from './proxy-internal.js'
 import { loadSite, invalidateSite } from './site-loader.js'
 import { createLogger } from '@ossy/observability'
 import { mountHealthEndpoint } from './health.js'
+import { readWorkspaceIdFromCookies } from './user-app-settings.js'
 
 const log = createLogger('platform')
 
@@ -86,9 +87,10 @@ export async function startRuntime ({ port } = {}) {
 
   app.use((req, _res, next) => {
     const userSettings = JSON.parse(req.signedCookies?.['x-ossy-user-settings'] || '{}')
-    req.userAppSettings = userSettings
-    if (userSettings.workspaceId && !req.get('workspaceId')) {
-      req.headers.workspaceid = userSettings.workspaceId
+    const workspaceId = readWorkspaceIdFromCookies(req) || userSettings.workspaceId
+    req.userAppSettings = workspaceId ? { ...userSettings, workspaceId } : userSettings
+    if (workspaceId && !req.get('workspaceId')) {
+      req.headers.workspaceid = workspaceId
     }
     // Prefer a verified signed auth cookie; fall back to presence only when unsigned.
     req.isAuthenticated = !!(req.signedCookies?.auth)

package/src/select-workspace.api.js

@@ -35,7 +35,11 @@ export default async function handle (req, res) {
       return
     }
 
-    mergeUserAppSettingsCookie(req, res, { workspaceId })
+    const selected = workspaces.find((w) => w.id === workspaceId)
+    mergeUserAppSettingsCookie(req, res, {
+      workspaceId,
+      ...(selected?.name ? { workspaceName: selected.name } : {}),
+    })
 
     const redirect = req.query.redirect
     if (redirect && typeof redirect === 'string') {

package/src/server.js

@@ -43,7 +43,11 @@ import {
 import {
   clearAuthCookie,
   clearWorkspaceFromUserAppSettings,
+  mergeUserAppSettingsCookie,
+  readWorkspaceIdFromCookies,
+  setAuthCookie,
 } from './user-app-settings.js'
+import { applyVerifySignInSessionCookies } from './verify-sign-in-session.js'
 const log = createLogger('@ossy/platform')
 const MONGO_TIMEOUT_MS = resolveTimeoutMs('OSSY_MONGO_TIMEOUT_MS', 10_000)
 const SSR_RENDER_TIMEOUT_MS = resolveTimeoutMs('OSSY_SSR_RENDER_TIMEOUT_MS', 30_000)
@@ -330,9 +334,10 @@ export async function startServer (options = {}) {
   app.use(cookieParser(ConfigService.TokenSecret))
   app.use((req, _res, next) => {
     const userSettings = JSON.parse(req.signedCookies?.['x-ossy-user-settings'] || '{}')
-    req.userAppSettings = userSettings
-    if (userSettings.workspaceId && !req.get('workspaceId')) {
-      req.headers.workspaceid = userSettings.workspaceId
+    const workspaceId = readWorkspaceIdFromCookies(req) || userSettings.workspaceId
+    req.userAppSettings = workspaceId ? { ...userSettings, workspaceId } : userSettings
+    if (workspaceId && !req.get('workspaceId')) {
+      req.headers.workspaceid = workspaceId
     }
     next()
   })
@@ -425,6 +430,9 @@ export async function startServer (options = {}) {
         clearAuthCookie(res)
         clearWorkspaceFromUserAppSettings(req, res)
       }
+      if (actionId === '@ossy/authentication/actions/verify-sign-in' && result?.token) {
+        await applyVerifySignInSessionCookies(req, res, result)
+      }
       res.json(result ?? { ok: true })
     } catch (err) {
       // Still clear auth on sign-out failures so a broken session can recover.
@@ -668,6 +676,7 @@ export default startServer
 export { loadLayoutsById, resolvePageLayoutRender }
 export { ConfigService } from './config.service.js'
 export { ActionService } from './actions/action.service.js'
+export { applyVerifySignInSessionCookies } from './verify-sign-in-session.js'
 export { IntegrationService } from './integration.service.js'
 export { StorageClient } from './storage/storage.client.js'
 export { originalObjectKey, derivativeObjectKey, assertStorageKey } from './storage/storage-keys.js'
@@ -679,8 +688,10 @@ export { getPlatformSchema, initPlatformSchema, createSchemaEngine, schemaForWor
 export { validateSchemasForImport } from './resources/schema.validation.js'
 export {
   USER_SETTINGS_COOKIE,
+  WORKSPACE_ID_COOKIE,
   AUTH_COOKIE,
   readUserAppSettings,
+  readWorkspaceIdFromCookies,
   mergeUserAppSettingsCookie,
   clearWorkspaceFromUserAppSettings,
   setAuthCookie,

package/src/tasks/change-stream.js

@@ -1,6 +1,6 @@
 import { TaskService } from './task-service.js'
 import { createLogger } from '@ossy/observability'
-import { ProjectionRebuild, PushInvalidation, resolveMongoUrl } from '@ossy/event-store'
+import { Mongo, ProjectionRebuild, PushInvalidation } from '@ossy/event-store'
 
 const log = createLogger('platform')
 
@@ -11,26 +11,20 @@ function isMongoTopologyClosedError(error) {
   return false
 }
 
+/** Watches `eventstore` inserts. Uses the shared {@link Mongo} client — one per process. */
 export class ChangeStream {
 
   static _stopped = false
   static _reconnectAttempts = 0
-  static _dbUrl = null
-  static _client = null
   /** @type {import('mongodb').ChangeStream | null} */
   static _changeStream = null
   /** @type {ReturnType<typeof setTimeout> | null} */
   static _reconnectTimer = null
 
-  /**
-   * Opens the MongoDB changestream and wires up reconnect logic.
-   * Logs errors; does not crash the process on Mongo outages.
-   * @param {string} dbUrl - MongoDB connection URL (process.env.DB_URL)
-   */
-  static start(dbUrl) {
+  /** @param {string} [_dbUrl] - Unused; kept for call-site compatibility. */
+  static start(_dbUrl) {
     ChangeStream._stopped = false
     ChangeStream._reconnectAttempts = 0
-    ChangeStream._dbUrl = resolveMongoUrl(dbUrl)
     ChangeStream._open().catch((error) => {
       log.error('[ChangeStream] Change stream could not be opened', undefined, error)
       ChangeStream._scheduleReconnect()
@@ -55,48 +49,20 @@ export class ChangeStream {
       }
     }
 
-    const client = ChangeStream._client
-    ChangeStream._client = null
-    if (client) {
-      try {
-        await client.close()
-      } catch {
-        // ignore
-      }
-    }
-
     log.info('[ChangeStream] Stopped')
   }
 
-  static async _getMongoClient() {
-    const { MongoClient } = await import('mongodb')
-    return MongoClient
-  }
-
-  static async _getClient () {
+  static _getClient () {
     if (ChangeStream._stopped) {
       throw new Error('ChangeStream stopped')
     }
-    if (!ChangeStream._client) {
-      const MongoClient = await ChangeStream._getMongoClient()
-      ChangeStream._client = new MongoClient(ChangeStream._dbUrl, {
-        serverSelectionTimeoutMS: 30_000,
-      })
-    }
-    return ChangeStream._client
+    return Mongo.Client
   }
 
-  static async _resetClient () {
+  static _resetSharedClient () {
     if (ChangeStream._stopped) return
-    const MongoClient = await ChangeStream._getMongoClient()
-    const prev = ChangeStream._client
-    ChangeStream._client = new MongoClient(ChangeStream._dbUrl, {
-      serverSelectionTimeoutMS: 30_000,
-    })
-    if (prev) {
-      prev.close().catch(() => {})
-    }
-    log.info('[ChangeStream] New MongoClient instance created')
+    Mongo.resetClient()
+    log.info('[ChangeStream] Shared Mongo client reset')
   }
 
   static _scheduleReconnect () {
@@ -127,7 +93,7 @@ export class ChangeStream {
     log.info('[ChangeStream] Watching for changes')
 
     const dbName = process.env.DB_NAME || 'test'
-    const client = await ChangeStream._getClient()
+    const client = ChangeStream._getClient()
     if (ChangeStream._stopped) return
 
     const collection = client.db(dbName).collection('eventstore')
@@ -166,7 +132,7 @@ export class ChangeStream {
       if (ChangeStream._stopped) return
       log.error('[ChangeStream] Change stream error (server keeps running)', undefined, error)
       if (isMongoTopologyClosedError(error)) {
-        ChangeStream._resetClient().catch(() => {})
+        ChangeStream._resetSharedClient()
       }
       scheduleOnce()
     })

package/src/test/flow-action.js

@@ -0,0 +1,62 @@
+/**
+ * Shared helpers for resolving action POJOs in declarative flow steps.
+ */
+
+/**
+ * @param {unknown} action
+ * @returns {string}
+ */
+export function resolveActionId (action) {
+  if (typeof action === 'string') return action
+  if (action && typeof action.id === 'string') return action.id
+  throw new Error('Flow action step requires an action POJO or id string')
+}
+
+/**
+ * Optional discriminators for when multiple controls share an action id
+ * (e.g. per-row OpenRemoveMember beside a system bot row, or language switch targets).
+ *
+ * @param {unknown} action
+ * @param {{ service?: string, memberEmail?: string, language?: string }} [fallback]
+ * @returns {{ service?: string, memberEmail?: string, language?: string }}
+ */
+export function resolveActionMatchers (action, fallback = {}) {
+  const fromAction = typeof action === 'object' && action != null ? action : {}
+  const service = fromAction.service ?? fromAction['data-service'] ?? fallback.service
+  const memberEmail = fromAction.memberEmail
+    ?? fromAction['data-member-email']
+    ?? fallback.memberEmail
+  const language = fromAction.language
+    ?? fromAction['data-language']
+    ?? fallback.language
+  return {
+    ...(service != null && service !== '' ? { service: String(service) } : {}),
+    ...(memberEmail != null && memberEmail !== '' ? { memberEmail: String(memberEmail) } : {}),
+    ...(language != null && language !== '' ? { language: String(language) } : {}),
+  }
+}
+
+/**
+ * @param {string} actionId
+ * @param {string | { service?: string, memberEmail?: string, language?: string }} [serviceOrMatchers]
+ * @returns {string}
+ */
+export function actionSelector (actionId, serviceOrMatchers) {
+  const matchers = typeof serviceOrMatchers === 'string'
+    ? { service: serviceOrMatchers }
+    : (serviceOrMatchers ?? {})
+  let selector = `[data-action="${actionId}"]`
+  if (matchers.service) selector += `[data-service="${matchers.service}"]`
+  if (matchers.memberEmail) selector += `[data-member-email="${matchers.memberEmail}"]`
+  if (matchers.language) selector += `[data-language="${matchers.language}"]`
+  return selector
+}
+
+/**
+ * @param {unknown} action
+ * @param {string} [fallback]
+ * @returns {string | undefined}
+ */
+export function resolveActionService (action, fallback) {
+  return resolveActionMatchers(action, { service: fallback }).service
+}

package/src/test/flow-action.spec.js

@@ -0,0 +1,64 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  actionSelector,
+  resolveActionId,
+  resolveActionMatchers,
+  resolveActionService,
+} from './flow-action.js'
+
+describe('resolveActionId', () => {
+  it('reads id from a POJO', () => {
+    expect(resolveActionId({ id: '@ossy/app/actions/switch-language' }))
+      .toBe('@ossy/app/actions/switch-language')
+  })
+
+  it('accepts a bare id string', () => {
+    expect(resolveActionId('@ossy/app/actions/switch-language'))
+      .toBe('@ossy/app/actions/switch-language')
+  })
+})
+
+describe('resolveActionMatchers', () => {
+  it('reads service, memberEmail, and language from the action POJO', () => {
+    expect(resolveActionMatchers({
+      id: 'x',
+      service: 'booking',
+      memberEmail: 'a@b.c',
+      language: 'sv',
+    })).toEqual({
+      service: 'booking',
+      memberEmail: 'a@b.c',
+      language: 'sv',
+    })
+  })
+
+  it('falls back to data-* keys and step fallbacks', () => {
+    expect(resolveActionMatchers(
+      { 'data-service': 'timesheets', 'data-member-email': 'x@y.z', 'data-language': 'en' },
+      { service: 'ignored', memberEmail: 'ignored', language: 'ignored' },
+    )).toEqual({
+      service: 'timesheets',
+      memberEmail: 'x@y.z',
+      language: 'en',
+    })
+  })
+})
+
+describe('actionSelector', () => {
+  it('includes language in the selector', () => {
+    expect(actionSelector('@ossy/app/actions/switch-language', { language: 'sv' }))
+      .toBe('[data-action="@ossy/app/actions/switch-language"][data-language="sv"]')
+  })
+
+  it('still supports a bare service string', () => {
+    expect(actionSelector('@ossy/workspaces/actions/enable-service', 'booking'))
+      .toBe('[data-action="@ossy/workspaces/actions/enable-service"][data-service="booking"]')
+  })
+})
+
+describe('resolveActionService', () => {
+  it('delegates to matchers', () => {
+    expect(resolveActionService({ service: 'analytics' })).toBe('analytics')
+    expect(resolveActionService({}, 'booking')).toBe('booking')
+  })
+})

package/src/test/flow-context.js

@@ -42,3 +42,23 @@ export function interpolateContextString (template, context, options = {}) {
     return escape(value)
   })
 }
+
+/**
+ * Merge optional form-step field overrides into faker-mocked content.
+ * Values may be `$contextKey` placeholders (e.g. `{ email: '$email' }`).
+ *
+ * @param {Record<string, unknown>} content
+ * @param {Record<string, unknown> | null | undefined} overrides
+ * @param {{ fields?: Record<string, unknown>, [key: string]: unknown }} context
+ * @returns {Record<string, unknown>}
+ */
+export function applyFormFieldOverrides (content, overrides, context) {
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    return content
+  }
+  const next = { ...content }
+  for (const [name, raw] of Object.entries(overrides)) {
+    next[name] = resolveContextValue(raw, context)
+  }
+  return next
+}

package/src/test/flow-context.spec.js

@@ -1,5 +1,6 @@
 import { describe, expect, it } from '@jest/globals'
 import {
+  applyFormFieldOverrides,
   escapeCssAttrValue,
   interpolateContextString,
   resolveContextValue,
@@ -41,4 +42,17 @@ describe('flow-context', () => {
       interpolateContextString('[data-x="$missing"]', context),
     ).toBe('[data-x="$missing"]')
   })
+
+  it('applies form field overrides with $context placeholders', () => {
+    const mocked = { email: 'faker@example.com', firstName: 'Faker' }
+    expect(
+      applyFormFieldOverrides(mocked, { email: '$email' }, context),
+    ).toEqual({ email: 'new@example.com', firstName: 'Faker' })
+  })
+
+  it('returns content unchanged when overrides are missing', () => {
+    const mocked = { email: 'faker@example.com' }
+    expect(applyFormFieldOverrides(mocked, null, context)).toBe(mocked)
+    expect(applyFormFieldOverrides(mocked, undefined, context)).toBe(mocked)
+  })
 })

package/src/test/flow-download.js

@@ -0,0 +1,102 @@
+/**
+ * Resolve a declarative `{ download }` flow step.
+ *
+ * Clicks an action (or CSS selector) while waiting for one or more browser
+ * download events — used for single-file and batch download journeys.
+ */
+
+import { resolveActionId, resolveActionService } from './flow-action.js'
+
+/**
+ * @param {unknown} value
+ * @returns {{
+ *   actionId: string | null,
+ *   service: string | undefined,
+ *   selector: string | null,
+ *   count: number,
+ *   filenames: string[],
+ *   timeout: number,
+ * }}
+ */
+export function resolveDownloadTarget (value) {
+  if (value == null || (typeof value !== 'object' && typeof value !== 'string')) {
+    throw new Error('download step requires { action } or { selector }')
+  }
+
+  const spec = typeof value === 'string'
+    ? { action: value }
+    : value
+
+  const actionRaw = spec.action
+  const selectorRaw = typeof spec.selector === 'string' ? spec.selector.trim() : ''
+  let actionId = null
+  let service = typeof spec.service === 'string' ? spec.service : undefined
+
+  if (actionRaw != null) {
+    actionId = resolveActionId(actionRaw)
+    service = resolveActionService(actionRaw, service)
+  }
+
+  if (!actionId && !selectorRaw) {
+    throw new Error('download step requires { action } or a non-empty { selector }')
+  }
+
+  const filenames = []
+  if (spec.filename != null) {
+    if (typeof spec.filename !== 'string' || !spec.filename.trim()) {
+      throw new Error('download.filename must be a non-empty string')
+    }
+    filenames.push(spec.filename.trim())
+  }
+  if (Array.isArray(spec.filenames)) {
+    for (let i = 0; i < spec.filenames.length; i += 1) {
+      const name = spec.filenames[i]
+      if (typeof name !== 'string' || !name.trim()) {
+        throw new Error(`download.filenames[${i}] must be a non-empty string`)
+      }
+      filenames.push(name.trim())
+    }
+  } else if (spec.filenames != null) {
+    throw new Error('download.filenames must be an array of strings')
+  }
+
+  const countRaw = spec.count
+  const inferredCount = spec.count == null && filenames.length > 1 ? filenames.length : null
+  const count = inferredCount ?? (countRaw == null ? 1 : Number(countRaw))
+  if (!Number.isInteger(count) || count < 1) {
+    throw new Error('download.count must be a positive integer')
+  }
+
+  const timeoutRaw = spec.timeout
+  const timeout = timeoutRaw == null ? 30000 : Number(timeoutRaw)
+  if (!Number.isFinite(timeout) || timeout <= 0) {
+    throw new Error('download.timeout must be a positive number')
+  }
+
+  return {
+    actionId,
+    service,
+    selector: selectorRaw || null,
+    count,
+    filenames,
+    timeout,
+  }
+}
+
+/**
+ * @param {string[]} suggested
+ * @param {string[]} expected
+ */
+export function assertDownloadFilenames (suggested, expected) {
+  if (!expected.length) return
+  const remaining = [...suggested]
+  for (const name of expected) {
+    const index = remaining.indexOf(name)
+    if (index === -1) {
+      throw new Error(
+        `Expected download filename "${name}" not found in [${suggested.join(', ')}]`,
+      )
+    }
+    remaining.splice(index, 1)
+  }
+}

package/src/test/flow-download.spec.js

@@ -0,0 +1,60 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  assertDownloadFilenames,
+  resolveDownloadTarget,
+} from './flow-download.js'
+
+describe('resolveDownloadTarget', () => {
+  it('accepts an action POJO and optional filename', () => {
+    expect(resolveDownloadTarget({
+      action: { id: '@ossy/resources/actions/download-resource' },
+      filename: 'e2e-upload.txt',
+    })).toEqual({
+      actionId: '@ossy/resources/actions/download-resource',
+      service: undefined,
+      selector: null,
+      count: 1,
+      filenames: ['e2e-upload.txt'],
+      timeout: 30000,
+    })
+  })
+
+  it('infers count from filenames when count is omitted', () => {
+    expect(resolveDownloadTarget({
+      action: '@ossy/resources/actions/download-selected',
+      filenames: ['a.txt', 'b.txt'],
+    })).toMatchObject({
+      count: 2,
+      filenames: ['a.txt', 'b.txt'],
+    })
+  })
+
+  it('accepts a CSS selector fallback', () => {
+    expect(resolveDownloadTarget({
+      selector: ' [data-download] ',
+      count: 1,
+    })).toMatchObject({
+      actionId: null,
+      selector: '[data-download]',
+      count: 1,
+    })
+  })
+
+  it('rejects invalid values', () => {
+    expect(() => resolveDownloadTarget(null)).toThrow(/requires \{ action \}/)
+    expect(() => resolveDownloadTarget({})).toThrow(/requires \{ action \}/)
+    expect(() => resolveDownloadTarget({ action: 'x', count: 0 })).toThrow(/positive integer/)
+    expect(() => resolveDownloadTarget({ action: 'x', filename: '' })).toThrow(/filename/)
+    expect(() => resolveDownloadTarget({ action: 'x', timeout: -1 })).toThrow(/timeout/)
+  })
+})
+
+describe('assertDownloadFilenames', () => {
+  it('passes when expected names are present', () => {
+    expect(() => assertDownloadFilenames(['a.txt', 'b.txt'], ['b.txt', 'a.txt'])).not.toThrow()
+  })
+
+  it('fails when a name is missing', () => {
+    expect(() => assertDownloadFilenames(['a.txt'], ['b.txt'])).toThrow(/b\.txt/)
+  })
+})