sp-walkthrough

Interactive video walkthrough component that overlays timed scenes on a video. Each scene can highlight a DOM element, display a caption, and auto-advance on a timeline. Includes author mode for creating walkthroughs by pointing and clicking elements on the page.

Preview Limitation

Walkthrough examples below use a text-only mode (no video source) to demonstrate scene-based navigation. Full video playback requires an MP4 source and does not work inside documentation iframes. The component's full functionality — video sync, DOM highlighting, and captions — is available when used in a real application.

Installation

Install from a GitHub Release:

npm install https://github.com/StephanWald/trm-ai-webcomponents/releases/download/v0.0.1/skillspilot-webcomponents-0.0.1.tgz

Or load via script tag:

<script type="module" src="https://stephanwald.github.io/trm-ai-webcomponents/wc/skillspilot.esm.js"></script>

Examples

Basic Walkthrough (Manual Navigation)

A walkthrough with no video — scenes advance manually via the Next/Prev buttons. Useful for UI tours without a recorded video.

View / Edit Source

<sp-walkthrough id="wt1"></sp-walkthrough> <button onclick="document.getElementById('wt1').show()" style="margin-top:8px;padding:6px 16px;cursor:pointer"> Show Walkthrough </button> <script> const wt = document.getElementById('wt1'); wt.scenes = [ { id: 's1', caption: 'Welcome! This walkthrough shows you around the interface.', startTime: 0, endTime: 3 }, { id: 's2', caption: 'Step 2: Click the menu button to open the navigation panel.', startTime: 3, endTime: 6 }, { id: 's3', caption: 'Step 3: Select your workspace from the list on the left.', startTime: 6, endTime: 9 } ]; </script>

Author Mode

Enable author mode with author-mode="true" to create new scenes by clicking DOM elements. The component activates a pointer tool and records element selectors into the scene timeline.

View / Edit Source

<p id="para1" style="padding:8px;border:1px solid #ddd;border-radius:4px"> Click on any element while in author mode to record it as a scene target. </p> <button id="btn1" style="padding:6px 16px;cursor:pointer">Sample Button</button> <sp-walkthrough id="wt2" author-mode="true"></sp-walkthrough> <button onclick="document.getElementById('wt2').show()" style="margin-top:8px;padding:6px 16px;cursor:pointer"> Launch Author Mode </button> <script> const wt = document.getElementById('wt2'); wt.scenes = [ { id: 's1', caption: 'Author mode active — click elements to record selector targets.', startTime: 0, endTime: 5 } ]; </script>

Event Handling

Listen to walkthrough-shown, walkthrough-hidden, scene-changed, and timeline-updated events to integrate the walkthrough into your application state.

View / Edit Source

<sp-walkthrough id="wt3"></sp-walkthrough> <button onclick="document.getElementById('wt3').show()" style="padding:6px 16px;cursor:pointer"> Show Walkthrough </button> <div id="evtlog" style="margin-top:8px;padding:8px;background:#f5f5f5;border-radius:4px;font-family:monospace;font-size:0.8rem;min-height:60px;"></div> <script> const wt = document.getElementById('wt3'); const log = document.getElementById('evtlog'); function addLog(msg) { const p = document.createElement('p'); p.style.margin = '2px 0'; p.textContent = new Date().toLocaleTimeString() + ' - ' + msg; log.prepend(p); if (log.children.length > 5) log.lastChild.remove(); } wt.scenes = [ { id: 's1', caption: 'Scene 1: Introduction', startTime: 0, endTime: 4 }, { id: 's2', caption: 'Scene 2: Main feature overview', startTime: 4, endTime: 8 } ]; wt.addEventListener('walkthroughShown', () => addLog('walkthroughShown')); wt.addEventListener('walkthroughHidden', () => addLog('walkthroughHidden')); wt.addEventListener('sceneChanged', e => addLog('sceneChanged: scene ' + e.detail?.id)); wt.addEventListener('timelineUpdated', e => addLog('timelineUpdated: ' + e.detail?.scenes?.length + ' scenes')); </script>

Programmatic Control

Use the component's methods (show(), hide(), play(), pause(), restart(), abort()) to control the walkthrough from your application code.

View / Edit Source

