@conduction/nextcloud-vue 2.62.0 → 2.63.0

package/src/components/CnWalkthrough/CnWalkthrough.vue

@@ -25,7 +25,12 @@
 		     the greyed-out area reaches the app, which is the point. A centered
 		     step spotlights nothing, so its backdrop stays interactive and
 		     dismisses the tour. -->
-		<template v-if="isCentered || !rect">
+		<!-- Quiet: an app dialog is open, or the step's target belongs to
+		     another page. No dim and no cutout, so the overlay never sits on
+		     top of the dialog and never invites a click on the wrong page.
+		     Only the docked coachmark stays. -->
+		<template v-if="quiet" />
+		<template v-else-if="isCentered || !rect">
 			<div v-if="isCentered"
 				class="cn-walkthrough__dim cn-walkthrough__dim--full"
 				@click.self="onBackdrop" />
@@ -50,7 +55,7 @@
 		<!-- Coachmark card -->
 		<div ref="card"
 			class="cn-walkthrough__card"
-			:class="`cn-walkthrough__card--${cardPlacement}`"
+			:class="[`cn-walkthrough__card--${cardPlacement}`, { 'cn-walkthrough__card--docked': quiet }]"
 			:style="cardStyle">
 			<NcButton class="cn-walkthrough__close"
 				variant="tertiary"
@@ -183,7 +188,7 @@ export default {
 		translate: { type: Function, default: null },
 	},
 
