@ossy/platform 3.2.0 → 3.4.0

package/README.md

@@ -60,7 +60,7 @@ Optional environment variables used by the platform itself:
 | Variable | Description |
 |---|---|
 | `DB_URL` | MongoDB connection string. Required for tasks and aggregates. |
-| `API_URL` + `OSSY_API_KEY` | SDK configuration. When set, tasks receive a pre-configured SDK instance. |
+| `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. |
 
 ## Health check

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -45,16 +45,16 @@
     "@aws-sdk/util-format-url": "^3.972.17",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@ossy/config": "^3.0.9",
-    "@ossy/event-store": "^3.2.0",
-    "@ossy/locale": "^3.0.9",
-    "@ossy/manifest": "^3.0.9",
+    "@ossy/event-store": "^3.4.0",
+    "@ossy/locale": "^3.4.0",
+    "@ossy/manifest": "^3.4.0",
     "@ossy/observability": "^3.0.9",
     "@ossy/policies": "^3.0.9",
-    "@ossy/schema": "^3.0.9",
-    "@ossy/sdk": "^3.2.0",
+    "@ossy/schema": "^3.4.0",
+    "@ossy/sdk": "^3.4.0",
     "@ossy/tokens": "^3.0.9",
-    "@ossy/users": "^3.2.0",
-    "@ossy/workspaces": "^3.2.0",
+    "@ossy/users": "^3.4.0",
+    "@ossy/workspaces": "^3.4.0",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
@@ -74,5 +74,5 @@
     "src",
     "Dockerfile"
   ],
-  "gitHead": "b045f1fd7f2fe00c776b9ea96f76083b93fd8556"
+  "gitHead": "d36b69444268d172bc3e8e1dc77e67afc63f8650"
 }

package/src/file.schema.js

@@ -7,5 +7,9 @@ export default {
     { name: 'Key', type: 'text' },
     { name: 'ContentLength', type: 'number' },
     { name: 'ContentType', type: 'text' },
+    // Populated async by @ossy/media-tasks/tasks/resize-common-web
+    { name: 'blurhash', type: 'text' },
+    { name: 'width', type: 'number' },
+    { name: 'height', type: 'number' },
   ],
 }

package/src/health.js

@@ -6,16 +6,35 @@
  */
 export const HEALTH_PATH = '/health'
 
+/**
+ * Abort hung Node `fetch` probes under the usual 5s Docker/ECS check timeout.
+ * Mirrored by `@ossy/deployment-tools` `HEALTHCHECK_FETCH_TIMEOUT_MS`.
+ */
+export const HEALTHCHECK_FETCH_TIMEOUT_MS = 4000
+
+/**
+ * @param {string | undefined} explicit
+ * @returns {string}
+ */
+export function resolveHealthServiceName (explicit) {
+  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim()
+  const fromEnv = typeof process.env.OSSY_SERVICE_NAME === 'string'
+    ? process.env.OSSY_SERVICE_NAME.trim()
+    : ''
+  return fromEnv || 'ossy'
+}
+
 /**
  * @param {import('express').Express} app
  * @param {{ service?: string }} [options]
  */
-export function mountHealthEndpoint (app, { service = 'ossy' } = {}) {
+export function mountHealthEndpoint (app, { service } = {}) {
+  const resolvedService = resolveHealthServiceName(service)
   const handler = (_req, res) => {
     res.status(200).json({
       ok: true,
       status: 'ok',
-      service,
+      service: resolvedService,
     })
   }
 

package/src/health.spec.js

@@ -1,6 +1,11 @@
-import { describe, expect, it, jest } from '@jest/globals'
+import { afterEach, describe, expect, it, jest } from '@jest/globals'
 import express from 'express'
-import { HEALTH_PATH, mountHealthEndpoint } from './health.js'
+import {
+  HEALTH_PATH,
+  HEALTHCHECK_FETCH_TIMEOUT_MS,
+  mountHealthEndpoint,
+  resolveHealthServiceName,
+} from './health.js'
 
 function createMockRes () {
   const res = {
@@ -18,7 +23,38 @@ function createMockRes () {
   return res
 }
 
+describe('resolveHealthServiceName', () => {
+  const original = process.env.OSSY_SERVICE_NAME
+
+  afterEach(() => {
+    if (original === undefined) delete process.env.OSSY_SERVICE_NAME
+    else process.env.OSSY_SERVICE_NAME = original
+  })
+
+  it('prefers an explicit non-empty service', () => {
+    process.env.OSSY_SERVICE_NAME = 'from-env'
+    expect(resolveHealthServiceName('platform-runtime')).toBe('platform-runtime')
+  })
+
+  it('uses OSSY_SERVICE_NAME when explicit is omitted', () => {
+    process.env.OSSY_SERVICE_NAME = 'website-ossy'
+    expect(resolveHealthServiceName()).toBe('website-ossy')
+  })
+
+  it('defaults to ossy', () => {
+    delete process.env.OSSY_SERVICE_NAME
+    expect(resolveHealthServiceName()).toBe('ossy')
+  })
+})
+
 describe('mountHealthEndpoint', () => {
+  const original = process.env.OSSY_SERVICE_NAME
+
+  afterEach(() => {
+    if (original === undefined) delete process.env.OSSY_SERVICE_NAME
+    else process.env.OSSY_SERVICE_NAME = original
+  })
+
   it('registers GET /health that returns 200 without auth', () => {
     const app = express()
     const get = jest.spyOn(app, 'get')
@@ -42,6 +78,7 @@ describe('mountHealthEndpoint', () => {
   })
 
   it('defaults service name to ossy', () => {
+    delete process.env.OSSY_SERVICE_NAME
     const app = express()
     const get = jest.spyOn(app, 'get')
     mountHealthEndpoint(app)
@@ -50,4 +87,20 @@ describe('mountHealthEndpoint', () => {
     handler({}, res)
     expect(res.body.service).toBe('ossy')
   })
+
+  it('labels via OSSY_SERVICE_NAME when set', () => {
+    process.env.OSSY_SERVICE_NAME = 'website-ossy'
+    const app = express()
+    const get = jest.spyOn(app, 'get')
+    mountHealthEndpoint(app)
+    const handler = get.mock.calls[0][1]
+    const res = createMockRes()
+    handler({}, res)
+    expect(res.body.service).toBe('website-ossy')
+  })
+
+  it('exports HEALTHCHECK_FETCH_TIMEOUT_MS under the ECS check timeout', () => {
+    expect(HEALTHCHECK_FETCH_TIMEOUT_MS).toBe(4000)
+    expect(HEALTHCHECK_FETCH_TIMEOUT_MS).toBeLessThan(5000)
+  })
 })

package/src/index.js

@@ -1,4 +1,5 @@
 export { TaskService } from './tasks/task-service.js'
+export { createInProcessSdk } from './tasks/in-process-sdk.js'
 export { loadAndRegisterTasks } from './tasks/task-registry.js'
 export { ChangeStream } from './tasks/change-stream.js'
 export { registerSchema, getSystemSchemas } from './resources/schema.registry.js'

package/src/runtime.js

@@ -78,7 +78,8 @@ export async function startRuntime ({ port } = {}) {
 
   const app = express()
   // Liveness for ALB/ECS — before site loading so probes never depend on CMS/domain.
-  mountHealthEndpoint(app, { service: 'platform-runtime' })
+  // Prefer OSSY_SERVICE_NAME (ECS task env) when set.
+  mountHealthEndpoint(app)
   app.use(morgan('tiny'))
   app.use(express.json({ strict: false }))
   app.use(cookieParser(process.env.OSSY_COOKIE_SECRET || 'default_secret'))

package/src/server.js

@@ -276,11 +276,12 @@ export async function startServer (options = {}) {
   const layoutsById = await loadLayoutsById(layoutManifest, buildDir, log)
 
   // Register the SDK so all tasks receive it as `sdk`.
-  // Priority: explicit options.sdk → SDK.of() from env vars → null (direct-DB fallback in tasks).
+  // Priority: explicit options.sdk → HTTP bot SDK (API_URL + OSSY_API_KEY) → in-process ActionService SDK.
   const botSdk = (process.env.API_URL && process.env.OSSY_API_KEY)
     ? SDK.of({ apiUrl: process.env.API_URL, authorization: process.env.OSSY_API_KEY })
     : null
-  TaskService.setSdk(options.sdk ?? botSdk)
+  const { createInProcessSdk } = await import('./tasks/in-process-sdk.js')
+  TaskService.setSdk(options.sdk ?? botSdk ?? createInProcessSdk())
 
   TaskService.startScheduler()
 
@@ -322,7 +323,8 @@ export async function startServer (options = {}) {
 
   const app = express()
   // Liveness for ALB/ECS — before auth so probes never depend on cookies/Mongo.
-  mountHealthEndpoint(app, { service: 'platform' })
+  // Prefer OSSY_SERVICE_NAME (ECS task env) when set.
+  mountHealthEndpoint(app)
   app.use(morgan('tiny'))
   app.use(express.json({ strict: false }))
   app.use(cookieParser(ConfigService.TokenSecret))
@@ -342,6 +344,10 @@ export async function startServer (options = {}) {
     next()
   })
   app.use(WorkspacesMiddleware.ExtractWorkspaceId())
+  // App-authored Express middleware from `src/middleware.js` (bundled to
+  // build/public/static/middleware.js). Runs after auth/workspace so handlers
+  // can rely on req.userId / req.workspaceId when present.
+  for (const mw of await loadAppMiddleware(buildDir)) app.use(mw)
   app.use(createSlowRequestLogger(log))
   if (fs.existsSync(publicDir)) app.use(express.static(publicDir))
   app.use(ProxyInternal())
@@ -625,6 +631,32 @@ export async function startServer (options = {}) {
   return { app, server, port, close: closeServer, lifetime }
 }
 
+/**
+ * Load optional app middleware bundled from `src/middleware.js`.
+ * Accepts a default export that is either a middleware function or an array.
+ *
+ * @param {string} buildDir
+ * @returns {Promise<import('express').RequestHandler[]>}
+ */
+async function loadAppMiddleware (buildDir) {
+  const candidates = [
+    path.resolve(buildDir, 'public', 'static', 'middleware.js'),
+    path.resolve(buildDir, 'middleware.js'),
+  ]
+  for (const candidate of candidates) {
+    if (!fs.existsSync(candidate)) continue
+    try {
+      const mod = await import(pathToFileURL(candidate).href)
+      const value = mod.default
+      if (Array.isArray(value)) return value
+      if (typeof value === 'function') return [value]
+    } catch (err) {
+      log.warn(`Failed to load app middleware from ${candidate}`, undefined, err)
+    }
+  }
+  return []
+}
+
 export default startServer
 export { loadLayoutsById, resolvePageLayoutRender }
 export { ConfigService } from './config.service.js'

package/src/tasks/in-process-sdk.js

@@ -0,0 +1,107 @@
+import { resolveActionId } from '@ossy/sdk'
+import { ActionService } from '../actions/action.service.js'
+import { IntegrationService } from '../integration.service.js'
+import { StorageClient } from '../storage/storage.client.js'
+import { derivativeObjectKey } from '../storage/storage-keys.js'
+
+/**
+ * @param {unknown} file
+ * @returns {Promise<Buffer>}
+ */
+async function fileToBuffer (file) {
+  if (Buffer.isBuffer(file)) return file
+  if (file instanceof Uint8Array) return Buffer.from(file)
+  if (typeof file?.arrayBuffer === 'function') {
+    return Buffer.from(await file.arrayBuffer())
+  }
+  throw new Error('[InProcessSdk] uploadNamedVersion expects a File, Blob, Buffer, or Uint8Array')
+}
+
+/**
+ * Resolve actor/workspace from an eventstore document for nested action invokes.
+ *
+ * @param {object} [event]
+ * @returns {{ userId: string, workspaceId?: string }}
+ */
+function reqFromEvent (event) {
+  return {
+    userId: event?.createdBy
+      ?? event?.payload?.createdBy
+      ?? event?.payload?.userId
+      ?? 'system',
+    workspaceId: event?.payload?.belongsTo
+      ?? event?.belongsTo
+      ?? event?.payload?.workspaceId,
+  }
+}
+
+/**
+ * Same-process SDK for changestream / scheduled tasks when no HTTP bot
+ * credentials (`API_URL` + `OSSY_API_KEY`) are configured.
+ *
+ * Implements the surface media and follow-up tasks use: `invoke` and
+ * `resources.uploadNamedVersion`, via ActionService + StorageClient.
+ *
+ * @param {{ req?: { userId?: string, workspaceId?: string } }} [options]
+ */
+export function createInProcessSdk (options = {}) {
+  const req = options.req ?? { userId: 'system' }
+
+  const sdk = {
+    /**
+     * @param {import('@ossy/sdk').ActionRef} action
+     * @param {Record<string, unknown>} [payload]
+     */
+    invoke (action, payload = {}) {
+      const actionId = resolveActionId(action)
+      return ActionService.invoke(actionId, {
+        payload,
+        sdk,
+        integrations: IntegrationService,
+        req,
+      })
+    },
+
+    /**
+     * Bind actor/workspace from a triggering event for one dispatch.
+     * @param {object} event
+     */
+    withEventContext (event) {
+      return createInProcessSdk({ req: reqFromEvent(event) })
+    },
+
+    get resources () {
+      return {
+        /**
+         * Patch named derivative metadata, then write bytes to storage.
+         * @param {{ id: string, name: string, file: File | Blob | Buffer | Uint8Array }} args
+         */
+        async uploadNamedVersion ({ id, name, file }) {
+          if (!id) throw new Error('[InProcessSdk] uploadNamedVersion requires id')
+          if (!name) throw new Error('[InProcessSdk] uploadNamedVersion requires name')
+          if (!file) throw new Error('[InProcessSdk] uploadNamedVersion requires file')
+
+          const size = typeof file.size === 'number' ? file.size : undefined
+          const type = typeof file.type === 'string' ? file.type : undefined
+          const buffer = await fileToBuffer(file)
+
+          const resource = await sdk.invoke('@ossy/resources/actions/upload-named-version', {
+            id,
+            namedVersion: name,
+            // HTTP SDK historically sent `name`; accept either in the task.
+            name,
+            size: size ?? buffer.length,
+            type,
+          })
+
+          // Action response may rewrite `sizes` to read URLs via withResourceMedia;
+          // always persist with the canonical derivative key.
+          await StorageClient.save(derivativeObjectKey(id, name), buffer)
+          return resource
+        },
+      }
+    },
+  }
+
+  return sdk
+}

package/src/tasks/in-process-sdk.spec.js

@@ -0,0 +1,89 @@
+import { describe, expect, it, jest } from '@jest/globals'
+
+const invokeMock = jest.fn(async (_id, context) => ({
+  id: context.payload.id,
+  content: {
+    sizes: { [context.payload.namedVersion]: `${context.payload.id}:${context.payload.namedVersion}` },
+    uploadUrl: '/local-storage?key=unused',
+  },
+}))
+
+const saveMock = jest.fn(async () => {})
+
+jest.unstable_mockModule('../actions/action.service.js', () => ({
+  ActionService: { invoke: invokeMock },
+}))
+
+jest.unstable_mockModule('../integration.service.js', () => ({
+  IntegrationService: { get: () => null },
+}))
+
+jest.unstable_mockModule('../storage/storage.client.js', () => ({
+  StorageClient: { save: saveMock },
+}))
+
+const { createInProcessSdk } = await import('./in-process-sdk.js')
+
+describe('createInProcessSdk', () => {
+  it('invokes actions in-process with bound req', async () => {
+    invokeMock.mockClear()
+    const sdk = createInProcessSdk({
+      req: { userId: 'u1', workspaceId: 'ws1' },
+    })
+
+    await sdk.invoke({ id: '@ossy/resources/actions/get' }, { resourceId: 'r1' })
+
+    expect(invokeMock).toHaveBeenCalledWith(
+      '@ossy/resources/actions/get',
+      expect.objectContaining({
+        payload: { resourceId: 'r1' },
+        req: { userId: 'u1', workspaceId: 'ws1' },
+      }),
+    )
+  })
+
+  it('binds event actor/workspace via withEventContext', async () => {
+    invokeMock.mockClear()
+    const sdk = createInProcessSdk().withEventContext({
+      createdBy: 'author',
+      payload: { belongsTo: 'workspace-a' },
+    })
+
+    await sdk.invoke('@ossy/resources/actions/get', { resourceId: 'r2' })
+
+    expect(invokeMock).toHaveBeenCalledWith(
+      '@ossy/resources/actions/get',
+      expect.objectContaining({
+        req: { userId: 'author', workspaceId: 'workspace-a' },
+      }),
+    )
+  })
+
+  it('uploadNamedVersion patches then saves bytes', async () => {
+    invokeMock.mockClear()
+    saveMock.mockClear()
+    const sdk = createInProcessSdk()
+    const bytes = new Uint8Array([1, 2, 3, 4])
+
+    await sdk.resources.uploadNamedVersion({
+      id: 'file1',
+      name: 'thumbnailSmall',
+      file: new File([bytes], 'thumbnailSmall', { type: 'image/jpeg' }),
+    })
+
+    expect(invokeMock).toHaveBeenCalledWith(
+      '@ossy/resources/actions/upload-named-version',
+      expect.objectContaining({
+        payload: expect.objectContaining({
+          id: 'file1',
+          namedVersion: 'thumbnailSmall',
+          type: 'image/jpeg',
+        }),
+      }),
+    )
+    expect(saveMock).toHaveBeenCalledWith(
+      'file1:thumbnailSmall',
+      expect.any(Buffer),
+    )
+  })
+})

package/src/tasks/task-service.js

@@ -147,7 +147,10 @@ export class TaskService {
   static dispatch(event, { sdk } = {}) {
     if (!event) return
 
-    const effectiveSdk = sdk ?? TaskService._sdk
+    const baseSdk = sdk ?? TaskService._sdk
+    const effectiveSdk = typeof baseSdk?.withEventContext === 'function'
+      ? baseSdk.withEventContext(event)
+      : baseSdk
 
     for (const { metadata, handler } of TaskService._tasks) {
       const triggers = metadata.triggers ?? []

package/src/test/flow-click.js

@@ -0,0 +1,43 @@
+/**
+ * Normalize a declarative flow `click` step into a Playwright locator click.
+ * Prefer `{ action }` for `data-action` controls; use `click` for structural hooks
+ * (e.g. overlay backdrop) that are not action POJOs.
+ *
+ * @param {unknown} click
+ * @returns {{ selector: string, position?: { x: number, y: number } }}
+ */
+export function resolveClickTarget (click) {
+  if (typeof click === 'string') {
+    const selector = click.trim()
+    if (!selector) {
+      throw new Error('click step requires a non-empty CSS selector')
+    }
+    return { selector }
+  }
+
+  if (click != null && typeof click === 'object' && !Array.isArray(click)) {
+    const selector = typeof click.selector === 'string' ? click.selector.trim() : ''
+    if (!selector) {
+      throw new Error('click step requires a non-empty CSS selector')
+    }
+
+    const out = { selector }
+    if (click.position != null) {
+      if (
+        typeof click.position !== 'object'
+        || Array.isArray(click.position)
+        || !Number.isFinite(Number(click.position.x))
+        || !Number.isFinite(Number(click.position.y))
+      ) {
+        throw new Error('click.position requires { x, y } with finite numbers')
+      }
+      out.position = {
+        x: Number(click.position.x),
+        y: Number(click.position.y),
+      }
+    }
+    return out
+  }
+
+  throw new Error('click step requires a non-empty CSS selector')
+}

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

@@ -0,0 +1,42 @@
+import { describe, expect, it } from '@jest/globals'
+import { resolveClickTarget } from './flow-click.js'
+
+describe('resolveClickTarget', () => {
+  it('accepts a bare selector string', () => {
+    expect(resolveClickTarget('[data-overlay]')).toEqual({
+      selector: '[data-overlay]',
+    })
+  })
+
+  it('accepts { selector } and trims whitespace', () => {
+    expect(resolveClickTarget({ selector: ' [data-ossy-mobile-shell-nav-overlay] ' })).toEqual({
+      selector: '[data-ossy-mobile-shell-nav-overlay]',
+    })
+  })
+
+  it('accepts optional { position: { x, y } }', () => {
+    expect(resolveClickTarget({
+      selector: '[data-ossy-mobile-shell-nav-overlay]',
+      position: { x: 360, y: 200 },
+    })).toEqual({
+      selector: '[data-ossy-mobile-shell-nav-overlay]',
+      position: { x: 360, y: 200 },
+    })
+  })
+
+  it('rejects empty or invalid values', () => {
+    expect(() => resolveClickTarget('')).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget('   ')).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget(null)).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget({ selector: '' })).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget([])).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget({
+      selector: '[data-overlay]',
+      position: { x: 'left' },
+    })).toThrow(/position requires/)
+    expect(() => resolveClickTarget({
+      selector: '[data-overlay]',
+      position: 10,
+    })).toThrow(/position requires/)
+  })
+})

package/src/test/flow-press.js

@@ -0,0 +1,25 @@
+/**
+ * Normalize a declarative flow `press` step into a Playwright keyboard key.
+ *
+ * @param {unknown} press
+ * @returns {string}
+ */
+export function resolvePressKey (press) {
+  if (typeof press === 'string') {
+    const key = press.trim()
+    if (!key) {
+      throw new Error('press step requires a non-empty key string (e.g. "Escape")')
+    }
+    return key
+  }
+
+  if (press != null && typeof press === 'object' && !Array.isArray(press)) {
+    const key = typeof press.key === 'string' ? press.key.trim() : ''
+    if (!key) {
+      throw new Error('press step requires a non-empty key string (e.g. "Escape")')
+    }
+    return key
+  }
+
+  throw new Error('press step requires a non-empty key string (e.g. "Escape")')
+}

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

@@ -0,0 +1,25 @@
+import { describe, expect, it } from '@jest/globals'
+import { resolvePressKey } from './flow-press.js'
+
+describe('resolvePressKey', () => {
+  it('accepts a bare key string', () => {
+    expect(resolvePressKey('Escape')).toBe('Escape')
+    expect(resolvePressKey('Enter')).toBe('Enter')
+    expect(resolvePressKey('Tab')).toBe('Tab')
+    expect(resolvePressKey('Shift+Tab')).toBe('Shift+Tab')
+  })
+
+  it('accepts { key } and trims whitespace', () => {
+    expect(resolvePressKey({ key: ' Escape ' })).toBe('Escape')
+    expect(resolvePressKey({ key: ' Shift+Tab ' })).toBe('Shift+Tab')
+  })
+
+  it('rejects empty or invalid values', () => {
+    expect(() => resolvePressKey('')).toThrow(/non-empty key/)
+    expect(() => resolvePressKey('   ')).toThrow(/non-empty key/)
+    expect(() => resolvePressKey(null)).toThrow(/non-empty key/)
+    expect(() => resolvePressKey({ key: '' })).toThrow(/non-empty key/)
+    expect(() => resolvePressKey({ key: 27 })).toThrow(/non-empty key/)
+    expect(() => resolvePressKey([])).toThrow(/non-empty key/)
+  })
+})

package/src/test/flow-runner.js

@@ -19,12 +19,18 @@ import {
   interpolateContextString,
   resolveContextValue,
 } from './flow-context.js'
+import { resolveClickTarget } from './flow-click.js'
+import { resolvePressKey } from './flow-press.js'
+import { resolveViewportSize } from './flow-viewport.js'
 
 export {
   escapeCssAttrValue,
   interpolateContextString,
   resolveContextValue,
 } from './flow-context.js'
+export { resolveClickTarget } from './flow-click.js'
+export { resolvePressKey } from './flow-press.js'
+export { resolveViewportSize } from './flow-viewport.js'
 
 const FLOW_PATTERN = /\.flow\.(mjs|cjs|js)$/
 
@@ -201,6 +207,31 @@ export async function runFlow (flow, options = {}) {
       continue
     }
 
+    if (step.viewport != null) {
+      if (!page) throw new Error('viewport step requires a Playwright page')
+      await page.setViewportSize(resolveViewportSize(step.viewport))
+      continue
+    }
+
+    if (step.press != null) {
+      if (!page) throw new Error('press step requires a Playwright page')
+      await page.keyboard.press(resolvePressKey(step.press))
+      continue
+    }
+
+    if (step.click != null) {
+      if (!page) throw new Error('click step requires a Playwright page')
+      const { selector, position } = resolveClickTarget(step.click)
+      const resolvedSelector = interpolateContextString(selector, context, {
+        escape: escapeCssAttrValue,
+      })
+      const locator = page.locator(resolvedSelector).first()
+      const clickTimeout = step.timeout ?? 15000
+      await locator.waitFor({ state: 'visible', timeout: clickTimeout })
+      await locator.click(position ? { position } : undefined)
+      continue
+    }
+
     if (step.form) {
       if (!page) throw new Error('form step requires a Playwright page')
       const formMeta = step.form
@@ -215,10 +246,16 @@ export async function runFlow (flow, options = {}) {
       }
       const engine = schemaEngineFromManifest(manifest)
       const content = mockFormContent(engine, template, context)
+      const formTimeout = step.timeout ?? 15000
       const formRoot = formId ? page.locator(`form[id="${formId}"]`) : page
+      await formRoot.waitFor({ state: 'visible', timeout: formTimeout })
       for (const field of template.fields) {
         const value = content[field.name]
-        const locator = formRoot.locator(`[name="${field.name}"]`)
+        if (value === undefined || value === null) {
+          throw new Error(`mockFormContent produced no value for field "${field.name}"`)
+        }
+        const locator = formRoot.locator(`[name="${field.name}"]`).first()
+        await locator.waitFor({ state: 'visible', timeout: formTimeout })
         const tag = await locator.evaluate(el => el.tagName.toLowerCase()).catch(() => 'input')
         if (tag === 'select') {
           await locator.selectOption(String(value))
@@ -227,7 +264,18 @@ export async function runFlow (flow, options = {}) {
           if (inputType === 'checkbox') {
             if (value) await locator.check()
           } else {
-            await locator.fill(String(value))
+            // Retry fills: early hydration can accept DOM input then wipe on re-render.
+            const asText = String(value)
+            for (let attempt = 0; attempt < 3; attempt++) {
+              await locator.fill(asText)
+              try {
+                await expectFn(locator).toHaveValue(asText, { timeout: 2000 })
+                break
+              } catch (err) {
+                if (attempt === 2) throw err
+                await page.waitForTimeout(150)
+              }
+            }
           }
         } else {
           await locator.fill(String(value))
@@ -240,10 +288,26 @@ export async function runFlow (flow, options = {}) {
       if (!page) throw new Error('action step requires a Playwright page')
       const actionId = resolveActionId(step.action)
       const service = resolveActionService(step.action, step.service)
-      const locator = page.locator(actionSelector(actionId, service)).first()
+      const matches = page.locator(actionSelector(actionId, service))
       const actionTimeout = step.timeout ?? 15000
-      await locator.waitFor({ state: 'visible', timeout: actionTimeout })
-      await locator.click()
+      await matches.first().waitFor({ state: 'attached', timeout: actionTimeout })
+      // Prefer an actionable match when duplicates exist (e.g. hero CTA under a page overlay).
+      const count = await matches.count()
+      let clicked = false
+      let lastError
+      for (let i = 0; i < count; i++) {
+        const candidate = matches.nth(i)
+        try {
+          await candidate.click({ timeout: Math.min(5000, actionTimeout) })
+          clicked = true
+          break
+        } catch (err) {
+          lastError = err
+        }
+      }
+      if (!clicked) {
+        throw lastError ?? new Error(`No actionable locator for ${actionSelector(actionId, service)}`)
+      }
       continue
     }
 
@@ -309,19 +373,37 @@ export async function runFlow (flow, options = {}) {
 
     if (step.result) {
       if (!page) throw new Error('result step requires a Playwright page')
-      const { text, url, page: pageRef, action, selector, timeout = 8000 } = step.result
+      const {
+        text,
+        url,
+        page: pageRef,
+        action,
+        selector,
+        hidden = false,
+        timeout = 8000,
+      } = step.result
+      const assertLocator = async (locator) => {
+        if (hidden) {
+          await expectFn(locator).toBeHidden({ timeout })
+          return
+        }
+        await expectFn(locator).toBeVisible({ timeout })
+      }
       if (action != null) {
         const actionId = resolveActionId(action)
         const service = resolveActionService(action, step.result.service)
-        await expectFn(page.locator(actionSelector(actionId, service)).first()).toBeVisible({ timeout })
+        await assertLocator(page.locator(actionSelector(actionId, service)).first())
       }
       if (selector != null) {
         const resolvedSelector = interpolateContextString(selector, context, {
           escape: escapeCssAttrValue,
         })
-        await expectFn(page.locator(resolvedSelector).first()).toBeVisible({ timeout })
+        await assertLocator(page.locator(resolvedSelector).first())
       }
       if (text != null) {
+        if (hidden) {
+          throw new Error('result.text cannot use hidden: true — assert via action or selector')
+        }
         const pattern = text instanceof RegExp ? text : new RegExp(text, 'i')
         await expectFn(page.getByText(pattern).first()).toBeVisible({ timeout })
       }

package/src/test/flow-viewport.js

@@ -0,0 +1,23 @@
+/**
+ * Normalize a declarative flow `viewport` step into Playwright setViewportSize input.
+ *
+ * @param {unknown} viewport
+ * @returns {{ width: number, height: number }}
+ */
+export function resolveViewportSize (viewport) {
+  if (viewport == null || typeof viewport !== 'object' || Array.isArray(viewport)) {
+    throw new Error('viewport step requires { width, height } with positive numbers')
+  }
+
+  const width = Number(viewport.width)
+  const height = Number(viewport.height)
+
+  if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) {
+    throw new Error('viewport step requires { width, height } with positive numbers')
+  }
+
+  return {
+    width: Math.round(width),
+    height: Math.round(height),
+  }
+}

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

@@ -0,0 +1,26 @@
+import { describe, expect, it } from '@jest/globals'
+import { resolveViewportSize } from './flow-viewport.js'
+
+describe('resolveViewportSize', () => {
+  it('accepts positive width/height', () => {
+    expect(resolveViewportSize({ width: 390, height: 844 })).toEqual({
+      width: 390,
+      height: 844,
+    })
+  })
+
+  it('rounds fractional dimensions', () => {
+    expect(resolveViewportSize({ width: 389.6, height: 843.2 })).toEqual({
+      width: 390,
+      height: 843,
+    })
+  })
+
+  it('rejects missing or non-positive sizes', () => {
+    expect(() => resolveViewportSize(null)).toThrow(/width, height/)
+    expect(() => resolveViewportSize({ width: 390 })).toThrow(/width, height/)
+    expect(() => resolveViewportSize({ width: 0, height: 844 })).toThrow(/width, height/)
+    expect(() => resolveViewportSize({ width: -1, height: 844 })).toThrow(/width, height/)
+    expect(() => resolveViewportSize('mobile')).toThrow(/width, height/)
+  })
+})

package/src/test/playwright.config.js

@@ -17,8 +17,16 @@
 /** @type {import('@playwright/test').PlaywrightTestConfig} */
 export default {
   retries: process.env.CI ? 1 : 0,
+  // Fail hung flow steps instead of sitting on the default 30s forever across many actions.
+  timeout: process.env.CI ? 60_000 : 30_000,
+  expect: {
+    timeout: process.env.CI ? 15_000 : 5_000,
+  },
   use: {
     baseURL: process.env.OSSY_APP_URL ?? process.env.BASE_URL ?? 'http://localhost:3002',
+    trace: process.env.CI ? 'on-first-retry' : 'off',
+    actionTimeout: process.env.CI ? 15_000 : 0,
+    navigationTimeout: process.env.CI ? 30_000 : 0,
   },
   reporter: [['list']],
   env: {

package/src/token.service.js

@@ -24,7 +24,7 @@ export class TokenService {
 
       if (!token) {
         log.debug('[TokenService] No token to verify')
-        return reject(new Error('No token'))
+        return reject(Object.assign(new Error('No token'), { status: 401 }))
       }
 
       jwt.verify(token, ConfigService.TokenSecret, { algorithms: ['HS256'] }, (error, payload) => {
@@ -32,7 +32,12 @@ export class TokenService {
 
         if (errorType) {
           log.error('[TokenService]: Token invalid', undefined, error)
-          return reject()
+          // Callers (e.g. POST /actions) use `err.status ?? 500` — always attach 401
+          // so unverifiable auth tokens are not reported as internal errors (#494).
+          return reject(Object.assign(new Error('Invalid or expired token'), {
+            status: 401,
+            cause: error,
+          }))
         }
 
         log.info('[TokenService]: Token verified')

package/src/token.service.spec.js

@@ -0,0 +1,49 @@
+import { beforeAll, describe, expect, it } from '@jest/globals'
+import jwt from 'jsonwebtoken'
+import { TokenService } from './token.service.js'
+import { ConfigService } from './config.service.js'
+
+describe('TokenService.verify', () => {
+  beforeAll(() => {
+    process.env.TOKEN_SECRET = process.env.TOKEN_SECRET || 'test-token-secret-for-verify'
+  })
+
+  it('resolves a valid HS256 token payload', async () => {
+    const token = jwt.sign({ sub: 'user-1', type: 'WebAuth' }, ConfigService.TokenSecret, {
+      algorithm: 'HS256',
+      expiresIn: '1h',
+    })
+    await expect(TokenService.verify(token)).resolves.toMatchObject({
+      sub: 'user-1',
+      type: 'WebAuth',
+    })
+  })
+
+  it('rejects missing tokens with status 401', async () => {
+    await expect(TokenService.verify('')).rejects.toMatchObject({
+      message: 'No token',
+      status: 401,
+    })
+    await expect(TokenService.verify(null)).rejects.toMatchObject({
+      status: 401,
+    })
+  })
+
+  it('rejects garbage tokens with status 401 (not an empty rejection)', async () => {
+    await expect(TokenService.verify('not-a-jwt')).rejects.toMatchObject({
+      message: 'Invalid or expired token',
+      status: 401,
+    })
+  })
+
+  it('rejects expired tokens with status 401', async () => {
+    const token = jwt.sign({ sub: 'user-1' }, ConfigService.TokenSecret, {
+      algorithm: 'HS256',
+      expiresIn: -10,
+    })
+    await expect(TokenService.verify(token)).rejects.toMatchObject({
+      message: 'Invalid or expired token',
+      status: 401,
+    })
+  })
+})