<sp-walkthrough id="wt4"></sp-walkthrough> <div style="display:flex;gap:8px;flex-wrap:wrap;margin-top:8px"> <button onclick="document.getElementById('wt4').show()" style="padding:6px 12px;cursor:pointer">show()</button> <button onclick="document.getElementById('wt4').hide()" style="padding:6px 12px;cursor:pointer">hide()</button> <button onclick="document.getElementById('wt4').restart()" style="padding:6px 12px;cursor:pointer">restart()</button> <button onclick="document.getElementById('wt4').abort()" style="padding:6px 12px;cursor:pointer">abort()</button> </div> <script> const wt = document.getElementById('wt4'); wt.scenes = [ { id: 's1', caption: 'Scene 1: Use the buttons above to control this walkthrough.', startTime: 0, endTime: 5 }, { id: 's2', caption: 'Scene 2: The walkthrough can be hidden or aborted at any time.', startTime: 5, endTime: 10 } ]; </script>

API Reference

Properties

Property	Attribute	Type	Default	Description
authorMode	author-mode	boolean	false	Author mode - enables scene editing and pointer tool
autoPlay	auto-play	boolean	false	Auto-play video on show
captionsSrc	captions-src	string	—	WebVTT captions file URL
scenes	—	Scene[]	[]	Array of walkthrough scenes
theme	theme	"auto" | "dark" | "light"	'auto'	Theme override
videoSrc	video-src	string	—	Video source URL (MP4/WebM/YouTube) - optional for manual-only mode

Events

Event	Detail Type	Description
sceneChanged	SceneChangeDetail	Emitted when scene changes
timelineUpdated	TimelineUpdateDetail	Emitted when timeline is updated (author mode)
walkthroughAborted	void	Emitted when walkthrough is aborted (ESC key or abort method)
walkthroughHidden	void	Emitted when walkthrough is hidden
walkthroughShown	void	Emitted when walkthrough is shown

Methods

Method	Signature	Description
abort	() => Promise<void>	Abort walkthrough (cleans up and hides)
hide	() => Promise<void>	Hide the walkthrough
pause	() => Promise<void>	Pause video
play	() => Promise<void>	Play video
restart	() => Promise<void>	Restart walkthrough from beginning
show	() => Promise<void>	Show the walkthrough

CSS Custom Properties

Property	Description
--dwc-border-radius	Default border radius for buttons, inputs, and control elements
--dwc-border-radius-lg	Large border radius for the walkthrough panel corners
--dwc-color-border	Border color for the panel, control buttons, and scene selector
--dwc-color-border-hover	Border hover color for control buttons
--dwc-color-danger	Danger color for scene delete button text
--dwc-color-danger-bg	Danger background on scene delete button hover
--dwc-color-info-bg	Info background for scene editor panel
--dwc-color-info-border	Info border for scene editor panel
--dwc-color-primary	Primary brand color for controls row background, focus rings
--dwc-color-primary-dark	Darker primary shade for author button hover
--dwc-color-primary-text	Text color on primary-colored surfaces (controls row)
--dwc-color-success	Success color for the active pointer-tool button indicator
--dwc-color-surface	Background color for the walkthrough panel and form inputs
--dwc-color-surface-secondary	Secondary surface color for control buttons and scene list items
--dwc-color-text	Primary text color for scene titles, control buttons, and form labels
--dwc-color-text-secondary	Secondary text color for scene descriptions and counter
--dwc-color-warning	Warning color for selector instability indicators
--dwc-color-warning-bg	Warning background for author toolbar
--dwc-color-warning-border	Warning border for author toolbar
--dwc-font-family	Base font family for all panel text
--dwc-font-size-base	Base font size for scene titles and controls
--dwc-font-size-sm	Small font size for scene descriptions, counter, and author UI
--dwc-font-size-xs	Extra-small font size for metadata labels and form help text
--dwc-font-weight-semibold	Semibold weight for panel title, scene titles, and form labels
--dwc-line-height-normal	Normal line height for scene description text
--dwc-shadow-xl	Extra-large shadow for the floating walkthrough panel
--dwc-spacing-md	Medium spacing for panel content padding and section margins
--dwc-spacing-sm	Small spacing for control bar gaps
--dwc-spacing-xs	Extra-small spacing for tight gaps in controls
--dwc-transition-base	Base transition duration for panel show/hide animation
--dwc-transition-fast	Fast transition duration for button hover states
--dwc-z-modal	Z-index for the walkthrough panel to float above page content