-	emits: ['complete', 'dismiss', 'step-change', 'advance', 'handoff'],
+	emits: ['complete', 'dismiss', 'pause', 'progress', 'step-change', 'advance', 'handoff'],
 
 	setup(props) {
 		const wt = useWalkthrough(props.appId, props.manifest, {
@@ -200,6 +205,10 @@ export default {
 			cardPos: { top: 0, left: 0 },
 			cardPlacement: 'bottom',
 			targetEl: null,
+			// An app dialog (NcModal / NcDialog) is open over the page.
+			appModalOpen: false,
+			// The step's target was found on another page than the current one.
+			offPage: false,
 		}
 	},
 
@@ -228,6 +237,18 @@ export default {
 			return this.wt.isLast.value
 		},
 
+		/**
+		 * Whether the overlay steps back: no dim, no cutout, a docked card.
+		 * True while an app dialog is open or the step's target is on
+		 * another page.
+		 *
+		 * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+		 * @return {boolean}
+		 */
+		quiet() {
+			return this.appModalOpen || this.offPage
+		},
+
 		isCentered() {
 			return this.step && this.step.placement === 'center'
 		},
@@ -321,6 +342,9 @@ export default {
 		},
 
 		cardStyle() {
+			if (this.quiet) {
+				return {}
+			}
 			if (this.isCentered || !this.rect) {
 				return { top: '50%', left: '50%', transform: 'translate(-50%, -50%)' }
 			}
@@ -339,6 +363,18 @@ export default {
 				 * @type {{ stepId: string, index: number }}
 				 */
 				this.$emit('step-change', { stepId: newStep.id, index: this.index })
+				/**
+				 * @event progress Emitted on every step change so the host can remember where the user is.
+				 * @type {{ tourId: string, stepId: string, index: number }}
+				 */
+				this.$emit('progress', {
+					tourId: (this.wt.activeTour.value && this.wt.activeTour.value.id) || '',
+					stepId: newStep.id,
+					index: this.index,
+				})
+				// A new step finds its own page again.
+				this._homeRoute = null
+				this.offPage = false
 				this.$nextTick(() => this.locateTarget())
 			}
 		},
@@ -377,6 +413,9 @@ export default {
 		// A qualifying auto-start tour whose first-step page is NOT the current
 		// route — held here until the user navigates to that page (see hookRouter).
 		this._pendingAutoTour = null
+		// The route the active step's target was first found on (see locateTarget).
+		this._homeRoute = null
+		this._modalObs = null
 	},
 
 	mounted() {
@@ -386,12 +425,27 @@ export default {
 		window.addEventListener('scroll', this._onScroll, true)
 		window.addEventListener('resize', this._onScroll)
 		this._onKey = (e) => {
-			if (e.key === 'Escape') {
-				this.onBackdrop()
+			if (e.key !== 'Escape' || !this.active) {
+				return
 			}
+			// ESC while an app dialog is open belongs to that dialog. It used
+			// to dismiss the tour too, so closing a create form ended it.
+			if (this.isAppModalOpen()) {
+				return
+			}
+			this.onBackdrop()
 		}
 		window.addEventListener('keydown', this._onKey)
-		this._onObjectCreated = (e) => this.wt.notify({ kind: 'object-created', object: (e && e.detail) || {} })
+		this._onObjectCreated = (e) => {
+			const d = (e && e.detail) || {}
+			this.wt.notify({
+				kind: 'object-created',
+				register: d.register,
+				schema: d.schema,
+				object: d.object && typeof d.object === 'object' ? d.object : d,
+			})
+		}
+		this.watchAppModals()
 		window.addEventListener('cn-walkthrough:object-created', this._onObjectCreated)
 		this.hookRouter()
 		if (this.active) {
@@ -404,6 +458,10 @@ export default {
 		window.removeEventListener('resize', this._onScroll)
 		window.removeEventListener('keydown', this._onKey)
 		window.removeEventListener('cn-walkthrough:object-created', this._onObjectCreated)
+		if (this._modalObs) {
+			this._modalObs.disconnect()
+			this._modalObs = null
+		}
 		if (typeof this._routeUnhook === 'function') {
 			this._routeUnhook()
 		}
@@ -411,6 +469,51 @@ export default {
 	},
 
 	methods: {
+		/**
+		 * Whether an app dialog (NcModal / NcDialog, or any other modal
+		 * dialog that is not this overlay) is open.
+		 *
+		 * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+		 * @return {boolean}
+		 */
+		isAppModalOpen() {
+			if (typeof document === 'undefined') {
+				return false
+			}
+			const own = this.$el
+			const nodes = document.querySelectorAll('.modal-mask, [role="dialog"][aria-modal="true"]')
+			for (const node of nodes) {
+				if (own && typeof own.contains === 'function' && (own === node || own.contains(node))) {
+					continue
+				}
+				return true
+			}
+			return false
+		},
+
+		/**
+		 * Follow app dialogs opening and closing, so the overlay steps back
+		 * while one is open and comes back after.
+		 *
+		 * @return {void}
+		 */
+		watchAppModals() {
+			const update = () => {
+				const open = this.isAppModalOpen()
+				if (open !== this.appModalOpen) {
+					this.appModalOpen = open
+					if (!open && this.active) {
+						this.$nextTick(() => this.locateTarget())
+					}
+				}
+			}
+			update()
+			if (typeof window !== 'undefined' && window.MutationObserver) {
+				this._modalObs = new MutationObserver(update)
+				this._modalObs.observe(document.body, { childList: true, subtree: true })
+			}
+		},
+
 		/**
 		 * Translate an i18n key/text via the `translate` prop when given.
 		 *
@@ -598,6 +701,23 @@ export default {
 				return
 			}
 			const el = this.resolveTarget(this.step)
+			// A step's target belongs to the page it was first found on. The
+			// same `index-add` button exists on every list page, and a step
+			// left half-done on Products used to spotlight the Clients page's
+			// button too, inviting a click that belonged to another step.
+			const kind = (this.step.target && this.step.target.kind) || ''
+			const routeName = this.$route ? this.$route.name : null
+			if (el && kind !== 'page' && kind !== 'nav-item' && routeName) {
+				if (this._homeRoute === null) {
+					this._homeRoute = routeName
+				} else if (this._homeRoute !== routeName) {
+					this.offPage = true
+					this.targetEl = null
+					this.rect = null
+					return
+				}
+			}
+			this.offPage = false
 			this.targetEl = el
 			if (!el) {
 				// Optional step whose target is absent → skip; else wait for it.
@@ -862,6 +982,10 @@ export default {
 		 * @return {void}
 		 */
 		focusCard() {
+			// Never take focus from an open app dialog.
+			if (this.appModalOpen) {
+				return
+			}
 			this.$nextTick(() => {
 				const btn = this.$refs.firstBtn && this.$refs.firstBtn.$el
 				if (btn && typeof btn.focus === 'function') {
@@ -1058,16 +1182,20 @@ export default {
 		},
 
 		/**
-		 * Dismiss the tour from a backdrop click or ESC.
+		 * Pause the tour from a backdrop click or ESC. The tour hides and
+		 * keeps its step; only Skip (the close button) and Finish end it.
+		 * Pressing ESC used to dismiss it, and the host recorded that as
+		 * "seen", so the tour never came back.
 		 *
+		 * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
 		 * @return {void}
 		 */
 		onBackdrop() {
-			this.wt.dismiss()
+			this.wt.pause()
 			/**
-			 * @event dismiss Emitted when the user dismisses the tour (backdrop / ESC).
+			 * @event pause Emitted when the user hides the tour (backdrop / ESC). The tour can continue later.
 			 */
-			this.$emit('dismiss')
+			this.$emit('pause')
 		},
 	},
 }
@@ -1126,6 +1254,11 @@ export default {
 	pointer-events: auto;
 }
 
+.cn-walkthrough__card--docked {
+	inset-block-end: 16px;
+	inset-inline-start: 16px;
+}
+
 .cn-walkthrough__close {
 	/* !important beats NcButton's own `position: relative`, which would otherwise
 	   leave the close button in-flow at the card's top-left. */

package/src/components/CnWidgetGrid/builtInWidgets.js

@@ -25,6 +25,7 @@ import CnObjectGeoWidget from '../CnObjectGeoWidget/CnObjectGeoWidget.vue'
 import CnObjectMetadataWidget from '../CnObjectMetadataWidget/CnObjectMetadataWidget.vue'
 import CnRelatedObjectsWidget from '../CnRelatedObjectsWidget/CnRelatedObjectsWidget.vue'
 import CnTextWidget from '../CnTextWidget/CnTextWidget.vue'
+import CnTimelineWidget from '../CnTimelineWidget/CnTimelineWidget.vue'
 import CnWidgetCardGrid from '../CnWidgetCardGrid/CnWidgetCardGrid.vue'
 import CnWidgetFormRenderer from '../CnWidgetFormRenderer/CnWidgetFormRenderer.vue'
 import CnWidgetMapViewer from '../CnWidgetMapViewer/CnWidgetMapViewer.vue'
@@ -84,6 +85,7 @@ export const BUILT_IN_WIDGETS = {
 	integration: CnIntegrationWidget,
 	banner: CnBannerWidget,
 	'audit-trail': CnAuditTrailWidget,
+	timeline: CnTimelineWidget,
 	header: CnHeaderWidget,
 	text: CnTextWidget,
 	divider: CnDividerWidget,

package/src/components/CnWidgetGrid/registerDashboardWidgets.js

@@ -72,6 +72,7 @@ import '../CnObjectDataWidget/dashboardRegistration.js'
 import '../CnObjectGeoWidget/dashboardRegistration.js'
 import '../CnWidgetObjectTable/dashboardRegistration.js'
 import '../CnAuditTrailWidget/dashboardRegistration.js'
+import '../CnTimelineWidget/dashboardRegistration.js'
 import '../CnKbSearchWidget/index.js'
 import '../CnInteractionFormWidget/index.js'
 import '../CnBannerWidget/index.js'

package/src/components/CnWizardDialog/CnWizardDialog.vue

@@ -105,7 +105,7 @@
 				</NcButton>
 				<NcButton variant="primary"
 					data-testid="cn-wizard-next"
-					:disabled="loading"
+					:disabled="loading || nextDisabled"
 					@click="isLast ? submit() : next()">
 					<template #icon>
 						<NcLoadingIcon v-if="loading" :size="20" />
@@ -280,6 +280,19 @@ export default {
 			type: Boolean,
 			default: true,
 		},
+
+		/**
+		 * Disable the Next / Submit button, whatever the step's `validate`
+		 * would say. For a host that knows the wizard cannot go on yet, such as
+		 * `CnSetupWizard` while a required app is missing.
+		 *
+		 * @type {boolean}
+		 * @spec openspec/changes/setup-wizard-card-load-and-dependency-gate/specs/cn-setup-wizard/spec.md#requirement-the-wizard-checks-dependencies-before-any-step
+		 */
+		nextDisabled: {
+			type: Boolean,
+			default: false,
+		},
 	},
 
 	emits: ['close', 'step-change', 'submit'],
@@ -396,6 +409,9 @@ export default {
 		 * @return {Promise<void>}
 		 */
 		async next() {
+			if (this.nextDisabled) {
+				return
+			}
 			if (this.isLast) {
 				return this.submit()
 			}
@@ -467,6 +483,9 @@ export default {
 		 * @return {Promise<void>}
 		 */
 		async submit() {
+			if (this.nextDisabled) {
+				return
+			}
 			const ok = await this.runValidation()
 			if (!ok) {
 				return

package/src/components/index.js

@@ -17,6 +17,7 @@ export { CnLeafDependencySettings } from './CnLeafDependencySettings/index.js'
 export { CnStatsBlock } from './CnStatsBlock/index.js'
 export { CnStructuredDocReview } from './CnStructuredDocReview/index.js'
 export { CnConfigurationCard } from './CnConfigurationCard/index.js'
+export { CnAdminActionCard } from './CnAdminActionCard/index.js'
 export { CnVersionInfoCard } from './CnVersionInfoCard/index.js'
 export { CnAdminSettingsShell } from './CnAdminSettingsShell/index.js'
 export { CnCellRenderer } from './CnCellRenderer/index.js'
@@ -103,6 +104,7 @@ export { CnSearchPage } from './CnSearchPage/index.js'
 export { CnCommandPalette } from './CnCommandPalette/index.js'
 export { CnTabbedFormDialog } from './CnTabbedFormDialog/index.js'
 export { CnTimelineStages } from './CnTimelineStages/index.js'
+export { CnTimelineWidget } from './CnTimelineWidget/index.js'
 export { CnTreeView } from './CnTreeView/index.js'
 export { CnUserActionMenu } from './CnUserActionMenu/index.js'
 export { CnNotesCard } from './CnNotesCard/index.js'

package/src/composables/useDependencyCheck.js

@@ -0,0 +1,61 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+import { useAppStatus } from './useAppStatus.js'
+
+/**
+ * Resolve `manifest.dependencies` entries to their live status.
+ *
+ * Accepts the manifest's own shape: an app-id string (a REQUIRED dependency)
+ * or `{ id, name?, required? }` where `required` defaults to true. Each entry
+ * becomes `{ id, name, required, installed, enabled }`.
+ *
+ * `serverStatuses` is the optional `dependency_statuses` initial state an app
+ * injects from PHP, keyed by app id: `{ installed, enabled }`. It wins over
+ * the browser heuristic, because only the server can tell "installed but
+ * disabled" from "not installed". Without it, `useAppStatus` answers, which
+ * is the same resolution `CnAppRoot` uses for its dependency-missing phase.
+ *
+ * @param {Array<string|{id: string, name?: string, required?: boolean}>} entries The declared dependencies.
+ * @param {object} [serverStatuses] Server-reported statuses keyed by app id.
+ * @return {Array<{id: string, name: string, required: boolean, installed: boolean, enabled: boolean}>} One row per valid entry.
+ *
+ * @spec openspec/changes/setup-wizard-card-load-and-dependency-gate/specs/cn-setup-wizard/spec.md#requirement-the-wizard-checks-dependencies-before-any-step
+ *
+ * @example
+ * const missing = checkDependencies(manifest.dependencies)
+ *   .filter((d) => d.required && !(d.installed && d.enabled))
+ */
+export function checkDependencies(entries, serverStatuses = {}) {
+	const list = Array.isArray(entries) ? entries : []
+	const server = (serverStatuses && typeof serverStatuses === 'object') ? serverStatuses : {}
+	return list
+		.map((entry) => {
+			const isObject = entry !== null && typeof entry === 'object'
+			const id = isObject ? entry.id : entry
+			if (typeof id !== 'string' || id === '') {
+				return null
+			}
+			const required = isObject ? entry.required !== false : true
+			const name = (isObject && entry.name) || id
+			const reported = server[id]
+			if (reported !== undefined && reported !== null) {
+				return { id, name, required, installed: !!reported.installed, enabled: !!reported.enabled }
+			}
+			const status = useAppStatus(id)
+			return { id, name, required, installed: !!status.installed.value, enabled: !!status.enabled.value }
+		})
+		.filter((row) => row !== null)
+}
+
+/**
+ * Whether a resolved dependency row is usable: installed AND enabled.
+ *
+ * @param {{installed: boolean, enabled: boolean}} row A row from `checkDependencies`.
+ * @return {boolean} True when the app can be used.
+ */
+export function isDependencyResolved(row) {
+	return !!row && row.installed === true && row.enabled === true
+}

package/src/composables/useWalkthrough.js

@@ -199,6 +199,162 @@ export function persistWalkthroughSeenVersion(appId, configKey, version, options
 	}
 }
 
+/**
+ * localStorage key prefix for the per-browser mirror of tour progress.
+ */
+export const WALKTHROUGH_PROGRESS_STORAGE_PREFIX = 'cn-walkthrough-progress:'
+
+/**
+ * The preference key that holds tour progress, next to the completion key.
+ *
+ * @param {string} configKey `manifest.walkthrough.completionConfigKey` (may be empty).
+ * @return {string} `<configKey>-progress`, or '' when no key is declared.
+ */
+export function walkthroughProgressKey(configKey) {
+	return configKey ? configKey + '-progress' : ''
+}
+
+/**
+ * Normalise stored progress (an object, or the JSON string a preference
+ * holds) into `{ tourId, stepId, index, version }`, or null.
+ *
+ * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+ * @param {unknown} value The stored value.
+ * @return {{tourId: string, stepId: string, index: number, version: string}|null} The progress.
+ */
+export function normaliseWalkthroughProgress(value) {
+	let data = value
+	if (typeof data === 'string') {
+		if (data === '') {
+			return null
+		}
+		try {
+			data = JSON.parse(data)
+		} catch {
+			return null
+		}
+	}
+	if (!isPlainObject(data) || typeof data.tourId !== 'string' || data.tourId === '') {
+		return null
+	}
+	return {
+		tourId: data.tourId,
+		stepId: typeof data.stepId === 'string' ? data.stepId : '',
+		index: Number.isInteger(data.index) && data.index >= 0 ? data.index : 0,
+		version: typeof data.version === 'string' ? data.version : '',
+	}
+}
+
+/**
+ * Read the per-browser mirror of the tour progress. Synchronous.
+ *
+ * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+ * @param {string} appId The Nextcloud app id.
+ * @param {Storage} [storage] Injectable storage backend.
+ * @return {object|null} The progress, or null.
+ */
+export function readLocalWalkthroughProgress(appId, storage) {
+	const s = resolveStorage(storage)
+	if (!s) {
+		return null
+	}
+	try {
+		return normaliseWalkthroughProgress(s.getItem(WALKTHROUGH_PROGRESS_STORAGE_PREFIX + appId))
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Load the user's tour progress: the per-user preference
+ * `<completionConfigKey>-progress` when declared, else the local mirror.
+ *
+ * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+ * @param {string} appId The Nextcloud app id.
+ * @param {string} configKey `manifest.walkthrough.completionConfigKey` (may be empty).
+ * @param {object} [options] `{ http, storage }` injection points for tests.
+ * @return {Promise<object|null>} The progress, or null.
+ */
+export async function loadWalkthroughProgress(appId, configKey, options = {}) {
+	const local = readLocalWalkthroughProgress(appId, options.storage)
+	const key = walkthroughProgressKey(configKey)
+	if (!key) {
+		return local
+	}
+	const http = options.http || axios
+	try {
+		const { data } = await http.get(walkthroughPreferenceUrl(appId, key))
+		if (!isPlainObject(data) || !('value' in data)) {
+			return local
+		}
+		return normaliseWalkthroughProgress(data.value) || local
+	} catch {
+		return local
+	}
+}
+
+/**
+ * Persist the user's tour progress, or clear it with `null`. Writes the
+ * local mirror and, with a completion key, the per-user preference. Never
+ * throws.
+ *
+ * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+ * @param {string} appId The Nextcloud app id.
+ * @param {string} configKey `manifest.walkthrough.completionConfigKey` (may be empty).
+ * @param {object|null} progress `{ tourId, stepId, index, version }`, or null to clear.
+ * @param {object} [options] `{ http, storage }` injection points for tests.
+ * @return {Promise<boolean>} True when the server preference was written.
+ */
+export function persistWalkthroughProgress(appId, configKey, progress, options = {}) {
+	const value = progress ? normaliseWalkthroughProgress(progress) : null
+	const raw = value ? JSON.stringify(value) : ''
+	const s = resolveStorage(options.storage)
+	if (s) {
+		try {
+			if (raw) {
+				s.setItem(WALKTHROUGH_PROGRESS_STORAGE_PREFIX + appId, raw)
+			} else {
+				s.removeItem(WALKTHROUGH_PROGRESS_STORAGE_PREFIX + appId)
+			}
+		} catch {
+			/* quota / private mode: best-effort */
+		}
+	}
+	const key = walkthroughProgressKey(configKey)
+	if (!key) {
+		return Promise.resolve(false)
+	}
+	const http = options.http || axios
+	try {
+		return Promise.resolve(http.put(walkthroughPreferenceUrl(appId, key), { value: raw }))
+			.then(() => true)
+			.catch(() => false)
+	} catch {
+		return Promise.resolve(false)
+	}
+}
+
+/**
+ * Whether an `object-created` signal satisfies a step's `advanceOn`.
+ *
+ * The signal's own `register` / `schema` (the slugs the creating surface
+ * knows) are compared first; an object's `@self` values are numeric ids on
+ * OpenRegister and only match a step that also uses ids.
+ *
+ * @param {object} advanceOn The step's `advanceOn`.
+ * @param {object} signal `{ register?, schema?, object? }`.
+ * @return {boolean} True when it matches.
+ */
+function objectCreatedMatches(advanceOn, signal) {
+	const obj = signal.object || {}
+	const self = obj['@self'] || {}
+	const same = (want, candidates) => !want || candidates
+		.filter((c) => c !== null && c !== undefined && c !== '')
+		.some((c) => String(c).toLowerCase() === String(want).toLowerCase())
+	return same(advanceOn.register, [signal.register, obj.register, self.register])
+		&& same(advanceOn.schema, [signal.schema, obj.schema, self.schema])
+}
+
 /**
  * Compare two semver-ish strings. Missing / unparseable parts sort as 0.
  *
@@ -276,6 +432,9 @@ export function useWalkthrough(appId, manifest, options = {}) {
 		const currentIndex = ref(0)
 		const context = ref({})
 		const running = ref(false)
+		// True while the tour is hidden by ESC or a backdrop click. The tour
+		// and its step stay, so it continues where it was.
+		const paused = ref(false)
 		// True while a user-initiated replay is active (the "Restart tutorial"
 		// entry). A replay shows the FULL tour regardless of the persisted
 		// seen-version — otherwise a returning user, whose seenVersion already
@@ -479,6 +638,7 @@ export function useWalkthrough(appId, manifest, options = {}) {
 		 */
 		function start(tourId, startIndex = 0) {
 			replaying.value = false
+			paused.value = false
 			activeTourId.value = tourId
 			currentIndex.value = startIndex
 			context.value = {}
@@ -503,9 +663,59 @@ export function useWalkthrough(appId, manifest, options = {}) {
 		 */
 		function dismiss() {
 			running.value = false
+			paused.value = false
 			activeTourId.value = null
 			replaying.value = false
 		}
+		/**
+		 * Hide the active tour without ending it (ESC, a click on the dim).
+		 * The tour and step are kept, so `resumePaused()` continues there.
+		 *
+		 * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+		 * @return {void}
+		 */
+		function pause() {
+			if (!activeTourId.value) {
+				return
+			}
+			running.value = false
+			paused.value = true
+		}
+		/**
+		 * Show a paused tour again at the step it was on.
+		 *
+		 * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+		 * @return {boolean} True when there was a paused tour to show.
+		 */
+		function resumePaused() {
+			if (!paused.value || !activeTourId.value) {
+				return false
+			}
+			paused.value = false
+			running.value = true
+			return true
+		}
+		/**
+		 * Start a tour at a remembered step ("continue where you left off").
+		 * Runs in replay mode so a returning user sees the full tour, and
+		 * falls back to the first step when the step no longer exists.
+		 *
+		 * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+		 * @param {string} tourId The tour id.
+		 * @param {string} [stepId] The step to continue at.
+		 * @return {boolean} True when the tour exists and started.
+		 */
+		function resumeAt(tourId, stepId) {
+			const tour = tours.find((t) => t.id === tourId)
+			if (!tour) {
+				return false
+			}
+			replaying.value = true
+			const idx = composeSteps(tour).findIndex((s) => s.id === stepId)
+			start(tourId, Math.max(0, idx))
+			replaying.value = true
+			return true
+		}
 		/**
 		 * Mark the active tour complete: stop running and invoke the
 		 * `onComplete(appVersion)` persistence callback so the seen version is
@@ -515,6 +725,7 @@ export function useWalkthrough(appId, manifest, options = {}) {
 		 */
 		function complete() {
 			running.value = false
+			paused.value = false
 			activeTourId.value = null
 			replaying.value = false
 			if (typeof options.onComplete === 'function') {
@@ -542,12 +753,9 @@ export function useWalkthrough(appId, manifest, options = {}) {
 					runCapture(step, { params: signal.params || {} })
 				}
 			} else if (signal.kind === 'object-created' && a.type === 'object-created') {
-				const obj = signal.object || {}
-				const reg = obj.register ?? obj['@self']?.register
-				const sch = obj.schema ?? obj['@self']?.schema
-				match = (!a.register || reg === a.register) && (!a.schema || sch === a.schema)
+				match = objectCreatedMatches(a, signal)
 				if (match) {
-					runCapture(step, { object: obj })
+					runCapture(step, { object: signal.object || {} })
 				}
 			} else if (signal.kind === 'element' && a.type === 'element-appears') {
 				match = true
@@ -575,9 +783,13 @@ export function useWalkthrough(appId, manifest, options = {}) {
 			isLast,
 			context,
 			running,
+			paused,
 			replaying,
 			start,
 			restart,
+			pause,
+			resumePaused,
+			resumeAt,
 			next,
 			back,
 			skip,