Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat: add Walkthrough Studio builtin extension

Juan Denis3a34358ae1d0
diff --git a/builtin-extensions/serverkit-walkthrough-studio/frontend/index.jsx b/builtin-extensions/serverkit-walkthrough-studio/frontend/index.jsx
new file mode 100644
index 00000000..97ddd853
--- /dev/null
+++ b/builtin-extensions/serverkit-walkthrough-studio/frontend/index.jsx
@@ -0,0 +1,554 @@
+import {
+ ArrowDown,
+ ArrowUp,
+ BookOpenCheck,
+ Braces,
+ Copy,
+ Download,
+ Eye,
+ FileUp,
+ GripVertical,
+ Plus,
+ Save,
+ Sparkles,
+ Trash2,
+} from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import {
+ api,
+ Button,
+ copyToClipboard,
+ downloadBlob,
+ emitWalkthroughSignal,
+ PageTopbar,
+ useAuth,
+ useConfirm,
+ useToast,
+ useWalkthroughs,
+ validateWalkthroughDefinition,
+ WALKTHROUGH_COMPLETION_TYPES,
+} from '../sdk';
+
+import './styles/walkthrough-studio.scss';
+
+
+function createInitialStep(t) {
+ return {
+ id: 'open-page',
+ title: t('walkthroughStudio.initialStepTitle', 'Open the page'),
+ description: t('walkthroughStudio.initialStepDescription', 'Navigate to the place where this task begins.'),
+ action: t('walkthroughStudio.initialStepAction', 'Open page'),
+ path: '/',
+ target: '',
+ completion: { type: 'route', path: '/' },
+ };
+}
+
+function createGuide(t) {
+ return {
+ id: 'my-walkthrough',
+ title: t('walkthroughStudio.initialTitle', 'My walkthrough'),
+ description: t('walkthroughStudio.initialDescription', 'Help an operator complete one clear outcome.'),
+ duration: 'About 5 minutes',
+ icon: 'guide',
+ tone: 'cyan',
+ secondary: true,
+ permissions: [],
+ steps: [createInitialStep(t)],
+ };
+}
+
+function slugify(value, fallback) {
+ const slug = String(value || '')
+ .toLowerCase()
+ .trim()
+ .replace(/[^a-z0-9._-]+/g, '-')
+ .replace(/^-+|-+$/g, '')
+ .slice(0, 80);
+ return slug || fallback;
+}
+
+function completionTypeLabel(t, value) {
+ const labels = {
+ manual: t('walkthroughStudio.completionManual', 'Manual confirmation'),
+ route: t('walkthroughStudio.completionRouteReached', 'Route reached'),
+ signal: t('walkthroughStudio.completionSignal', 'Success signal received'),
+ check: t('walkthroughStudio.completionCheck', 'Named status check'),
+ target: t('walkthroughStudio.completionTarget', 'Target becomes visible'),
+ };
+ return labels[value] || value;
+}
+
+function Field({ label, hint, children }) {
+ return (
+ <label className="wts-field">
+ <span className="wts-field__label">{label}</span>
+ {children}
+ {hint && <small>{hint}</small>}
+ </label>
+ );
+}
+
+function CompletionFields({ step, onChange, t }) {
+ const type = step.completion?.type || 'manual';
+ if (type === 'signal') {
+ return (
+ <Field
+ label={t('walkthroughStudio.signalName', 'Success signal')}
+ hint={t('walkthroughStudio.signalHint', 'Emit this token only after the operation succeeds.')}
+ >
+ <input
+ value={step.completion.signal || ''}
+ onChange={(event) => onChange({ ...step.completion, signal: slugify(event.target.value, '') })}
+ placeholder="extension.resource-created"
+ />
+ </Field>
+ );
+ }
+ if (type === 'check') {
+ return (
+ <Field
+ label={t('walkthroughStudio.checkName', 'Named host check')}
+ hint={t('walkthroughStudio.checkHint', 'Checks must be implemented and allowlisted by the host.')}
+ >
+ <input
+ value={step.completion.check || ''}
+ onChange={(event) => onChange({ ...step.completion, check: slugify(event.target.value, '') })}
+ placeholder="extension.resource-ready"
+ />
+ </Field>
+ );
+ }
+ if (type === 'route') {
+ return (
+ <Field label={t('walkthroughStudio.completionRoute', 'Completion route')}>
+ <input
+ value={step.completion.path || ''}
+ onChange={(event) => onChange({ ...step.completion, path: event.target.value })}
+ placeholder="/services"
+ />
+ </Field>
+ );
+ }
+ if (type === 'target') {
+ return (
+ <p className="wts-callout">
+ {t('walkthroughStudio.targetCompletionHint', 'This step completes when its data-walkthrough target becomes visible.')}
+ </p>
+ );
+ }
+ return (
+ <p className="wts-callout">
+ {t('walkthroughStudio.manualCompletionHint', 'The operator uses Done · next step after completing the instruction.')}
+ </p>
+ );
+}
+
+function GuidePreview({ guide, issues, onRun, t }) {
+ return (
+ <aside className="wts-preview" data-walkthrough="studio-preview">
+ <div className="wts-panel-heading">
+ <span>{t('walkthroughStudio.livePreview', 'Live preview')}</span>
+ <span className={`wts-validity${issues.length ? ' is-invalid' : ''}`}>
+ {issues.length
+ ? t('walkthroughStudio.issueCount', '{{count}} issues', { count: issues.length })
+ : t('walkthroughStudio.valid', 'Valid')}
+ </span>
+ </div>
+
+ <div className={`wts-guide-card is-${guide.tone || 'cyan'}`}>
+ <span className="wts-guide-card__kicker">{guide.secondary ? 'OPTIONAL GUIDE' : 'ESSENTIAL GUIDE'}</span>
+ <h2>{guide.title || t('walkthroughStudio.untitled', 'Untitled walkthrough')}</h2>
+ <p>{guide.description || t('walkthroughStudio.addDescription', 'Add a description to explain the outcome.')}</p>
+ <div className="wts-guide-card__meta">
+ <span>{guide.steps?.length || 0} {t('walkthroughStudio.steps', 'steps')}</span>
+ <span>{guide.duration || t('walkthroughStudio.noDuration', 'No duration')}</span>
+ </div>
+ </div>
+
+ <ol className="wts-preview-steps">
+ {(guide.steps || []).map((step, index) => (
+ <li key={`${step.id}-${index}`}>
+ <span>{String(index + 1).padStart(2, '0')}</span>
+ <div>
+ <strong>{step.title || t('walkthroughStudio.untitledStep', 'Untitled step')}</strong>
+ <small>{step.completion?.type || 'manual'} · {step.target || t('walkthroughStudio.noTarget', 'no target')}</small>
+ </div>
+ </li>
+ ))}
+ </ol>
+
+ {issues.length > 0 && (
+ <div className="wts-issues" role="alert">
+ {issues.slice(0, 6).map((item) => (
+ <p key={`${item.path}:${item.message}`}><strong>{item.path || 'guide'}</strong> {item.message}</p>
+ ))}
+ </div>
+ )}
+
+ <Button type="button" variant="outline" onClick={onRun} disabled={issues.length > 0}>
+ <Eye size={14} /> {t('walkthroughStudio.runInDock', 'Run in walkthrough dock')}
+ </Button>
+
+ <details className="wts-json">
+ <summary><Braces size={14} /> {t('walkthroughStudio.definitionJson', 'Definition JSON')}</summary>
+ <pre>{JSON.stringify(guide, null, 2)}</pre>
+ </details>
+ </aside>
+ );
+}
+
+export function WalkthroughStudioPage() {
+ const { t } = useTranslation();
+ const toast = useToast();
+ const { confirm } = useConfirm();
+ const { isAdmin } = useAuth();
+ const { preview, refreshDefinitions } = useWalkthroughs();
+ const importRef = useRef(null);
+ const [library, setLibrary] = useState([]);
+ const [draft, setDraft] = useState(() => createGuide(t));
+ const [originalId, setOriginalId] = useState(null);
+ const [stepIndex, setStepIndex] = useState(0);
+ const [loading, setLoading] = useState(true);
+ const [saving, setSaving] = useState(false);
+
+ const issues = useMemo(() => validateWalkthroughDefinition(draft), [draft]);
+ const activeStep = draft.steps?.[stepIndex] || null;
+
+ const loadLibrary = useCallback(async () => {
+ setLoading(true);
+ try {
+ const response = await api.getWalkthroughDefinitions();
+ setLibrary(Array.isArray(response?.definitions) ? response.definitions : []);
+ } catch (error) {
+ toast.error(error.message || t('walkthroughStudio.loadFailed', 'Could not load the walkthrough library.'));
+ } finally {
+ setLoading(false);
+ }
+ }, [t, toast]);
+
+ useEffect(() => { loadLibrary(); }, [loadLibrary]);
+
+ const updateGuide = (patch) => setDraft((current) => ({ ...current, ...patch }));
+ const updateStep = (patch) => setDraft((current) => ({
+ ...current,
+ steps: current.steps.map((step, index) => (
+ index === stepIndex ? { ...step, ...patch } : step
+ )),
+ }));
+
+ const selectGuide = (guide) => {
+ setDraft(JSON.parse(JSON.stringify(guide)));
+ setOriginalId(guide.id);
+ setStepIndex(0);
+ };
+
+ const newGuide = () => {
+ setDraft(createGuide(t));
+ setOriginalId(null);
+ setStepIndex(0);
+ };
+
+ const addStep = () => {
+ setDraft((current) => {
+ const nextNumber = current.steps.length + 1;
+ return {
+ ...current,
+ steps: [...current.steps, {
+ id: `step-${nextNumber}`,
+ title: t('walkthroughStudio.numberedStep', 'Step {{number}}', { number: nextNumber }),
+ description: t('walkthroughStudio.newStepDescription', 'Describe the operator action and the expected outcome.'),
+ action: 'Open page',
+ path: '/',
+ target: '',
+ completion: { type: 'manual' },
+ }],
+ };
+ });
+ setStepIndex(draft.steps.length);
+ };
+
+ const moveStep = (direction) => {
+ const nextIndex = stepIndex + direction;
+ if (nextIndex < 0 || nextIndex >= draft.steps.length) return;
+ setDraft((current) => {
+ const steps = [...current.steps];
+ [steps[stepIndex], steps[nextIndex]] = [steps[nextIndex], steps[stepIndex]];
+ return { ...current, steps };
+ });
+ setStepIndex(nextIndex);
+ };
+
+ const deleteStep = () => {
+ if (draft.steps.length <= 1) {
+ toast.warning(t('walkthroughStudio.keepOneStep', 'A walkthrough needs at least one step.'));
+ return;
+ }
+ setDraft((current) => ({
+ ...current,
+ steps: current.steps.filter((_, index) => index !== stepIndex),
+ }));
+ setStepIndex((current) => Math.max(0, current - 1));
+ };
+
+ const saveGuide = async () => {
+ if (!isAdmin) {
+ toast.error(t('walkthroughStudio.adminRequired', 'Administrator access is required to publish walkthroughs.'));
+ return;
+ }
+ if (issues.length > 0) {
+ toast.warning(t('walkthroughStudio.fixIssues', 'Fix the validation issues before publishing.'));
+ return;
+ }
+ setSaving(true);
+ try {
+ const withoutOriginal = library.filter((guide) => guide.id !== originalId && guide.id !== draft.id);
+ const nextLibrary = [...withoutOriginal, draft];
+ const response = await api.updateWalkthroughDefinitions(nextLibrary);
+ setLibrary(response.definitions || nextLibrary);
+ setOriginalId(draft.id);
+ await refreshDefinitions();
+ emitWalkthroughSignal('walkthrough-studio-guide-saved', { guideId: draft.id });
+ toast.success(t('walkthroughStudio.published', 'Walkthrough published.'));
+ } catch (error) {
+ toast.error(error.message || t('walkthroughStudio.publishFailed', 'Could not publish the walkthrough.'));
+ } finally {
+ setSaving(false);
+ }
+ };
+
+ const deleteGuide = async (guide) => {
+ if (!await confirm({
+ title: t('walkthroughStudio.deleteTitle', 'Delete walkthrough'),
+ message: t('walkthroughStudio.deleteMessage', 'Delete “{{title}}” from the shared walkthrough library?', { title: guide.title }),
+ confirmText: t('common.actions.delete', 'Delete'),
+ })) return;
+ try {
+ const nextLibrary = library.filter((item) => item.id !== guide.id);
+ await api.updateWalkthroughDefinitions(nextLibrary);
+ setLibrary(nextLibrary);
+ if (originalId === guide.id) newGuide();
+ await refreshDefinitions();
+ toast.success(t('walkthroughStudio.deleted', 'Walkthrough deleted.'));
+ } catch (error) {
+ toast.error(error.message || t('walkthroughStudio.deleteFailed', 'Could not delete the walkthrough.'));
+ }
+ };
+
+ const importFile = async (event) => {
+ const file = event.target.files?.[0];
+ event.target.value = '';
+ if (!file) return;
+ try {
+ const parsed = JSON.parse(await file.text());
+ const imported = Array.isArray(parsed)
+ ? parsed[0]
+ : (parsed.walkthroughs?.[0] || parsed.contributions?.walkthroughs?.[0] || parsed);
+ if (validateWalkthroughDefinition(imported).length > 0) {
+ throw new Error(t('walkthroughStudio.importInvalid', 'The file does not contain a valid walkthrough.'));
+ }
+ setDraft(imported);
+ setOriginalId(null);
+ setStepIndex(0);
+ toast.success(t('walkthroughStudio.imported', 'Walkthrough imported as a draft.'));
+ } catch (error) {
+ toast.error(error.message || t('walkthroughStudio.importFailed', 'Could not import this file.'));
+ }
+ };
+
+ const copyContribution = async () => {
+ await copyToClipboard(JSON.stringify({ walkthroughs: [draft] }, null, 2));
+ toast.success(t('walkthroughStudio.contributionCopied', 'Extension contribution copied.'));
+ };
+
+ const runPreview = () => {
+ if (!preview(draft)) {
+ toast.error(t('walkthroughStudio.previewFailed', 'The draft could not be previewed.'));
+ return;
+ }
+ toast.info(t('walkthroughStudio.previewOpened', 'Draft opened in the walkthrough dock.'));
+ };
+
+ const actions = (
+ <>
+ <input ref={importRef} className="wts-file-input" type="file" accept="application/json,.json" onChange={importFile} />
+ <Button type="button" variant="ghost" size="sm" onClick={() => importRef.current?.click()}>
+ <FileUp size={14} /> {t('common.actions.import', 'Import')}
+ </Button>
+ <Button type="button" variant="ghost" size="sm" onClick={() => downloadBlob(`${JSON.stringify(draft, null, 2)}\n`, `${draft.id || 'walkthrough'}.json`, { type: 'application/json' })}>
+ <Download size={14} /> {t('common.actions.export', 'Export')}
+ </Button>
+ <Button type="button" size="sm" onClick={saveGuide} disabled={saving || issues.length > 0} data-walkthrough="studio-publish">
+ <Save size={14} /> {saving ? t('common.saving', 'Saving…') : t('walkthroughStudio.publish', 'Publish')}
+ </Button>
+ </>
+ );
+
+ return (
+ <div className="page-container page-container--full-bleed wts-page">
+ <PageTopbar
+ icon={<BookOpenCheck size={18} />}
+ title={t('walkthroughStudio.title', 'Walkthrough Studio')}
+ meta={t('walkthroughStudio.meta', 'Declarative guide authoring')}
+ actions={actions}
+ />
+
+ <div className="wts-shell">
+ <aside className="wts-library">
+ <div className="wts-panel-heading">
+ <span>{t('walkthroughStudio.library', 'Shared library')}</span>
+ <Button type="button" variant="ghost" size="icon" onClick={newGuide} aria-label={t('walkthroughStudio.newGuide', 'New walkthrough')}>
+ <Plus size={15} />
+ </Button>
+ </div>
+ <p className="wts-library__intro">
+ {t('walkthroughStudio.libraryIntro', 'Published guides appear in the walkthrough dock for everyone with the required permissions.')}
+ </p>
+ <div className="wts-library__list">
+ {loading && <p className="wts-muted">{t('common.loading', 'Loading…')}</p>}
+ {!loading && library.length === 0 && (
+ <button type="button" className="wts-library__empty" onClick={newGuide}>
+ <Sparkles size={18} />
+ <strong>{t('walkthroughStudio.createFirst', 'Create the first custom guide')}</strong>
+ <span>{t('walkthroughStudio.noCodeRequired', 'No application code required')}</span>
+ </button>
+ )}
+ {library.map((guide) => (
+ <div key={guide.id} className={`wts-library__item${originalId === guide.id ? ' is-active' : ''}`}>
+ <button type="button" onClick={() => selectGuide(guide)}>
+ <strong>{guide.title}</strong>
+ <span>{guide.steps.length} {t('walkthroughStudio.steps', 'steps')}</span>
+ </button>
+ <Button type="button" variant="ghost" size="icon" onClick={() => deleteGuide(guide)} aria-label={t('common.actions.delete', 'Delete')}>
+ <Trash2 size={13} />
+ </Button>
+ </div>
+ ))}
+ </div>
+ <div className="wts-library__footer">
+ <Button type="button" variant="outline" size="sm" onClick={copyContribution}>
+ <Copy size={13} /> {t('walkthroughStudio.copyContribution', 'Copy contribution')}
+ </Button>
+ </div>
+ </aside>
+
+ <main className="wts-editor">
+ <section className="wts-section" data-walkthrough="studio-guide-meta">
+ <div className="wts-section__head">
+ <div>
+ <span className="wts-eyebrow">{t('walkthroughStudio.guideEyebrow', '01 / GUIDE')}</span>
+ <h2>{t('walkthroughStudio.outcome', 'Define the outcome')}</h2>
+ </div>
+ <label className="wts-toggle">
+ <input type="checkbox" checked={draft.secondary !== false} onChange={(event) => updateGuide({ secondary: event.target.checked })} />
+ <span>{t('walkthroughStudio.optional', 'Optional guide')}</span>
+ </label>
+ </div>
+ <div className="wts-form-grid">
+ <Field label={t('walkthroughStudio.guideTitle', 'Title')}>
+ <input value={draft.title} onChange={(event) => updateGuide({ title: event.target.value })} />
+ </Field>
+ <Field label={t('walkthroughStudio.stableId', 'Stable id')} hint={t('walkthroughStudio.stableIdHint', 'Do not rename after publishing; progress uses this id.')}>
+ <input value={draft.id} onChange={(event) => updateGuide({ id: slugify(event.target.value, '') })} />
+ </Field>
+ <Field label={t('walkthroughStudio.description', 'Outcome description')}>
+ <textarea rows="3" value={draft.description} onChange={(event) => updateGuide({ description: event.target.value })} />
+ </Field>
+ <div className="wts-form-grid__compact">
+ <Field label={t('walkthroughStudio.duration', 'Duration')}>
+ <input value={draft.duration || ''} onChange={(event) => updateGuide({ duration: event.target.value })} />
+ </Field>
+ <Field label={t('walkthroughStudio.icon', 'Icon token')}>
+ <input value={draft.icon || ''} onChange={(event) => updateGuide({ icon: slugify(event.target.value, '') })} />
+ </Field>
+ <Field label={t('walkthroughStudio.tone', 'Tone')}>
+ <select value={draft.tone || 'cyan'} onChange={(event) => updateGuide({ tone: event.target.value })}>
+ {['cyan', 'green', 'amber', 'blue', 'violet', 'neutral'].map((tone) => <option key={tone} value={tone}>{tone}</option>)}
+ </select>
+ </Field>
+ </div>
+ </div>
+ </section>
+
+ <section className="wts-section" data-walkthrough="studio-step-list">
+ <div className="wts-section__head">
+ <div>
+ <span className="wts-eyebrow">{t('walkthroughStudio.flowEyebrow', '02 / FLOW')}</span>
+ <h2>{t('walkthroughStudio.stepsAndSignals', 'Shape the steps and signals')}</h2>
+ </div>
+ <Button type="button" variant="outline" size="sm" onClick={addStep}>
+ <Plus size={13} /> {t('walkthroughStudio.addStep', 'Add step')}
+ </Button>
+ </div>
+
+ <div className="wts-step-workbench">
+ <div className="wts-step-rail">
+ {draft.steps.map((step, index) => (
+ <button
+ key={`${step.id}-${index}`}
+ type="button"
+ className={index === stepIndex ? 'is-active' : ''}
+ onClick={() => setStepIndex(index)}
+ >
+ <GripVertical size={13} />
+ <span>{String(index + 1).padStart(2, '0')}</span>
+ <strong>{step.title || t('walkthroughStudio.untitledStep', 'Untitled step')}</strong>
+ <small>{step.completion?.type || 'manual'}</small>
+ </button>
+ ))}
+ </div>
+
+ {activeStep && (
+ <div className="wts-step-editor">
+ <div className="wts-step-editor__tools">
+ <span>STEP {String(stepIndex + 1).padStart(2, '0')}</span>
+ <Button type="button" variant="ghost" size="icon" onClick={() => moveStep(-1)} disabled={stepIndex === 0} aria-label={t('walkthroughStudio.moveUp', 'Move up')}><ArrowUp size={14} /></Button>
+ <Button type="button" variant="ghost" size="icon" onClick={() => moveStep(1)} disabled={stepIndex === draft.steps.length - 1} aria-label={t('walkthroughStudio.moveDown', 'Move down')}><ArrowDown size={14} /></Button>
+ <Button type="button" variant="ghost" size="icon" onClick={deleteStep} aria-label={t('common.actions.delete', 'Delete')}><Trash2 size={14} /></Button>
+ </div>
+ <div className="wts-form-grid">
+ <Field label={t('walkthroughStudio.stepTitle', 'Step title')}>
+ <input value={activeStep.title} onChange={(event) => updateStep({ title: event.target.value })} />
+ </Field>
+ <Field label={t('walkthroughStudio.stepId', 'Step id')}>
+ <input value={activeStep.id} onChange={(event) => updateStep({ id: slugify(event.target.value, '') })} />
+ </Field>
+ <Field label={t('walkthroughStudio.instruction', 'Instruction')}>
+ <textarea rows="3" value={activeStep.description} onChange={(event) => updateStep({ description: event.target.value })} />
+ </Field>
+ <div className="wts-form-grid__compact">
+ <Field label={t('walkthroughStudio.openPath', 'Open path')}>
+ <input value={activeStep.path || ''} onChange={(event) => updateStep({ path: event.target.value })} placeholder="/services" />
+ </Field>
+ <Field label={t('walkthroughStudio.actionLabel', 'Action label')}>
+ <input value={activeStep.action || ''} onChange={(event) => updateStep({ action: event.target.value })} placeholder={t('walkthroughStudio.actionPlaceholder', 'Open services')} />
+ </Field>
+ </div>
+ <Field label={t('walkthroughStudio.targetToken', 'Target token')} hint={t('walkthroughStudio.targetHint', 'Matches data-walkthrough="token" in the page markup.')}>
+ <input value={activeStep.target || ''} onChange={(event) => updateStep({ target: slugify(event.target.value, '') })} placeholder="service-create-button" />
+ </Field>
+ <Field label={t('walkthroughStudio.completionType', 'Completion type')}>
+ <select
+ value={activeStep.completion?.type || 'manual'}
+ onChange={(event) => updateStep({ completion: { type: event.target.value } })}
+ >
+ {WALKTHROUGH_COMPLETION_TYPES.map((type) => <option key={type.value} value={type.value}>{completionTypeLabel(t, type.value)}</option>)}
+ </select>
+ </Field>
+ <CompletionFields step={activeStep} onChange={(completion) => updateStep({ completion })} t={t} />
+ </div>
+ </div>
+ )}
+ </div>
+ </section>
+ </main>
+
+ <GuidePreview guide={draft} issues={issues} onRun={runPreview} t={t} />
+ </div>
+ </div>
+ );
+}
+
+export default WalkthroughStudioPage;
diff --git a/builtin-extensions/serverkit-walkthrough-studio/frontend/styles/walkthrough-studio.scss b/builtin-extensions/serverkit-walkthrough-studio/frontend/styles/walkthrough-studio.scss
new file mode 100644
index 00000000..a013963f
--- /dev/null
+++ b/builtin-extensions/serverkit-walkthrough-studio/frontend/styles/walkthrough-studio.scss
@@ -0,0 +1,596 @@
+@import '../../../styles/variables';
+
+$wts-radius: $radius-lg;
+$wts-radius-sm: $radius-md;
+
+.wts-page {
+ // Local aliases keep the extension's stylesheet readable while resolving
+ // through ServerKit's established SCSS token layer and active theme.
+ --border-color: #{$border-color};
+ --text-muted: #{$text-muted};
+ --bg-primary: #{$bg-body};
+ --success-color: #{$success-color};
+ --warning-color: #{$warning-color};
+ --danger-color: #{$danger-color};
+
+ min-block-size: 100%;
+ background:
+ linear-gradient(rgba(255, 255, 255, 0.018) 1px, transparent 1px),
+ linear-gradient(90deg, rgba(255, 255, 255, 0.018) 1px, transparent 1px),
+ var(--bg-primary);
+ background-size: 32px 32px;
+}
+
+.wts-file-input {
+ display: none;
+}
+
+.wts-shell {
+ display: grid;
+ grid-template-columns: 230px minmax(540px, 1fr) 310px;
+ min-block-size: calc(100vh - 112px);
+ border-block-start: 1px solid var(--border-color);
+}
+
+.wts-library,
+.wts-preview {
+ background: color-mix(in srgb, var(--bg-secondary) 92%, transparent);
+}
+
+.wts-library {
+ display: flex;
+ flex-direction: column;
+ min-inline-size: 0;
+ border-inline-end: 1px solid var(--border-color);
+}
+
+.wts-panel-heading {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ min-block-size: 48px;
+ padding: 10px 14px;
+ border-block-end: 1px solid var(--border-color);
+ color: var(--text-secondary);
+ font-family: $font-mono;
+ font-size: 10px;
+ font-weight: 700;
+ letter-spacing: 0.12em;
+ text-transform: uppercase;
+}
+
+.wts-library__intro {
+ margin: 0;
+ padding: 14px;
+ border-block-end: 1px solid var(--border-color);
+ color: var(--text-muted);
+ font-size: 12px;
+ line-height: 1.55;
+}
+
+.wts-library__list {
+ flex: 1;
+ overflow: auto;
+ padding: 8px;
+}
+
+.wts-library__empty {
+ display: flex;
+ flex-direction: column;
+ align-items: flex-start;
+ inline-size: 100%;
+ gap: 7px;
+ padding: 18px;
+ border: 1px dashed var(--border-color);
+ border-radius: $wts-radius;
+ background: transparent;
+ color: var(--text-muted);
+ text-align: start;
+
+ strong {
+ color: var(--text-primary);
+ font-size: 12px;
+ }
+
+ span {
+ font-size: 11px;
+ }
+
+ &:hover {
+ border-color: var(--accent-primary);
+ color: var(--accent-primary);
+ }
+}
+
+.wts-library__item {
+ display: grid;
+ grid-template-columns: minmax(0, 1fr) auto;
+ align-items: center;
+ border-radius: $wts-radius-sm;
+
+ > button:first-child {
+ display: flex;
+ flex-direction: column;
+ align-items: flex-start;
+ min-inline-size: 0;
+ gap: 3px;
+ padding: 10px;
+ border: 0;
+ background: transparent;
+ color: var(--text-primary);
+ text-align: start;
+
+ strong {
+ overflow: hidden;
+ max-inline-size: 100%;
+ font-size: 12px;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+
+ span {
+ color: var(--text-muted);
+ font-family: $font-mono;
+ font-size: 9px;
+ text-transform: uppercase;
+ }
+ }
+
+ &:hover,
+ &.is-active {
+ background: var(--bg-hover);
+ }
+
+ &.is-active {
+ box-shadow: inset 2px 0 var(--accent-primary);
+ }
+}
+
+.wts-library__footer {
+ padding: 12px;
+ border-block-start: 1px solid var(--border-color);
+
+ .btn {
+ inline-size: 100%;
+ }
+}
+
+.wts-editor {
+ min-inline-size: 0;
+ padding: 28px clamp(20px, 3vw, 48px) 64px;
+}
+
+.wts-section {
+ max-inline-size: 860px;
+ margin-inline: auto;
+ padding-block: 4px 42px;
+
+ + .wts-section {
+ padding-block-start: 34px;
+ border-block-start: 1px solid var(--border-color);
+ }
+}
+
+.wts-section__head {
+ display: flex;
+ align-items: flex-start;
+ justify-content: space-between;
+ gap: 18px;
+ margin-block-end: 22px;
+
+ h2 {
+ margin: 5px 0 0;
+ color: var(--text-primary);
+ font-size: clamp(20px, 2vw, 28px);
+ font-weight: 500;
+ letter-spacing: -0.035em;
+ }
+}
+
+.wts-eyebrow {
+ color: var(--accent-primary);
+ font-family: $font-mono;
+ font-size: 9px;
+ font-weight: 700;
+ letter-spacing: 0.14em;
+}
+
+.wts-toggle {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ color: var(--text-muted);
+ font-size: 11px;
+}
+
+.wts-form-grid {
+ display: grid;
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ gap: 16px;
+
+ > .wts-field:nth-child(3),
+ > .wts-callout,
+ > .wts-form-grid__compact {
+ grid-column: 1 / -1;
+ }
+}
+
+.wts-form-grid__compact {
+ display: grid;
+ grid-template-columns: repeat(3, minmax(0, 1fr));
+ gap: 12px;
+}
+
+.wts-field {
+ display: flex;
+ flex-direction: column;
+ min-inline-size: 0;
+ gap: 7px;
+
+ input,
+ textarea,
+ select {
+ inline-size: 100%;
+ min-block-size: 38px;
+ padding: 9px 11px;
+ border: 1px solid var(--border-color);
+ border-radius: $wts-radius-sm;
+ outline: none;
+ background: var(--bg-secondary);
+ color: var(--text-primary);
+ font: inherit;
+ font-size: 12px;
+
+ &:focus {
+ border-color: var(--accent-primary);
+ box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent-primary) 14%, transparent);
+ }
+ }
+
+ textarea {
+ resize: vertical;
+ line-height: 1.55;
+ }
+
+ small {
+ color: var(--text-muted);
+ font-size: 10px;
+ line-height: 1.45;
+ }
+}
+
+.wts-field__label {
+ color: var(--text-secondary);
+ font-family: $font-mono;
+ font-size: 9px;
+ font-weight: 700;
+ letter-spacing: 0.08em;
+ text-transform: uppercase;
+}
+
+.wts-step-workbench {
+ display: grid;
+ grid-template-columns: 210px minmax(0, 1fr);
+ overflow: hidden;
+ border: 1px solid var(--border-color);
+ border-radius: $wts-radius;
+ background: var(--bg-card);
+}
+
+.wts-step-rail {
+ padding: 8px;
+ border-inline-end: 1px solid var(--border-color);
+ background: var(--bg-secondary);
+
+ button {
+ display: grid;
+ grid-template-columns: auto auto minmax(0, 1fr);
+ align-items: center;
+ inline-size: 100%;
+ gap: 7px;
+ padding: 10px 8px;
+ border: 0;
+ border-radius: $wts-radius-sm;
+ background: transparent;
+ color: var(--text-muted);
+ text-align: start;
+
+ strong {
+ overflow: hidden;
+ color: var(--text-secondary);
+ font-size: 11px;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+
+ small {
+ grid-column: 3;
+ color: var(--text-muted);
+ font-family: $font-mono;
+ font-size: 8px;
+ text-transform: uppercase;
+ }
+
+ &:hover,
+ &.is-active {
+ background: var(--bg-hover);
+ }
+
+ &.is-active strong {
+ color: var(--text-primary);
+ }
+ }
+}
+
+.wts-step-editor {
+ min-inline-size: 0;
+ padding: 18px;
+}
+
+.wts-step-editor__tools {
+ display: flex;
+ align-items: center;
+ justify-content: flex-end;
+ gap: 2px;
+ margin-block-end: 16px;
+
+ > span {
+ margin-inline-end: auto;
+ color: var(--text-muted);
+ font-family: $font-mono;
+ font-size: 9px;
+ letter-spacing: 0.12em;
+ }
+}
+
+.wts-callout {
+ margin: 0;
+ padding: 10px 12px;
+ border-inline-start: 2px solid var(--accent-primary);
+ background: color-mix(in srgb, var(--accent-primary) 6%, transparent);
+ color: var(--text-muted);
+ font-size: 11px;
+ line-height: 1.5;
+}
+
+.wts-preview {
+ position: sticky;
+ inset-block-start: 0;
+ align-self: start;
+ overflow: auto;
+ max-block-size: calc(100vh - 64px);
+ border-inline-start: 1px solid var(--border-color);
+ padding-block-end: 24px;
+
+ > .btn,
+ > details,
+ > .wts-issues {
+ margin-inline: 14px;
+ }
+
+ > .btn {
+ inline-size: calc(100% - 28px);
+ }
+}
+
+.wts-validity {
+ padding: 3px 7px;
+ border-radius: 999px;
+ background: color-mix(in srgb, var(--success-color) 12%, transparent);
+ color: var(--success-color);
+ font-size: 8px;
+
+ &.is-invalid {
+ background: color-mix(in srgb, var(--danger-color) 12%, transparent);
+ color: var(--danger-color);
+ }
+}
+
+.wts-guide-card {
+ position: relative;
+ overflow: hidden;
+ margin: 14px;
+ padding: 18px;
+ border: 1px solid var(--border-color);
+ border-radius: $wts-radius;
+ background: var(--bg-card);
+
+ &::before {
+ position: absolute;
+ inset: 0 auto 0 0;
+ inline-size: 3px;
+ background: var(--accent-primary);
+ content: '';
+ }
+
+ &.is-green::before { background: var(--success-color); }
+ &.is-amber::before { background: var(--warning-color); }
+ &.is-violet::before { background: #a78bfa; }
+
+ h2 {
+ margin: 9px 0 7px;
+ color: var(--text-primary);
+ font-size: 18px;
+ font-weight: 550;
+ letter-spacing: -0.025em;
+ }
+
+ p {
+ margin: 0;
+ color: var(--text-muted);
+ font-size: 11px;
+ line-height: 1.55;
+ }
+}
+
+.wts-guide-card__kicker {
+ color: var(--accent-primary);
+ font-family: $font-mono;
+ font-size: 8px;
+ font-weight: 700;
+ letter-spacing: 0.13em;
+}
+
+.wts-guide-card__meta {
+ display: flex;
+ gap: 12px;
+ margin-block-start: 16px;
+ color: var(--text-muted);
+ font-family: $font-mono;
+ font-size: 9px;
+}
+
+.wts-preview-steps {
+ display: flex;
+ flex-direction: column;
+ gap: 0;
+ margin: 4px 14px 16px;
+ padding: 0;
+ list-style: none;
+
+ li {
+ display: grid;
+ grid-template-columns: 24px minmax(0, 1fr);
+ gap: 9px;
+ padding: 10px 4px;
+ border-block-end: 1px solid var(--border-color);
+
+ > span {
+ color: var(--text-muted);
+ font-family: $font-mono;
+ font-size: 9px;
+ }
+
+ div {
+ display: flex;
+ min-inline-size: 0;
+ flex-direction: column;
+ gap: 3px;
+ }
+
+ strong {
+ overflow: hidden;
+ color: var(--text-secondary);
+ font-size: 11px;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+
+ small {
+ color: var(--text-muted);
+ font-family: $font-mono;
+ font-size: 8px;
+ }
+ }
+}
+
+.wts-issues {
+ margin-block-end: 12px;
+ padding: 10px;
+ border: 1px solid color-mix(in srgb, var(--danger-color) 30%, var(--border-color));
+ border-radius: $wts-radius-sm;
+ background: color-mix(in srgb, var(--danger-color) 5%, transparent);
+
+ p {
+ margin: 0;
+ color: var(--text-muted);
+ font-size: 10px;
+ line-height: 1.5;
+
+ + p { margin-block-start: 4px; }
+ strong { color: var(--danger-color); }
+ }
+}
+
+.wts-json {
+ margin-block-start: 12px;
+ border: 1px solid var(--border-color);
+ border-radius: $wts-radius-sm;
+
+ summary {
+ display: flex;
+ align-items: center;
+ gap: 7px;
+ padding: 10px;
+ color: var(--text-muted);
+ cursor: pointer;
+ font-family: $font-mono;
+ font-size: 9px;
+ text-transform: uppercase;
+ }
+
+ pre {
+ overflow: auto;
+ max-block-size: 320px;
+ margin: 0;
+ padding: 10px;
+ border-block-start: 1px solid var(--border-color);
+ color: var(--text-secondary);
+ font-family: $font-mono;
+ font-size: 9px;
+ line-height: 1.55;
+ white-space: pre-wrap;
+ }
+}
+
+.wts-muted {
+ color: var(--text-muted);
+ font-size: 11px;
+}
+
+@media (max-width: 1280px) {
+ .wts-shell {
+ grid-template-columns: 210px minmax(520px, 1fr);
+ }
+
+ .wts-preview {
+ position: static;
+ grid-column: 2;
+ max-block-size: none;
+ border-block-start: 1px solid var(--border-color);
+ border-inline-start: 0;
+ }
+}
+
+@media (max-width: 900px) {
+ .wts-shell {
+ display: block;
+ }
+
+ .wts-library {
+ border-block-end: 1px solid var(--border-color);
+ border-inline-end: 0;
+ }
+
+ .wts-library__list {
+ max-block-size: 220px;
+ }
+
+ .wts-step-workbench {
+ grid-template-columns: 1fr;
+ }
+
+ .wts-step-rail {
+ border-block-end: 1px solid var(--border-color);
+ border-inline-end: 0;
+ }
+
+ .wts-preview {
+ border-inline-start: 0;
+ }
+}
+
+@media (max-width: 640px) {
+ .wts-editor {
+ padding-inline: 14px;
+ }
+
+ .wts-form-grid,
+ .wts-form-grid__compact {
+ grid-template-columns: 1fr;
+ }
+
+ .wts-form-grid > * {
+ grid-column: 1;
+ }
+}
diff --git a/builtin-extensions/serverkit-walkthrough-studio/plugin.json b/builtin-extensions/serverkit-walkthrough-studio/plugin.json
new file mode 100644
index 00000000..fbf1b27c
--- /dev/null
+++ b/builtin-extensions/serverkit-walkthrough-studio/plugin.json
@@ -0,0 +1,93 @@
+{
+ "name": "serverkit-walkthrough-studio",
+ "display_name": "Walkthrough Studio",
+ "version": "1.0.0",
+ "description": "Create, validate, preview, import, and export guided ServerKit walkthroughs without writing application code.",
+ "author": "ServerKit",
+ "license": "MIT",
+ "category": "utility",
+ "homepage": "https://github.com/jhd3197/ServerKit",
+ "permissions": [],
+ "min_panel_version": "1.7.81",
+ "sdk_version": "^1.5.0",
+ "icon": "<path d=\"M4 19.5V4.5A2.5 2.5 0 0 1 6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5Z\"/><path d=\"M8 7h8M8 11h6M8 15h4\"/>",
+ "contributions": {
+ "nav": [
+ {
+ "id": "walkthrough-studio",
+ "label": "Walkthrough Studio",
+ "route": "/walkthrough-studio",
+ "category": "system",
+ "icon": "<path d=\"M4 19.5V4.5A2.5 2.5 0 0 1 6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5Z\"/><path d=\"M8 7h8M8 11h6M8 15h4\"/>"
+ }
+ ],
+ "routes": [
+ { "path": "walkthrough-studio", "component": "WalkthroughStudioPage", "layout": "full" }
+ ],
+ "page_titles": {
+ "/walkthrough-studio": "Walkthrough Studio"
+ },
+ "command_palette": [
+ {
+ "label": "Walkthrough Studio",
+ "path": "/walkthrough-studio",
+ "category": "Tools",
+ "keywords": "guide tutorial onboarding author builder"
+ }
+ ],
+ "walkthroughs": [
+ {
+ "id": "build-first-walkthrough",
+ "title": "Build your first walkthrough",
+ "description": "Design a guided flow, test it in the live dock, and publish it to your team.",
+ "duration": "About 6 minutes",
+ "icon": "guide",
+ "tone": "violet",
+ "secondary": true,
+ "permissions": [
+ { "feature": "settings", "level": "admin" }
+ ],
+ "steps": [
+ {
+ "id": "open-studio",
+ "title": "Open Walkthrough Studio",
+ "description": "The Studio keeps guide metadata, steps, and the live preview visible in one authoring surface.",
+ "action": "Open Studio",
+ "path": "/walkthrough-studio",
+ "target": "studio-guide-meta",
+ "completion": { "type": "route", "path": "/walkthrough-studio" }
+ },
+ {
+ "id": "shape-guide",
+ "title": "Describe the outcome",
+ "description": "Give the guide a stable id, a concrete outcome, and an honest duration.",
+ "target": "studio-guide-meta",
+ "completion": { "type": "manual" }
+ },
+ {
+ "id": "author-steps",
+ "title": "Author and order the steps",
+ "description": "Choose how each step completes and point it at a stable data-walkthrough token.",
+ "target": "studio-step-list",
+ "completion": { "type": "manual" }
+ },
+ {
+ "id": "preview-guide",
+ "title": "Preview the guide",
+ "description": "Run the draft in the real walkthrough dock before publishing it.",
+ "target": "studio-preview",
+ "completion": { "type": "manual" }
+ },
+ {
+ "id": "publish-guide",
+ "title": "Publish the walkthrough",
+ "description": "Save the validated definition so every permitted user sees it immediately.",
+ "action": "Publish walkthrough",
+ "target": "studio-publish",
+ "completion": { "type": "signal", "signal": "walkthrough-studio-guide-saved" }
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/frontend/src/plugins/serverkit-walkthrough-studio/index.jsx b/frontend/src/plugins/serverkit-walkthrough-studio/index.jsx
new file mode 100644
index 00000000..97ddd853
--- /dev/null
+++ b/frontend/src/plugins/serverkit-walkthrough-studio/index.jsx
@@ -0,0 +1,554 @@
+import {
+ ArrowDown,
+ ArrowUp,
+ BookOpenCheck,
+ Braces,
+ Copy,
+ Download,
+ Eye,
+ FileUp,
+ GripVertical,
+ Plus,
+ Save,
+ Sparkles,
+ Trash2,
+} from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import {
+ api,
+ Button,
+ copyToClipboard,
+ downloadBlob,
+ emitWalkthroughSignal,
+ PageTopbar,
+ useAuth,
+ useConfirm,
+ useToast,
+ useWalkthroughs,
+ validateWalkthroughDefinition,
+ WALKTHROUGH_COMPLETION_TYPES,
+} from '../sdk';
+
+import './styles/walkthrough-studio.scss';
+
+
+function createInitialStep(t) {
+ return {
+ id: 'open-page',
+ title: t('walkthroughStudio.initialStepTitle', 'Open the page'),
+ description: t('walkthroughStudio.initialStepDescription', 'Navigate to the place where this task begins.'),
+ action: t('walkthroughStudio.initialStepAction', 'Open page'),
+ path: '/',
+ target: '',
+ completion: { type: 'route', path: '/' },
+ };
+}
+
+function createGuide(t) {
+ return {
+ id: 'my-walkthrough',
+ title: t('walkthroughStudio.initialTitle', 'My walkthrough'),
+ description: t('walkthroughStudio.initialDescription', 'Help an operator complete one clear outcome.'),
+ duration: 'About 5 minutes',
+ icon: 'guide',
+ tone: 'cyan',
+ secondary: true,
+ permissions: [],
+ steps: [createInitialStep(t)],
+ };
+}
+
+function slugify(value, fallback) {
+ const slug = String(value || '')
+ .toLowerCase()
+ .trim()
+ .replace(/[^a-z0-9._-]+/g, '-')
+ .replace(/^-+|-+$/g, '')
+ .slice(0, 80);
+ return slug || fallback;
+}
+
+function completionTypeLabel(t, value) {
+ const labels = {
+ manual: t('walkthroughStudio.completionManual', 'Manual confirmation'),
+ route: t('walkthroughStudio.completionRouteReached', 'Route reached'),
+ signal: t('walkthroughStudio.completionSignal', 'Success signal received'),
+ check: t('walkthroughStudio.completionCheck', 'Named status check'),
+ target: t('walkthroughStudio.completionTarget', 'Target becomes visible'),
+ };
+ return labels[value] || value;
+}
+
+function Field({ label, hint, children }) {
+ return (
+ <label className="wts-field">
+ <span className="wts-field__label">{label}</span>
+ {children}
+ {hint && <small>{hint}</small>}
+ </label>
+ );
+}
+
+function CompletionFields({ step, onChange, t }) {
+ const type = step.completion?.type || 'manual';
+ if (type === 'signal') {
+ return (
+ <Field
+ label={t('walkthroughStudio.signalName', 'Success signal')}
+ hint={t('walkthroughStudio.signalHint', 'Emit this token only after the operation succeeds.')}
+ >
+ <input
+ value={step.completion.signal || ''}
+ onChange={(event) => onChange({ ...step.completion, signal: slugify(event.target.value, '') })}
+ placeholder="extension.resource-created"
+ />
+ </Field>
+ );
+ }
+ if (type === 'check') {
+ return (
+ <Field
+ label={t('walkthroughStudio.checkName', 'Named host check')}
+ hint={t('walkthroughStudio.checkHint', 'Checks must be implemented and allowlisted by the host.')}
+ >
+ <input
+ value={step.completion.check || ''}
+ onChange={(event) => onChange({ ...step.completion, check: slugify(event.target.value, '') })}
+ placeholder="extension.resource-ready"
+ />
+ </Field>
+ );
+ }
+ if (type === 'route') {
+ return (
+ <Field label={t('walkthroughStudio.completionRoute', 'Completion route')}>
+ <input
+ value={step.completion.path || ''}
+ onChange={(event) => onChange({ ...step.completion, path: event.target.value })}
+ placeholder="/services"
+ />
+ </Field>
+ );
+ }
+ if (type === 'target') {
+ return (
+ <p className="wts-callout">
+ {t('walkthroughStudio.targetCompletionHint', 'This step completes when its data-walkthrough target becomes visible.')}
+ </p>
+ );
+ }
+ return (
+ <p className="wts-callout">
+ {t('walkthroughStudio.manualCompletionHint', 'The operator uses Done · next step after completing the instruction.')}
+ </p>
+ );
+}
+
+function GuidePreview({ guide, issues, onRun, t }) {
+ return (
+ <aside className="wts-preview" data-walkthrough="studio-preview">
+ <div className="wts-panel-heading">
+ <span>{t('walkthroughStudio.livePreview', 'Live preview')}</span>
+ <span className={`wts-validity${issues.length ? ' is-invalid' : ''}`}>
+ {issues.length
+ ? t('walkthroughStudio.issueCount', '{{count}} issues', { count: issues.length })
+ : t('walkthroughStudio.valid', 'Valid')}
+ </span>
+ </div>
+
+ <div className={`wts-guide-card is-${guide.tone || 'cyan'}`}>
+ <span className="wts-guide-card__kicker">{guide.secondary ? 'OPTIONAL GUIDE' : 'ESSENTIAL GUIDE'}</span>
+ <h2>{guide.title || t('walkthroughStudio.untitled', 'Untitled walkthrough')}</h2>
+ <p>{guide.description || t('walkthroughStudio.addDescription', 'Add a description to explain the outcome.')}</p>
+ <div className="wts-guide-card__meta">
+ <span>{guide.steps?.length || 0} {t('walkthroughStudio.steps', 'steps')}</span>
+ <span>{guide.duration || t('walkthroughStudio.noDuration', 'No duration')}</span>
+ </div>
+ </div>
+
+ <ol className="wts-preview-steps">
+ {(guide.steps || []).map((step, index) => (
+ <li key={`${step.id}-${index}`}>
+ <span>{String(index + 1).padStart(2, '0')}</span>
+ <div>
+ <strong>{step.title || t('walkthroughStudio.untitledStep', 'Untitled step')}</strong>
+ <small>{step.completion?.type || 'manual'} · {step.target || t('walkthroughStudio.noTarget', 'no target')}</small>
+ </div>
+ </li>
+ ))}
+ </ol>
+
+ {issues.length > 0 && (
+ <div className="wts-issues" role="alert">
+ {issues.slice(0, 6).map((item) => (
+ <p key={`${item.path}:${item.message}`}><strong>{item.path || 'guide'}</strong> {item.message}</p>
+ ))}
+ </div>
+ )}
+
+ <Button type="button" variant="outline" onClick={onRun} disabled={issues.length > 0}>
+ <Eye size={14} /> {t('walkthroughStudio.runInDock', 'Run in walkthrough dock')}
+ </Button>
+
+ <details className="wts-json">
+ <summary><Braces size={14} /> {t('walkthroughStudio.definitionJson', 'Definition JSON')}</summary>
+ <pre>{JSON.stringify(guide, null, 2)}</pre>
+ </details>
+ </aside>
+ );
+}
+
+export function WalkthroughStudioPage() {
+ const { t } = useTranslation();
+ const toast = useToast();
+ const { confirm } = useConfirm();
+ const { isAdmin } = useAuth();
+ const { preview, refreshDefinitions } = useWalkthroughs();
+ const importRef = useRef(null);
+ const [library, setLibrary] = useState([]);
+ const [draft, setDraft] = useState(() => createGuide(t));
+ const [originalId, setOriginalId] = useState(null);
+ const [stepIndex, setStepIndex] = useState(0);
+ const [loading, setLoading] = useState(true);
+ const [saving, setSaving] = useState(false);
+
+ const issues = useMemo(() => validateWalkthroughDefinition(draft), [draft]);
+ const activeStep = draft.steps?.[stepIndex] || null;
+
+ const loadLibrary = useCallback(async () => {
+ setLoading(true);
+ try {
+ const response = await api.getWalkthroughDefinitions();
+ setLibrary(Array.isArray(response?.definitions) ? response.definitions : []);
+ } catch (error) {
+ toast.error(error.message || t('walkthroughStudio.loadFailed', 'Could not load the walkthrough library.'));
+ } finally {
+ setLoading(false);
+ }
+ }, [t, toast]);
+
+ useEffect(() => { loadLibrary(); }, [loadLibrary]);
+
+ const updateGuide = (patch) => setDraft((current) => ({ ...current, ...patch }));
+ const updateStep = (patch) => setDraft((current) => ({
+ ...current,
+ steps: current.steps.map((step, index) => (
+ index === stepIndex ? { ...step, ...patch } : step
+ )),
+ }));
+
+ const selectGuide = (guide) => {
+ setDraft(JSON.parse(JSON.stringify(guide)));
+ setOriginalId(guide.id);
+ setStepIndex(0);
+ };
+
+ const newGuide = () => {
+ setDraft(createGuide(t));
+ setOriginalId(null);
+ setStepIndex(0);
+ };
+
+ const addStep = () => {
+ setDraft((current) => {
+ const nextNumber = current.steps.length + 1;
+ return {
+ ...current,
+ steps: [...current.steps, {
+ id: `step-${nextNumber}`,
+ title: t('walkthroughStudio.numberedStep', 'Step {{number}}', { number: nextNumber }),
+ description: t('walkthroughStudio.newStepDescription', 'Describe the operator action and the expected outcome.'),
+ action: 'Open page',
+ path: '/',
+ target: '',
+ completion: { type: 'manual' },
+ }],
+ };
+ });
+ setStepIndex(draft.steps.length);
+ };
+
+ const moveStep = (direction) => {
+ const nextIndex = stepIndex + direction;
+ if (nextIndex < 0 || nextIndex >= draft.steps.length) return;
+ setDraft((current) => {
+ const steps = [...current.steps];
+ [steps[stepIndex], steps[nextIndex]] = [steps[nextIndex], steps[stepIndex]];
+ return { ...current, steps };
+ });
+ setStepIndex(nextIndex);
+ };
+
+ const deleteStep = () => {
+ if (draft.steps.length <= 1) {
+ toast.warning(t('walkthroughStudio.keepOneStep', 'A walkthrough needs at least one step.'));
+ return;
+ }
+ setDraft((current) => ({
+ ...current,
+ steps: current.steps.filter((_, index) => index !== stepIndex),
+ }));
+ setStepIndex((current) => Math.max(0, current - 1));
+ };
+
+ const saveGuide = async () => {
+ if (!isAdmin) {
+ toast.error(t('walkthroughStudio.adminRequired', 'Administrator access is required to publish walkthroughs.'));
+ return;
+ }
+ if (issues.length > 0) {
+ toast.warning(t('walkthroughStudio.fixIssues', 'Fix the validation issues before publishing.'));
+ return;
+ }
+ setSaving(true);
+ try {
+ const withoutOriginal = library.filter((guide) => guide.id !== originalId && guide.id !== draft.id);
+ const nextLibrary = [...withoutOriginal, draft];
+ const response = await api.updateWalkthroughDefinitions(nextLibrary);
+ setLibrary(response.definitions || nextLibrary);
+ setOriginalId(draft.id);
+ await refreshDefinitions();
+ emitWalkthroughSignal('walkthrough-studio-guide-saved', { guideId: draft.id });
+ toast.success(t('walkthroughStudio.published', 'Walkthrough published.'));
+ } catch (error) {
+ toast.error(error.message || t('walkthroughStudio.publishFailed', 'Could not publish the walkthrough.'));
+ } finally {
+ setSaving(false);
+ }
+ };
+
+ const deleteGuide = async (guide) => {
+ if (!await confirm({
+ title: t('walkthroughStudio.deleteTitle', 'Delete walkthrough'),
+ message: t('walkthroughStudio.deleteMessage', 'Delete “{{title}}” from the shared walkthrough library?', { title: guide.title }),
+ confirmText: t('common.actions.delete', 'Delete'),
+ })) return;
+ try {
+ const nextLibrary = library.filter((item) => item.id !== guide.id);
+ await api.updateWalkthroughDefinitions(nextLibrary);
+ setLibrary(nextLibrary);
+ if (originalId === guide.id) newGuide();
+ await refreshDefinitions();
+ toast.success(t('walkthroughStudio.deleted', 'Walkthrough deleted.'));
+ } catch (error) {
+ toast.error(error.message || t('walkthroughStudio.deleteFailed', 'Could not delete the walkthrough.'));
+ }
+ };
+
+ const importFile = async (event) => {
+ const file = event.target.files?.[0];
+ event.target.value = '';
+ if (!file) return;
+ try {
+ const parsed = JSON.parse(await file.text());
+ const imported = Array.isArray(parsed)
+ ? parsed[0]
+ : (parsed.walkthroughs?.[0] || parsed.contributions?.walkthroughs?.[0] || parsed);
+ if (validateWalkthroughDefinition(imported).length > 0) {
+ throw new Error(t('walkthroughStudio.importInvalid', 'The file does not contain a valid walkthrough.'));
+ }
+ setDraft(imported);
+ setOriginalId(null);
+ setStepIndex(0);
+ toast.success(t('walkthroughStudio.imported', 'Walkthrough imported as a draft.'));
+ } catch (error) {
+ toast.error(error.message || t('walkthroughStudio.importFailed', 'Could not import this file.'));
+ }
+ };
+
+ const copyContribution = async () => {
+ await copyToClipboard(JSON.stringify({ walkthroughs: [draft] }, null, 2));
+ toast.success(t('walkthroughStudio.contributionCopied', 'Extension contribution copied.'));
+ };
+
+ const runPreview = () => {
+ if (!preview(draft)) {
+ toast.error(t('walkthroughStudio.previewFailed', 'The draft could not be previewed.'));
+ return;
+ }
+ toast.info(t('walkthroughStudio.previewOpened', 'Draft opened in the walkthrough dock.'));
+ };
+
+ const actions = (
+ <>
+ <input ref={importRef} className="wts-file-input" type="file" accept="application/json,.json" onChange={importFile} />
+ <Button type="button" variant="ghost" size="sm" onClick={() => importRef.current?.click()}>
+ <FileUp size={14} /> {t('common.actions.import', 'Import')}
+ </Button>
+ <Button type="button" variant="ghost" size="sm" onClick={() => downloadBlob(`${JSON.stringify(draft, null, 2)}\n`, `${draft.id || 'walkthrough'}.json`, { type: 'application/json' })}>
+ <Download size={14} /> {t('common.actions.export', 'Export')}
+ </Button>
+ <Button type="button" size="sm" onClick={saveGuide} disabled={saving || issues.length > 0} data-walkthrough="studio-publish">
+ <Save size={14} /> {saving ? t('common.saving', 'Saving…') : t('walkthroughStudio.publish', 'Publish')}
+ </Button>
+ </>
+ );
+
+ return (
+ <div className="page-container page-container--full-bleed wts-page">
+ <PageTopbar
+ icon={<BookOpenCheck size={18} />}
+ title={t('walkthroughStudio.title', 'Walkthrough Studio')}
+ meta={t('walkthroughStudio.meta', 'Declarative guide authoring')}
+ actions={actions}
+ />
+
+ <div className="wts-shell">
+ <aside className="wts-library">
+ <div className="wts-panel-heading">
+ <span>{t('walkthroughStudio.library', 'Shared library')}</span>
+ <Button type="button" variant="ghost" size="icon" onClick={newGuide} aria-label={t('walkthroughStudio.newGuide', 'New walkthrough')}>
+ <Plus size={15} />
+ </Button>
+ </div>
+ <p className="wts-library__intro">
+ {t('walkthroughStudio.libraryIntro', 'Published guides appear in the walkthrough dock for everyone with the required permissions.')}
+ </p>
+ <div className="wts-library__list">
+ {loading && <p className="wts-muted">{t('common.loading', 'Loading…')}</p>}
+ {!loading && library.length === 0 && (
+ <button type="button" className="wts-library__empty" onClick={newGuide}>
+ <Sparkles size={18} />
+ <strong>{t('walkthroughStudio.createFirst', 'Create the first custom guide')}</strong>
+ <span>{t('walkthroughStudio.noCodeRequired', 'No application code required')}</span>
+ </button>
+ )}
+ {library.map((guide) => (
+ <div key={guide.id} className={`wts-library__item${originalId === guide.id ? ' is-active' : ''}`}>
+ <button type="button" onClick={() => selectGuide(guide)}>
+ <strong>{guide.title}</strong>
+ <span>{guide.steps.length} {t('walkthroughStudio.steps', 'steps')}</span>
+ </button>
+ <Button type="button" variant="ghost" size="icon" onClick={() => deleteGuide(guide)} aria-label={t('common.actions.delete', 'Delete')}>
+ <Trash2 size={13} />
+ </Button>
+ </div>
+ ))}
+ </div>
+ <div className="wts-library__footer">
+ <Button type="button" variant="outline" size="sm" onClick={copyContribution}>
+ <Copy size={13} /> {t('walkthroughStudio.copyContribution', 'Copy contribution')}
+ </Button>
+ </div>
+ </aside>
+
+ <main className="wts-editor">
+ <section className="wts-section" data-walkthrough="studio-guide-meta">
+ <div className="wts-section__head">
+ <div>
+ <span className="wts-eyebrow">{t('walkthroughStudio.guideEyebrow', '01 / GUIDE')}</span>
+ <h2>{t('walkthroughStudio.outcome', 'Define the outcome')}</h2>
+ </div>
+ <label className="wts-toggle">
+ <input type="checkbox" checked={draft.secondary !== false} onChange={(event) => updateGuide({ secondary: event.target.checked })} />
+ <span>{t('walkthroughStudio.optional', 'Optional guide')}</span>
+ </label>
+ </div>
+ <div className="wts-form-grid">
+ <Field label={t('walkthroughStudio.guideTitle', 'Title')}>
+ <input value={draft.title} onChange={(event) => updateGuide({ title: event.target.value })} />
+ </Field>
+ <Field label={t('walkthroughStudio.stableId', 'Stable id')} hint={t('walkthroughStudio.stableIdHint', 'Do not rename after publishing; progress uses this id.')}>
+ <input value={draft.id} onChange={(event) => updateGuide({ id: slugify(event.target.value, '') })} />
+ </Field>
+ <Field label={t('walkthroughStudio.description', 'Outcome description')}>
+ <textarea rows="3" value={draft.description} onChange={(event) => updateGuide({ description: event.target.value })} />
+ </Field>
+ <div className="wts-form-grid__compact">
+ <Field label={t('walkthroughStudio.duration', 'Duration')}>
+ <input value={draft.duration || ''} onChange={(event) => updateGuide({ duration: event.target.value })} />
+ </Field>
+ <Field label={t('walkthroughStudio.icon', 'Icon token')}>
+ <input value={draft.icon || ''} onChange={(event) => updateGuide({ icon: slugify(event.target.value, '') })} />
+ </Field>
+ <Field label={t('walkthroughStudio.tone', 'Tone')}>
+ <select value={draft.tone || 'cyan'} onChange={(event) => updateGuide({ tone: event.target.value })}>
+ {['cyan', 'green', 'amber', 'blue', 'violet', 'neutral'].map((tone) => <option key={tone} value={tone}>{tone}</option>)}
+ </select>
+ </Field>
+ </div>
+ </div>
+ </section>
+
+ <section className="wts-section" data-walkthrough="studio-step-list">
+ <div className="wts-section__head">
+ <div>
+ <span className="wts-eyebrow">{t('walkthroughStudio.flowEyebrow', '02 / FLOW')}</span>
+ <h2>{t('walkthroughStudio.stepsAndSignals', 'Shape the steps and signals')}</h2>
+ </div>
+ <Button type="button" variant="outline" size="sm" onClick={addStep}>
+ <Plus size={13} /> {t('walkthroughStudio.addStep', 'Add step')}
+ </Button>
+ </div>
+
+ <div className="wts-step-workbench">
+ <div className="wts-step-rail">
+ {draft.steps.map((step, index) => (
+ <button
+ key={`${step.id}-${index}`}
+ type="button"
+ className={index === stepIndex ? 'is-active' : ''}
+ onClick={() => setStepIndex(index)}
+ >
+ <GripVertical size={13} />
+ <span>{String(index + 1).padStart(2, '0')}</span>
+ <strong>{step.title || t('walkthroughStudio.untitledStep', 'Untitled step')}</strong>
+ <small>{step.completion?.type || 'manual'}</small>
+ </button>
+ ))}
+ </div>
+
+ {activeStep && (
+ <div className="wts-step-editor">
+ <div className="wts-step-editor__tools">
+ <span>STEP {String(stepIndex + 1).padStart(2, '0')}</span>
+ <Button type="button" variant="ghost" size="icon" onClick={() => moveStep(-1)} disabled={stepIndex === 0} aria-label={t('walkthroughStudio.moveUp', 'Move up')}><ArrowUp size={14} /></Button>
+ <Button type="button" variant="ghost" size="icon" onClick={() => moveStep(1)} disabled={stepIndex === draft.steps.length - 1} aria-label={t('walkthroughStudio.moveDown', 'Move down')}><ArrowDown size={14} /></Button>
+ <Button type="button" variant="ghost" size="icon" onClick={deleteStep} aria-label={t('common.actions.delete', 'Delete')}><Trash2 size={14} /></Button>
+ </div>
+ <div className="wts-form-grid">
+ <Field label={t('walkthroughStudio.stepTitle', 'Step title')}>
+ <input value={activeStep.title} onChange={(event) => updateStep({ title: event.target.value })} />
+ </Field>
+ <Field label={t('walkthroughStudio.stepId', 'Step id')}>
+ <input value={activeStep.id} onChange={(event) => updateStep({ id: slugify(event.target.value, '') })} />
+ </Field>
+ <Field label={t('walkthroughStudio.instruction', 'Instruction')}>
+ <textarea rows="3" value={activeStep.description} onChange={(event) => updateStep({ description: event.target.value })} />
+ </Field>
+ <div className="wts-form-grid__compact">
+ <Field label={t('walkthroughStudio.openPath', 'Open path')}>
+ <input value={activeStep.path || ''} onChange={(event) => updateStep({ path: event.target.value })} placeholder="/services" />
+ </Field>
+ <Field label={t('walkthroughStudio.actionLabel', 'Action label')}>
+ <input value={activeStep.action || ''} onChange={(event) => updateStep({ action: event.target.value })} placeholder={t('walkthroughStudio.actionPlaceholder', 'Open services')} />
+ </Field>
+ </div>
+ <Field label={t('walkthroughStudio.targetToken', 'Target token')} hint={t('walkthroughStudio.targetHint', 'Matches data-walkthrough="token" in the page markup.')}>
+ <input value={activeStep.target || ''} onChange={(event) => updateStep({ target: slugify(event.target.value, '') })} placeholder="service-create-button" />
+ </Field>
+ <Field label={t('walkthroughStudio.completionType', 'Completion type')}>
+ <select
+ value={activeStep.completion?.type || 'manual'}
+ onChange={(event) => updateStep({ completion: { type: event.target.value } })}
+ >
+ {WALKTHROUGH_COMPLETION_TYPES.map((type) => <option key={type.value} value={type.value}>{completionTypeLabel(t, type.value)}</option>)}
+ </select>
+ </Field>
+ <CompletionFields step={activeStep} onChange={(completion) => updateStep({ completion })} t={t} />
+ </div>
+ </div>
+ )}
+ </div>
+ </section>
+ </main>
+
+ <GuidePreview guide={draft} issues={issues} onRun={runPreview} t={t} />
+ </div>
+ </div>
+ );
+}
+
+export default WalkthroughStudioPage;
diff --git a/frontend/src/plugins/serverkit-walkthrough-studio/plugin.json b/frontend/src/plugins/serverkit-walkthrough-studio/plugin.json
new file mode 100644
index 00000000..0b733775
--- /dev/null
+++ b/frontend/src/plugins/serverkit-walkthrough-studio/plugin.json
@@ -0,0 +1,112 @@
+{
+ "name": "serverkit-walkthrough-studio",
+ "display_name": "Walkthrough Studio",
+ "version": "1.0.0",
+ "description": "Create, validate, preview, import, and export guided ServerKit walkthroughs without writing application code.",
+ "author": "ServerKit",
+ "license": "MIT",
+ "category": "utility",
+ "homepage": "https://github.com/jhd3197/ServerKit",
+ "permissions": [],
+ "min_panel_version": "1.7.81",
+ "sdk_version": "^1.5.0",
+ "icon": "<path d=\"M4 19.5V4.5A2.5 2.5 0 0 1 6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5Z\"/><path d=\"M8 7h8M8 11h6M8 15h4\"/>",
+ "contributions": {
+ "nav": [
+ {
+ "id": "walkthrough-studio",
+ "label": "Walkthrough Studio",
+ "route": "/walkthrough-studio",
+ "category": "system",
+ "icon": "<path d=\"M4 19.5V4.5A2.5 2.5 0 0 1 6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5Z\"/><path d=\"M8 7h8M8 11h6M8 15h4\"/>"
+ }
+ ],
+ "routes": [
+ {
+ "path": "walkthrough-studio",
+ "component": "WalkthroughStudioPage",
+ "layout": "full"
+ }
+ ],
+ "page_titles": {
+ "/walkthrough-studio": "Walkthrough Studio"
+ },
+ "command_palette": [
+ {
+ "label": "Walkthrough Studio",
+ "path": "/walkthrough-studio",
+ "category": "Tools",
+ "keywords": "guide tutorial onboarding author builder"
+ }
+ ],
+ "walkthroughs": [
+ {
+ "id": "build-first-walkthrough",
+ "title": "Build your first walkthrough",
+ "description": "Design a guided flow, test it in the live dock, and publish it to your team.",
+ "duration": "About 6 minutes",
+ "icon": "guide",
+ "tone": "violet",
+ "secondary": true,
+ "permissions": [
+ {
+ "feature": "settings",
+ "level": "admin"
+ }
+ ],
+ "steps": [
+ {
+ "id": "open-studio",
+ "title": "Open Walkthrough Studio",
+ "description": "The Studio keeps guide metadata, steps, and the live preview visible in one authoring surface.",
+ "action": "Open Studio",
+ "path": "/walkthrough-studio",
+ "target": "studio-guide-meta",
+ "completion": {
+ "type": "route",
+ "path": "/walkthrough-studio"
+ }
+ },
+ {
+ "id": "shape-guide",
+ "title": "Describe the outcome",
+ "description": "Give the guide a stable id, a concrete outcome, and an honest duration.",
+ "target": "studio-guide-meta",
+ "completion": {
+ "type": "manual"
+ }
+ },
+ {
+ "id": "author-steps",
+ "title": "Author and order the steps",
+ "description": "Choose how each step completes and point it at a stable data-walkthrough token.",
+ "target": "studio-step-list",
+ "completion": {
+ "type": "manual"
+ }
+ },
+ {
+ "id": "preview-guide",
+ "title": "Preview the guide",
+ "description": "Run the draft in the real walkthrough dock before publishing it.",
+ "target": "studio-preview",
+ "completion": {
+ "type": "manual"
+ }
+ },
+ {
+ "id": "publish-guide",
+ "title": "Publish the walkthrough",
+ "description": "Save the validated definition so every permitted user sees it immediately.",
+ "action": "Publish walkthrough",
+ "target": "studio-publish",
+ "completion": {
+ "type": "signal",
+ "signal": "walkthrough-studio-guide-saved"
+ }
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/frontend/src/plugins/serverkit-walkthrough-studio/styles/walkthrough-studio.scss b/frontend/src/plugins/serverkit-walkthrough-studio/styles/walkthrough-studio.scss
new file mode 100644
index 00000000..a013963f
--- /dev/null
+++ b/frontend/src/plugins/serverkit-walkthrough-studio/styles/walkthrough-studio.scss
@@ -0,0 +1,596 @@
+@import '../../../styles/variables';
+
+$wts-radius: $radius-lg;
+$wts-radius-sm: $radius-md;
+
+.wts-page {
+ // Local aliases keep the extension's stylesheet readable while resolving
+ // through ServerKit's established SCSS token layer and active theme.
+ --border-color: #{$border-color};
+ --text-muted: #{$text-muted};
+ --bg-primary: #{$bg-body};
+ --success-color: #{$success-color};
+ --warning-color: #{$warning-color};
+ --danger-color: #{$danger-color};
+
+ min-block-size: 100%;
+ background:
+ linear-gradient(rgba(255, 255, 255, 0.018) 1px, transparent 1px),
+ linear-gradient(90deg, rgba(255, 255, 255, 0.018) 1px, transparent 1px),
+ var(--bg-primary);
+ background-size: 32px 32px;
+}
+
+.wts-file-input {
+ display: none;
+}
+
+.wts-shell {
+ display: grid;
+ grid-template-columns: 230px minmax(540px, 1fr) 310px;
+ min-block-size: calc(100vh - 112px);
+ border-block-start: 1px solid var(--border-color);
+}
+
+.wts-library,
+.wts-preview {
+ background: color-mix(in srgb, var(--bg-secondary) 92%, transparent);
+}
+
+.wts-library {
+ display: flex;
+ flex-direction: column;
+ min-inline-size: 0;
+ border-inline-end: 1px solid var(--border-color);
+}
+
+.wts-panel-heading {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ min-block-size: 48px;
+ padding: 10px 14px;
+ border-block-end: 1px solid var(--border-color);
+ color: var(--text-secondary);
+ font-family: $font-mono;
+ font-size: 10px;
+ font-weight: 700;
+ letter-spacing: 0.12em;
+ text-transform: uppercase;
+}
+
+.wts-library__intro {
+ margin: 0;
+ padding: 14px;
+ border-block-end: 1px solid var(--border-color);
+ color: var(--text-muted);
+ font-size: 12px;
+ line-height: 1.55;
+}
+
+.wts-library__list {
+ flex: 1;
+ overflow: auto;
+ padding: 8px;
+}
+
+.wts-library__empty {
+ display: flex;
+ flex-direction: column;
+ align-items: flex-start;
+ inline-size: 100%;
+ gap: 7px;
+ padding: 18px;
+ border: 1px dashed var(--border-color);
+ border-radius: $wts-radius;
+ background: transparent;
+ color: var(--text-muted);
+ text-align: start;
+
+ strong {
+ color: var(--text-primary);
+ font-size: 12px;
+ }
+
+ span {
+ font-size: 11px;
+ }
+
+ &:hover {
+ border-color: var(--accent-primary);
+ color: var(--accent-primary);
+ }
+}
+
+.wts-library__item {
+ display: grid;
+ grid-template-columns: minmax(0, 1fr) auto;
+ align-items: center;
+ border-radius: $wts-radius-sm;
+
+ > button:first-child {
+ display: flex;
+ flex-direction: column;
+ align-items: flex-start;
+ min-inline-size: 0;
+ gap: 3px;
+ padding: 10px;
+ border: 0;
+ background: transparent;
+ color: var(--text-primary);
+ text-align: start;
+
+ strong {
+ overflow: hidden;
+ max-inline-size: 100%;
+ font-size: 12px;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+
+ span {
+ color: var(--text-muted);
+ font-family: $font-mono;
+ font-size: 9px;
+ text-transform: uppercase;
+ }
+ }
+
+ &:hover,
+ &.is-active {
+ background: var(--bg-hover);
+ }
+
+ &.is-active {
+ box-shadow: inset 2px 0 var(--accent-primary);
+ }
+}
+
+.wts-library__footer {
+ padding: 12px;
+ border-block-start: 1px solid var(--border-color);
+
+ .btn {
+ inline-size: 100%;
+ }
+}
+
+.wts-editor {
+ min-inline-size: 0;
+ padding: 28px clamp(20px, 3vw, 48px) 64px;
+}
+
+.wts-section {
+ max-inline-size: 860px;
+ margin-inline: auto;
+ padding-block: 4px 42px;
+
+ + .wts-section {
+ padding-block-start: 34px;
+ border-block-start: 1px solid var(--border-color);
+ }
+}
+
+.wts-section__head {
+ display: flex;
+ align-items: flex-start;
+ justify-content: space-between;
+ gap: 18px;
+ margin-block-end: 22px;
+
+ h2 {
+ margin: 5px 0 0;
+ color: var(--text-primary);
+ font-size: clamp(20px, 2vw, 28px);
+ font-weight: 500;
+ letter-spacing: -0.035em;
+ }
+}
+
+.wts-eyebrow {
+ color: var(--accent-primary);
+ font-family: $font-mono;
+ font-size: 9px;
+ font-weight: 700;
+ letter-spacing: 0.14em;
+}
+
+.wts-toggle {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ color: var(--text-muted);
+ font-size: 11px;
+}
+
+.wts-form-grid {
+ display: grid;
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ gap: 16px;
+
+ > .wts-field:nth-child(3),
+ > .wts-callout,
+ > .wts-form-grid__compact {
+ grid-column: 1 / -1;
+ }
+}
+
+.wts-form-grid__compact {
+ display: grid;
+ grid-template-columns: repeat(3, minmax(0, 1fr));
+ gap: 12px;
+}
+
+.wts-field {
+ display: flex;
+ flex-direction: column;
+ min-inline-size: 0;
+ gap: 7px;
+
+ input,
+ textarea,
+ select {
+ inline-size: 100%;
+ min-block-size: 38px;
+ padding: 9px 11px;
+ border: 1px solid var(--border-color);
+ border-radius: $wts-radius-sm;
+ outline: none;
+ background: var(--bg-secondary);
+ color: var(--text-primary);
+ font: inherit;
+ font-size: 12px;
+
+ &:focus {
+ border-color: var(--accent-primary);
+ box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent-primary) 14%, transparent);
+ }
+ }
+
+ textarea {
+ resize: vertical;
+ line-height: 1.55;
+ }
+
+ small {
+ color: var(--text-muted);
+ font-size: 10px;
+ line-height: 1.45;
+ }
+}
+
+.wts-field__label {
+ color: var(--text-secondary);
+ font-family: $font-mono;
+ font-size: 9px;
+ font-weight: 700;
+ letter-spacing: 0.08em;
+ text-transform: uppercase;
+}
+
+.wts-step-workbench {
+ display: grid;
+ grid-template-columns: 210px minmax(0, 1fr);
+ overflow: hidden;
+ border: 1px solid var(--border-color);
+ border-radius: $wts-radius;
+ background: var(--bg-card);
+}
+
+.wts-step-rail {
+ padding: 8px;
+ border-inline-end: 1px solid var(--border-color);
+ background: var(--bg-secondary);
+
+ button {
+ display: grid;
+ grid-template-columns: auto auto minmax(0, 1fr);
+ align-items: center;
+ inline-size: 100%;
+ gap: 7px;
+ padding: 10px 8px;
+ border: 0;
+ border-radius: $wts-radius-sm;
+ background: transparent;
+ color: var(--text-muted);
+ text-align: start;
+
+ strong {
+ overflow: hidden;
+ color: var(--text-secondary);
+ font-size: 11px;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+
+ small {
+ grid-column: 3;
+ color: var(--text-muted);
+ font-family: $font-mono;
+ font-size: 8px;
+ text-transform: uppercase;
+ }
+
+ &:hover,
+ &.is-active {
+ background: var(--bg-hover);
+ }
+
+ &.is-active strong {
+ color: var(--text-primary);
+ }
+ }
+}
+
+.wts-step-editor {
+ min-inline-size: 0;
+ padding: 18px;
+}
+
+.wts-step-editor__tools {
+ display: flex;
+ align-items: center;
+ justify-content: flex-end;
+ gap: 2px;
+ margin-block-end: 16px;
+
+ > span {
+ margin-inline-end: auto;
+ color: var(--text-muted);
+ font-family: $font-mono;
+ font-size: 9px;
+ letter-spacing: 0.12em;
+ }
+}
+
+.wts-callout {
+ margin: 0;
+ padding: 10px 12px;
+ border-inline-start: 2px solid var(--accent-primary);
+ background: color-mix(in srgb, var(--accent-primary) 6%, transparent);
+ color: var(--text-muted);
+ font-size: 11px;
+ line-height: 1.5;
+}
+
+.wts-preview {
+ position: sticky;
+ inset-block-start: 0;
+ align-self: start;
+ overflow: auto;
+ max-block-size: calc(100vh - 64px);
+ border-inline-start: 1px solid var(--border-color);
+ padding-block-end: 24px;
+
+ > .btn,
+ > details,
+ > .wts-issues {
+ margin-inline: 14px;
+ }
+
+ > .btn {
+ inline-size: calc(100% - 28px);
+ }
+}
+
+.wts-validity {
+ padding: 3px 7px;
+ border-radius: 999px;
+ background: color-mix(in srgb, var(--success-color) 12%, transparent);
+ color: var(--success-color);
+ font-size: 8px;
+
+ &.is-invalid {
+ background: color-mix(in srgb, var(--danger-color) 12%, transparent);
+ color: var(--danger-color);
+ }
+}
+
+.wts-guide-card {
+ position: relative;
+ overflow: hidden;
+ margin: 14px;
+ padding: 18px;
+ border: 1px solid var(--border-color);
+ border-radius: $wts-radius;
+ background: var(--bg-card);
+
+ &::before {
+ position: absolute;
+ inset: 0 auto 0 0;
+ inline-size: 3px;
+ background: var(--accent-primary);
+ content: '';
+ }
+
+ &.is-green::before { background: var(--success-color); }
+ &.is-amber::before { background: var(--warning-color); }
+ &.is-violet::before { background: #a78bfa; }
+
+ h2 {
+ margin: 9px 0 7px;
+ color: var(--text-primary);
+ font-size: 18px;
+ font-weight: 550;
+ letter-spacing: -0.025em;
+ }
+
+ p {
+ margin: 0;
+ color: var(--text-muted);
+ font-size: 11px;
+ line-height: 1.55;
+ }
+}
+
+.wts-guide-card__kicker {
+ color: var(--accent-primary);
+ font-family: $font-mono;
+ font-size: 8px;
+ font-weight: 700;
+ letter-spacing: 0.13em;
+}
+
+.wts-guide-card__meta {
+ display: flex;
+ gap: 12px;
+ margin-block-start: 16px;
+ color: var(--text-muted);
+ font-family: $font-mono;
+ font-size: 9px;
+}
+
+.wts-preview-steps {
+ display: flex;
+ flex-direction: column;
+ gap: 0;
+ margin: 4px 14px 16px;
+ padding: 0;
+ list-style: none;
+
+ li {
+ display: grid;
+ grid-template-columns: 24px minmax(0, 1fr);
+ gap: 9px;
+ padding: 10px 4px;
+ border-block-end: 1px solid var(--border-color);
+
+ > span {
+ color: var(--text-muted);
+ font-family: $font-mono;
+ font-size: 9px;
+ }
+
+ div {
+ display: flex;
+ min-inline-size: 0;
+ flex-direction: column;
+ gap: 3px;
+ }
+
+ strong {
+ overflow: hidden;
+ color: var(--text-secondary);
+ font-size: 11px;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+
+ small {
+ color: var(--text-muted);
+ font-family: $font-mono;
+ font-size: 8px;
+ }
+ }
+}
+
+.wts-issues {
+ margin-block-end: 12px;
+ padding: 10px;
+ border: 1px solid color-mix(in srgb, var(--danger-color) 30%, var(--border-color));
+ border-radius: $wts-radius-sm;
+ background: color-mix(in srgb, var(--danger-color) 5%, transparent);
+
+ p {
+ margin: 0;
+ color: var(--text-muted);
+ font-size: 10px;
+ line-height: 1.5;
+
+ + p { margin-block-start: 4px; }
+ strong { color: var(--danger-color); }
+ }
+}
+
+.wts-json {
+ margin-block-start: 12px;
+ border: 1px solid var(--border-color);
+ border-radius: $wts-radius-sm;
+
+ summary {
+ display: flex;
+ align-items: center;
+ gap: 7px;
+ padding: 10px;
+ color: var(--text-muted);
+ cursor: pointer;
+ font-family: $font-mono;
+ font-size: 9px;
+ text-transform: uppercase;
+ }
+
+ pre {
+ overflow: auto;
+ max-block-size: 320px;
+ margin: 0;
+ padding: 10px;
+ border-block-start: 1px solid var(--border-color);
+ color: var(--text-secondary);
+ font-family: $font-mono;
+ font-size: 9px;
+ line-height: 1.55;
+ white-space: pre-wrap;
+ }
+}
+
+.wts-muted {
+ color: var(--text-muted);
+ font-size: 11px;
+}
+
+@media (max-width: 1280px) {
+ .wts-shell {
+ grid-template-columns: 210px minmax(520px, 1fr);
+ }
+
+ .wts-preview {
+ position: static;
+ grid-column: 2;
+ max-block-size: none;
+ border-block-start: 1px solid var(--border-color);
+ border-inline-start: 0;
+ }
+}
+
+@media (max-width: 900px) {
+ .wts-shell {
+ display: block;
+ }
+
+ .wts-library {
+ border-block-end: 1px solid var(--border-color);
+ border-inline-end: 0;
+ }
+
+ .wts-library__list {
+ max-block-size: 220px;
+ }
+
+ .wts-step-workbench {
+ grid-template-columns: 1fr;
+ }
+
+ .wts-step-rail {
+ border-block-end: 1px solid var(--border-color);
+ border-inline-end: 0;
+ }
+
+ .wts-preview {
+ border-inline-start: 0;
+ }
+}
+
+@media (max-width: 640px) {
+ .wts-editor {
+ padding-inline: 14px;
+ }
+
+ .wts-form-grid,
+ .wts-form-grid__compact {
+ grid-template-columns: 1fr;
+ }
+
+ .wts-form-grid > * {
+ grid-column: 1;
+ }
+}