@conduction/nextcloud-vue 2.1.0-vue3.12 → 2.1.0-vue3.13

package/eslint/index.js

@@ -52,6 +52,12 @@
  *     hand. The Vue-3 half of the key pair
  *     (`vue/no-v-for-template-key-on-child`) is untouched and stays armed —
  *     see {@link vueInvertedVue2Rules}.
+ *  6. It changes HOW you lint, never WHICH FILES you lint. Exactly one layer
+ *     carries a `files` glob — `**\/*.vue`, the only extension this preset
+ *     supplies a parser for. A `files` glob in flat config also ENROLS the
+ *     matched paths into the consumer's lint set, and enrolling a file type
+ *     you cannot parse is a fatal error that silences every rule on it —
+ *     see {@link VUE_SFC_FILES}.
  *
  * USAGE
  * -----
@@ -357,11 +363,65 @@ const vueEventCasingRules = {
 }
 
 /**
- * File globs the preset's language options apply to.
+ * The ONE file glob this preset is allowed to enrol, and the rule that says why.
+ *
+ * READ THIS BEFORE ADDING A `files` KEY TO ANY LAYER BELOW.
+ *
+ * In flat config a `files` glob does two different jobs at once, and only one
+ * of them is obvious:
+ *
+ *  1. it SCOPES the layer — "apply my options to these files"; and
+ *  2. it ENROLS those files — a path matched by some layer's `files` becomes a
+ *     file ESLint lints, even though ESLint's own default set is only
+ *     `**\/*.js`, `**\/*.mjs`, `**\/*.cjs`.
+ *
+ * A layer with NO `files` key does job 1 for every file the CONSUMER already
+ * lints and does not do job 2 at all. That is exactly what a shared
+ * language-level / rules layer wants, and getting it wrong shipped a
+ * regression:
+ *
+ * this preset used to scope its language-level and deprecation layers to
+ * `['**\/*.js', '**\/*.mjs', '**\/*.cjs', '**\/*.jsx', '**\/*.ts', '**\/*.mts',
+ * '**\/*.cts', '**\/*.tsx', '**\/*.vue']`. Adopting it therefore ENROLLED
+ * `.jsx`, `.ts`, `.tsx`, `.mts` and `.cts` into the lint set of every consumer
+ * — while supplying a parser for `.vue` only. Measured on portaliq's base
+ * config (`@nextcloud/eslint-config/vue3`, whose non-SFC parser is
+ * `@babel/eslint-parser` with no JSX plugin):
+ *
+ * ```
+ * base alone            + Probe.jsx  → NOT LINTED   (0 findings — a vacuous zero)
+ * base alone            + Probe.js   → linted, 1 no-unused-vars   (positive control)
+ * base + this preset    + Probe.jsx  → linted, FATAL "requires … parser plugin(s): jsx"
+ * standalone preset     + Probe.ts   → linted, FATAL
+ * standalone preset     + Probe.tsx  → linted, FATAL
+ * ```
+ *
+ * A `fatal` message stops ESLint evaluating EVERY OTHER RULE on that file, so
+ * an app with a React (or plain-TS) surface silently lost lint coverage of all
+ * of it — the identical failure shape to the `ecmaVersion: 2022` pin documented
+ * on {@link ECMA_LANGUAGE_LEVEL}, which fataled on the ES2024 `v` regexp flag
+ * and took the deprecation gate down with it.
+ *
+ * Note what the cause is NOT. Flat config DEEP-MERGES
+ * `languageOptions.parserOptions` across layers: spreading this preset last over
+ * a base that sets `{ requireConfigFile: false, ecmaFeatures: { jsx: true } }`
+ * yields `{ requireConfigFile: false, ecmaFeatures: { jsx: true },
+ * ecmaVersion: 'latest', sourceType: 'module' }` — nothing is dropped, and
+ * `tests/eslint/preset.spec.js` asserts it. "Merge instead of replace" would
+ * have been a no-op fix for a cause that was never there.
+ *
+ * So the rule: **enrol a file type only if this preset also supplies a parser
+ * that can read it.** It supplies one for `.vue` and nothing else, so `.vue` is
+ * the only glob here. Everything else is scoped by omission.
+ *
+ * A consumer that wants `.jsx` / `.ts` linted says so in ITS OWN config, where
+ * it can pair the extension with a parser that handles it; this preset's layers
+ * then apply to those files for free, because a layer with no `files` matches
+ * whatever the consumer lints.
  *
  * @type {string[]}
  */
