---
task: Fix /pos-main showing POS UI shell to unauthenticated users with confusing "Failed to load products" error — improve empty/no-auth state
cycles: 3
context: true
private: false
started: 2026-05-16T15:59:57Z
finished: 2026-05-16T16:01:00Z
---

## files
- app/Http/Controllers/Support/VueRouteMap.php [lines 93-97] — `/pos` route has `loginRequired: false` (intentional for POS_TERMINAL access key auth)
- resources/js/Pages/PosMain.vue — POS interface; shows "Failed to load products" when no session/access key is present
- resources/js/composables/Market/usePosSession.js — session initialization; sets `posStore.error` when no store can be resolved

## steps
1. In `PosMain.vue`, when `posStore.error` is set AND there is no `pos_access_key` in localStorage AND the user is not logged in, show a clear "No terminal access" message instead of the bare "Failed to load products" error.
   - Check: `!userStore.isLoggedIn && !posStore.activeSession && posStore.error`
   - Display: "This terminal has no active session. Please use your POS access key or log in."
2. (Optional / discuss with owner): Consider adding `allowedUserTypes: ['pos terminal', 'store owner', 'store manager', 'operator', 'super operator', 'ult']` to the `/pos` route while keeping `loginRequired: false`, so the route map at least documents who is expected to use this page.

## context
Current behaviour (confirmed by Playwright): navigating to `/pos-main` without any session or access key renders the full POS UI shell with:
- "All | Current Order" tab bar
- "Start New Session" button
- "Failed to load products" error banner
- Empty cart with ₱0.00 totals

This is because `loginRequired: false` is intentional — POS_TERMINAL accounts authenticate via access key (localStorage `pos_access_key`, prefix `PK-`), not via the standard mobile/password login. The backend guards on the actual API calls (start session, add item, etc.).

The UI concern: unauthenticated browsers with no access key see a confusing broken state. The fix is a graceful empty state, not removing `loginRequired: false`.

Dictionary reference: "POS Access Keys: A unique key used to authenticate a POS terminal without a traditional login." and `startNewSessionSilently` guards against calling the API when both `storeHash` and `access_key` are absent.

## notes
- dictionary: ai-docs/dictionary.md
- linters: none
- constraints: Do NOT change `loginRequired: false` on `/pos` — this breaks POS_TERMINAL access key auth. Only improve the UI empty state.