-const ALL_SCRIPT_FILES = ['**/*.js', '**/*.mjs', '**/*.cjs', '**/*.jsx', '**/*.ts', '**/*.mts', '**/*.cts', '**/*.tsx', '**/*.vue']
+const VUE_SFC_FILES = ['**/*.vue']
 
 /**
  * The composable FIX layer: language level, SFC parser wiring, the armed
@@ -378,7 +438,13 @@ const ALL_SCRIPT_FILES = ['**/*.js', '**/*.mjs', '**/*.cjs', '**/*.jsx', '**/*.t
 const conductionVue3Fixes = [
 	{
 		name: 'conduction/language-level',
-		files: ALL_SCRIPT_FILES,
+		// NO `files` — deliberately. See {@link VUE_SFC_FILES}: a `files` glob
+		// also ENROLS those paths into the consumer's lint set, and this layer
+		// supplies no parser, so enrolling `.jsx`/`.ts`/`.tsx` handed them to
+		// whatever parser the base had and fataled the whole file. Without the
+		// key the layer applies to every file the consumer already lints —
+		// including `.jsx` once the consumer enrols it properly — and enrols
+		// nothing of its own.
 		languageOptions: {
 			ecmaVersion: ECMA_LANGUAGE_LEVEL,
 			sourceType: 'module',
@@ -395,7 +461,9 @@ const conductionVue3Fixes = [
 	},
 	{
 		name: 'conduction/vue-sfc-parser',
-		files: ['**/*.vue'],
+		// The one enrolment this preset is entitled to make: it hands `.vue`
+		// files to `vue-eslint-parser`, which can actually read them.
+		files: VUE_SFC_FILES,
 		languageOptions: {
 			parser: vueParser,
 			ecmaVersion: ECMA_LANGUAGE_LEVEL,
@@ -405,7 +473,18 @@ const conductionVue3Fixes = [
 	},
 	{
 		name: 'conduction/vue3-deprecations',
-		files: ['**/*.vue', '**/*.js', '**/*.mjs', '**/*.cjs', '**/*.ts', '**/*.tsx'],
+		// NO `files` — same reason as the language-level layer, and a rules-only
+		// layer enrols just as hard as one carrying `languageOptions`. Its old
+		// glob listed `**\/*.ts` and `**\/*.tsx`, which is how a plain-TypeScript
+		// file ended up being linted by a preset that ships no TypeScript parser.
+		//
+		// Applying to everything is also strictly BETTER coverage: eslint-plugin-vue
+		// treats `.jsx` and `.tsx` as Vue component files
+		// (`utils.isVueFile()` → `.vue || .jsx || .tsx`), so a Vue component
+		// authored as a render-function `.jsx` now gets the deprecation gate it
+		// never had under the old glob, on any consumer that lints `.jsx` at all.
+		// On files with no Vue component in them every one of these rules is a
+		// no-op, so there is no cost to the breadth.
 		rules: {
 			...vueDeprecationRules,
 			...vueEventCasingRules,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conduction/nextcloud-vue",
-  "version": "2.1.0-vue3.12",
+  "version": "2.1.0-vue3.13",
   "description": "Shared Vue component library for Conduction Nextcloud apps — complements @nextcloud/vue with higher-level components, OpenRegister integration, and NL Design System support",
   "license": "EUPL-1.2",
   "author": "Conduction B.V. <info@conduction.nl>",

package/testing/index.js

@@ -34,6 +34,9 @@ export {
 	WALKTHROUGH_STORAGE_PREFIX,
 	CHROME_DIALOG_SELECTORS,
 	FIRST_RUN_WIZARD_ROUTE,
+	NO_USER_SESSION,
+	GUEST_SURFACE,
+	guestSurfaceStatus,
 	seedSupportDialogSeen,
 	seedWalkthroughSeen,
 	seedFirstVisitOverlaysSeen,

package/testing/playwright.d.ts

@@ -58,10 +58,55 @@ export interface CnAppDialogOptions {
 export interface CnWizardRetirement {
 	/** HTTP status of the DELETE, or `-1` when the request itself threw. */
 	status: number
-	/** False when the firstrunwizard app is not installed (404). */
-	installed: boolean
-	/** True when no wizard will block clicks — a 2xx, or a 404. */
+	/**
+	 * False when the firstrunwizard app is not installed (404); `null` when the
+	 * status could not tell us — a 401 is answered by Nextcloud's auth layer
+	 * before the wizard app is ever consulted, so both booleans would be
+	 * inventions.
+	 */
+	installed: boolean | null
+	/**
+	 * True when no wizard will block clicks — a 2xx, a 404, or a guest surface
+	 * where the per-user wizard could never have rendered at all.
+	 */
 	cleared: boolean
+	/**
+	 * True when the wizard could not exist on this surface, so nothing was
+	 * dismissed and nothing needed to be. Assert `false` when a spec means to
+	 * prove a REAL dismissal happened.
+	 */
+	notApplicable: boolean
+	/** Why, when `notApplicable` — currently `'no-user-session'`. */
+	reason: string | null
+}
+
+/** Outcome of {@link dismissFirstVisitOverlays}. */
+export interface CnOverlayDismissal {
+	/**
+	 * True on a Nextcloud GUEST surface: nc-vue mounts `CnWalkthrough` and
+	 * `CnSupportDialog` from `CnAppRoot`, and a logged-out page has no app root,
+	 * so there is nothing to clear. The call short-circuits instead of spending
+	 * two timeouts polling for elements that cannot appear.
+	 */
+	notApplicable: boolean
+	/** Why, when `notApplicable` — currently `'guest-surface'`. */
+	reason: string | null
+	/** True when a walkthrough tour was actually closed. */
+	walkthroughDismissed: boolean
+	/** How many support dialogs were actually closed (nested roots raise more). */
+	supportDialogsDismissed: number
+}
+
+/** What kind of Nextcloud surface a page is — see {@link guestSurfaceStatus}. */
+export interface CnSurfaceStatus {
+	/** A Nextcloud page, with no user session and no mounted `CnAppRoot`. */
+	guest: boolean
+	/** The logged-in user id, or `null`. */
+	user: string | null
+	/** Whether the page carries a Nextcloud request token at all. */
+	isNextcloudPage: boolean
+	/** `appId` of every mounted `CnAppRoot`, outer shell first. */
+	appRoots: string[]
 }
 
 /** One mounted component instance, reduced to a JSON-safe shape. */
@@ -100,6 +145,21 @@ export const CHROME_DIALOG_SELECTORS: string[]
 /** Nextcloud's own first-run wizard dismissal route. */
 export const FIRST_RUN_WIZARD_ROUTE: string
 
+/** `reason` when {@link retireFirstRunWizard} finds no user session. */
+export const NO_USER_SESSION: string
+
+/** `reason` when {@link dismissFirstVisitOverlays} finds a guest surface. */
+export const GUEST_SURFACE: string
+
+/**
+ * Whether this page is a logged-in app surface or a Nextcloud GUEST surface.
+ *
+ * Call it AFTER the page has loaded. The seeding helpers cannot answer it for
+ * you — they run before `goto()`, where there is no document to interrogate —
+ * and on a guest surface they write keys that nothing ever reads.
+ */
+export function guestSurfaceStatus(page: CnTestPage): Promise<CnSurfaceStatus>
+
 /**
  * Seed the support dialog as already seen.
  *
@@ -119,7 +179,7 @@ export function seedFirstVisitOverlaysSeen(target: CnSeedTarget, appId?: string
 
 export function dismissWalkthrough(page: CnTestPage, options?: CnDismissOptions): Promise<boolean>
 export function dismissSupportDialog(page: CnTestPage, options?: CnDismissOptions): Promise<number>
-export function dismissFirstVisitOverlays(page: CnTestPage, options?: CnDismissOptions): Promise<void>
+export function dismissFirstVisitOverlays(page: CnTestPage, options?: CnDismissOptions): Promise<CnOverlayDismissal>
 
 /** A `Locator` for the app's own modal, excluding NC and nc-vue chrome dialogs. */
 export function appDialog(page: CnTestPage, options?: CnAppDialogOptions): CnTestLocator

package/testing/playwright.js

@@ -159,6 +159,77 @@ const APP_ROOT_ID_ATTR = 'data-nldesign-theme-scope'
  */
 const FIRST_RUN_WIZARD_ROUTE = '/index.php/apps/firstrunwizard/wizard'
 
+/**
+ * `reason` returned by {@link retireFirstRunWizard} when the page has no user
+ * session, so Nextcloud's wizard could not render there whatever the server
+ * said.
+ *
+ * @type {string}
+ */
+const NO_USER_SESSION = 'no-user-session'
+
+/**
+ * `reason` returned by {@link dismissFirstVisitOverlays} when the page is a
+ * Nextcloud GUEST surface: it is a Nextcloud page (it carries a request token)
+ * but has no user session and mounts no `CnAppRoot`, so none of the overlays
+ * these helpers clear can exist on it.
+ *
+ * @type {string}
+ */
+const GUEST_SURFACE = 'guest-surface'
+
+/**
+ * Read the page's Nextcloud session, IN THE BROWSER.
+ *
+ * A module-level arrow with no closure references, so Playwright can serialise
+ * it into `page.evaluate` — and so {@link retireFirstRunWizard} and
+ * {@link guestSurfaceStatus} cannot drift apart on what "logged in" means.
+ *
+ * Three sources, in descending order of authority:
+ *
+ *  1. `OC.getCurrentUser()` — the documented accessor, present on any page that
+ *     loaded `core/js/dist/main`;
+ *  2. `OC.currentUser` — the older global some pages still expose;
+ *  3. the `data-user` attribute Nextcloud stamps on `<head>` — the only one of
+ *     the three that survives on a stripped-down public template.
+ *
+ * `isNextcloudPage` is derived from the request TOKEN, not the user, and that
+ * separation is the point. Measured on a portaliq guest portal page: it emits
+ * `data-requesttoken` and NO `data-user`. Token-without-user is therefore
+ * positive evidence of a guest surface, whereas "neither present" just means
+ * this is not a Nextcloud page at all (an `about:blank`, a fixture, a page
+ * seeded before `goto()`) and nothing may be concluded from it.
+ *
+ * @return {{user: (string|null), isNextcloudPage: boolean}} Session facts.
+ */
+const readSurfaceSession = () => {
+	const oc = globalThis.OC || {}
+	const head = (globalThis.document && globalThis.document.head) || null
+	const attr = (name) => (head && typeof head.getAttribute === 'function' ? head.getAttribute(name) : null)
+
+	let user = null
+	try {
+		if (typeof oc.getCurrentUser === 'function') {
+			const current = oc.getCurrentUser()
+			user = (current && current.uid) || null
+		}
+	} catch (e) {
+		/* a partially-initialised OC can throw; absence is the answer we want */
+	}
+	if (!user && typeof oc.currentUser === 'string' && oc.currentUser !== '') {
+		user = oc.currentUser
+	}
+	if (!user) {
+		user = attr('data-user') || null
+	}
+
+	const token = (typeof oc.requestToken === 'string' && oc.requestToken !== '')
+		? oc.requestToken
+		: attr('data-requesttoken')
+
+	return { user: user || null, isNextcloudPage: Boolean(token) }
+}
+
 /**
  * Selectors for `[role="dialog"]` elements that are NOT the application's own
  * modal — see {@link appDialog}.
@@ -437,6 +508,20 @@ async function installSeenShim(target, prefix, ids, matchAll, value, scope) {
  * Use the BrowserContext form with explicit ids whenever the state is going to
  * be saved — see {@link seedFirstVisitOverlaysSeen}.
  *
+ * INERT ON A GUEST SURFACE — READ THIS BEFORE DEBUGGING A SEED THAT "DID
+ * NOTHING". `CnSupportDialog` is auto-mounted by `CnAppRoot`, and a page with
+ * no user session does not mount one. Measured on a portaliq public portal
+ * page: `data-requesttoken` present, `data-user` absent, no `CnAppRoot` in the
+ * DOM. The seed still writes its key and still reads back `"1"` — it simply has
+ * no reader, because `useSupportDialog` never runs there.
+ *
+ * That is the RIGHT behaviour (there is no dialog to suppress) and the seed is
+ * deliberately left unconditional: it is normally called BEFORE `page.goto()`,
+ * where there is no document yet to interrogate, so a "is this a guest surface"
+ * probe here would be measuring `about:blank` and would answer wrong every
+ * time. Call {@link guestSurfaceStatus} AFTER the page has loaded when you need
+ * the answer, and {@link dismissFirstVisitOverlays} reports it for you.
+ *
  * @param {object} target Playwright `Page` or `BrowserContext`.
  * @param {string|string[]} [appId] App id(s). `'*'`/omitted covers all, but is
  *   page-scoped only and can never be persisted.
@@ -464,8 +549,12 @@ async function seedSupportDialogSeen(target, appId) {
  * that answers `{"value": null}` (never written) falls back to this mirror,
  * which is the common case.
  *
- * Same nested-`CnAppRoot` coverage rule — and the same `'*'`/`storageState`
- * refusal — as {@link seedSupportDialogSeen}.
+ * Same nested-`CnAppRoot` coverage rule, the same `'*'`/`storageState` refusal,
+ * and the same GUEST-SURFACE caveat — the tour is mounted by `CnAppRoot`, so on
+ * a page with no user session and no app root this seed writes a key nothing
+ * ever reads. See {@link seedSupportDialogSeen} for all three, and
+ * {@link guestSurfaceStatus} for the probe that tells you which surface you are
+ * on.
  *
  * @param {object} target Playwright `Page` or `BrowserContext`.
  * @param {string|string[]} [appId] App id(s); `'*'`/omitted covers all, and is
@@ -488,6 +577,12 @@ async function seedWalkthroughSeen(target, appId, version = FUTURE_VERSION) {
  * it refuses the `'*'` form outright — which is the form that reads back
  * correctly inside the page and then persists nothing.
  *
+ * Both seeds are INERT on a guest surface, for the reason spelled out on
+ * {@link seedSupportDialogSeen}: nc-vue mounts neither overlay without a
+ * `CnAppRoot`, and a logged-out page has none. Harmless, and worth knowing
+ * before you spend an afternoon on a seed that "did not take" —
+ * {@link guestSurfaceStatus} answers it in one call.
+ *
  * @param {object} target Playwright `Page` or `BrowserContext`.
  * @param {string|string[]} [appId] App id(s). Required (and explicit) when
  *   `target` is a `BrowserContext`.
@@ -610,13 +705,56 @@ async function dismissSupportDialog(page, options = {}) {
  * Order matters: the walkthrough's dimmer sits above the support dialog, so
  * the tour goes first or the dialog's close button is unreachable.
  *
+ * REPORTS "NOT APPLICABLE" ON A GUEST SURFACE INSTEAD OF SILENTLY DOING
+ * NOTHING. `CnWalkthrough` and `CnSupportDialog` are both auto-mounted BY
+ * `CnAppRoot`, so on a page that mounts no app root neither overlay exists and
+ * this helper has nothing to clear. That is correct behaviour and the wrong
+ * SHAPE: measured on a portaliq public portal page (request token present,
+ * `data-user` absent, no `CnAppRoot`), the call spent its full timeout budget
+ * twice over polling for elements that could not appear, and then returned the
+ * same `undefined` a successful dismissal returns. The consuming spec had no
+ * way to tell "cleared two overlays" from "there was nothing here" — so the
+ * next consumer gets to guess, or works around it locally.
+ *
+ * Now it returns a result. On a guest surface it short-circuits
+ * ({@link guestSurfaceStatus} decides), returning
+ * `{ notApplicable: true, reason: 'guest-surface' }` immediately instead of
+ * burning two timeouts. Everywhere else it reports what it actually did.
+ *
+ * The return value is additive: callers that ignore it are unaffected.
+ *
  * @param {object} page Playwright `Page`.
  * @param {object} [options] Forwarded to both helpers.
- * @return {Promise<void>}
+ * @return {Promise<{notApplicable: boolean, reason: (string|null),
+ *   walkthroughDismissed: boolean, supportDialogsDismissed: number}>} What was
+ *   cleared, or why nothing could be.
+ *
+ * @example
+ * const cleared = await dismissFirstVisitOverlays(page)
+ * if (cleared.notApplicable) {
+ *   // guest surface: nc-vue mounts no overlays here, nothing was skipped
+ * }
  */
 async function dismissFirstVisitOverlays(page, options = {}) {
-	await dismissWalkthrough(page, options)
-	await dismissSupportDialog(page, options)
+	const surface = await guestSurfaceStatus(page)
+	if (surface.guest) {
+		return {
+			notApplicable: true,
+			reason: GUEST_SURFACE,
+			walkthroughDismissed: false,
+			supportDialogsDismissed: 0,
+		}
+	}
+
+	const walkthroughDismissed = await dismissWalkthrough(page, options)
+	const supportDialogsDismissed = await dismissSupportDialog(page, options)
+
+	return {
+		notApplicable: false,
+		reason: null,
+		walkthroughDismissed,
+		supportDialogsDismissed,
+	}
 }
 
 /**
@@ -690,17 +828,59 @@ function appDialog(page, options = {}) {
  * reported as `{ cleared: true, installed: false }` rather than thrown, so a
  * shared `global-setup` works on instances with and without the app.
  *
- * @param {object} page Playwright `Page`, already logged in and on a Nextcloud
- *   page (the request is same-origin and needs `window.OC.requestToken`).
+ * TRUTHFUL ON A GUEST SURFACE — and it used to lie here.
+ * Unauthenticated, `DELETE /apps/firstrunwizard/wizard` answers `401`. The
+ * helper used to fold that into its catch-all failure branch and report
+ * `{ installed: true, cleared: false }` — i.e. "a blocking overlay remains".
+ * That is not merely unhelpful, it is FALSE: Nextcloud's first-run wizard is a
+ * per-user overlay and cannot render for a visitor with no session, so there
+ * was never anything there to block a click. A public-portal spec that trusted
+ * the return value would fail its own setup over an overlay that does not
+ * exist.
+ *
+ * So the session is consulted, not just the status code:
+ *
+ * | condition                          | result                                                                  |
+ * | ---------------------------------- | ----------------------------------------------------------------------- |
+ * | 2xx                                | `{installed: true,  cleared: true,  notApplicable: false}`               |
+ * | 404                                | `{installed: false, cleared: true,  notApplicable: false}`               |
+ * | 401, or a Nextcloud page with no user | `{installed: null, cleared: true,  notApplicable: true, reason: 'no-user-session'}` |
+ * | anything else                      | `{installed: true,  cleared: false, notApplicable: false}`               |
+ *
+ * WHY `cleared: true` FOR A GUEST. `cleared` documents one thing: "nothing will
+ * block clicks". On a guest surface nothing will, so `true` is the honest
+ * answer — reporting `false` would make every caller that guards on it treat a
+ * perfectly usable page as broken. `notApplicable: true` is what keeps it
+ * distinguishable from a real dismissal, so a spec that wants to assert the
+ * wizard was genuinely retired asserts `notApplicable === false` and gets a
+ * failure if it silently ran as a guest.
+ *
+ * WHY `installed: null` RATHER THAN A BOOLEAN. A `401` is answered by
+ * Nextcloud's auth layer before the wizard app is consulted at all, so the
+ * response carries no information about whether the app is installed. `true`
+ * and `false` would both be inventions; `null` says "not known from here". It
+ * is falsy, so existing `if (installed)` checks behave as they did.
+ *
+ * The 2xx and 404 branches are evaluated BEFORE the session check on purpose:
+ * if the server actually accepted the dismissal, that is dispositive and there
+ * is nothing to second-guess.
+ *
+ * @param {object} page Playwright `Page`, on a Nextcloud page (the request is
+ *   same-origin and needs `window.OC.requestToken`). A logged-out page is
+ *   handled rather than misreported — see the table above.
  * @param {object} [options] `{ route }` to override the dismissal route.
- * @return {Promise<{status: number, cleared: boolean, installed: boolean}>}
+ * @return {Promise<{status: number, cleared: boolean, installed: (boolean|null),
+ *   notApplicable: boolean, reason: (string|null)}>}
  *   `status` is the HTTP status, or `-1` when the request itself threw.
- *   `cleared` is true when nothing will block clicks (2xx, or 404 = not
- *   installed). `installed` distinguishes the two.
+ *   `cleared` is true when nothing will block clicks. `installed` is `null`
+ *   when the status could not tell us. `notApplicable` is true when the wizard
+ *   could never have rendered on this surface, with `reason` naming why.
  *
  * @example
- * const { cleared, status } = await retireFirstRunWizard(page)
- * if (!cleared) {
+ * const { cleared, notApplicable, status } = await retireFirstRunWizard(page)
+ * if (notApplicable) {
+ *   // guest surface — there is no wizard here, and that is fine
+ * } else if (!cleared) {
  *   console.warn(`first-run wizard dismissal returned ${status}`)
  * }
  */
@@ -721,11 +901,77 @@ async function retireFirstRunWizard(page, options = {}) {
 		}
 	}, route).catch(() => -1)
 
-	const installed = status !== 404
+	if (status >= 200 && status < 300) {
+		return { status, installed: true, cleared: true, notApplicable: false, reason: null }
+	}
+	if (status === 404) {
+		return { status, installed: false, cleared: true, notApplicable: false, reason: null }
+	}
+
+	const session = await page.evaluate(readSurfaceSession)
+		.catch(() => ({ user: null, isNextcloudPage: false }))
+
+	// A 401 is Nextcloud's auth layer saying "no session" outright. The second
+	// arm covers instances that answer differently (403, or a redirect that
+	// resolves to something else) but whose page still shows the guest
+	// signature: a request token, no user.
+	if (status === 401 || (session.isNextcloudPage && !session.user)) {
+		return {
+			status,
+			installed: null,
+			cleared: true,
+			notApplicable: true,
+			reason: NO_USER_SESSION,
+		}
+	}
+
+	return { status, installed: true, cleared: false, notApplicable: false, reason: null }
+}
+
+/**
+ * What kind of Nextcloud surface this page is — logged-in app, or guest.
+ *
+ * Exported because the seeding helpers CANNOT answer this for you. They are
+ * meant to be called BEFORE `page.goto()` (that is what makes `addInitScript`
+ * work), and before a navigation there is no document to interrogate: probing
+ * at seed time would be measuring `about:blank`. So the honest split is that
+ * the seeds stay unconditional and cheap, and this is the probe you call AFTER
+ * the page has loaded when you need to know whether any of it mattered.
+ *
+ * Measured on a portaliq public portal page: `data-requesttoken` present,
+ * `data-user` absent, no `CnAppRoot` mounted. That combination is the
+ * signature, and all three parts are required:
+ *
+ *  - a request token proves this is a Nextcloud page, so "no user" means
+ *    logged-out rather than "not a Nextcloud page at all";
+ *  - no user means `CnSupportDialog`'s and `CnWalkthrough`'s per-user state
+ *    cannot be read or written;
+ *  - no mounted `CnAppRoot` means neither overlay was ever instantiated —
+ *    nc-vue auto-mounts both FROM the app root, so no root is no overlays.
+ *
+ * A guest page that DOES mount a `CnAppRoot` is not reported as a guest
+ * surface, because the overlays it mounts are real and still need clearing.
+ *
+ * @param {object} page Playwright `Page`.
+ * @return {Promise<{guest: boolean, user: (string|null), isNextcloudPage: boolean,
+ *   appRoots: string[]}>} The surface facts, and the verdict derived from them.
+ *
+ * @example
+ * const surface = await guestSurfaceStatus(page)
+ * if (surface.guest) {
+ *   // seedSupportDialogSeen / dismissFirstVisitOverlays are no-ops here
+ * }
+ */
+async function guestSurfaceStatus(page) {
+	const session = await page.evaluate(readSurfaceSession)
+		.catch(() => ({ user: null, isNextcloudPage: false }))
+	const appRoots = await mountedAppIds(page).catch(() => [])
+
 	return {
-		status,
-		installed,
-		cleared: (status >= 200 && status < 300) || status === 404,
+		guest: Boolean(session.isNextcloudPage) && !session.user && appRoots.length === 0,
+		user: session.user || null,
+		isNextcloudPage: Boolean(session.isNextcloudPage),
+		appRoots,
 	}
 }
 
@@ -959,6 +1205,11 @@ module.exports = {
 	WALKTHROUGH_STORAGE_PREFIX,
 	CHROME_DIALOG_SELECTORS,
 	FIRST_RUN_WIZARD_ROUTE,
+	// The two `reason` strings. Exported so a spec can compare against the
+	// constant instead of retyping the literal and drifting.
+	NO_USER_SESSION,
+	GUEST_SURFACE,
+	guestSurfaceStatus,
 	seedSupportDialogSeen,
 	seedWalkthroughSeen,
 	seedFirstVisitOverlaysSeen,