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 declarative walkthrough contribution contract

Juan Deniscfcf965e2442
diff --git a/backend/app/api/plugins.py b/backend/app/api/plugins.py
index 222cff78..66d74e47 100644
--- a/backend/app/api/plugins.py
+++ b/backend/app/api/plugins.py
@@ -481,6 +481,10 @@ def get_manifest_spec():
'description': 'Placeable dashboard widget types: {id, name, component, icon?, category?, description?, w?, h?, min?, default_cfg?}. Unlike widgets (fixed host slot), these appear in the dashboard widget library and the user positions, resizes and configures instances of them.'},
'layouts': {'type': 'array',
'description': 'Custom layout components: {id, component}. The component must render <Outlet/> somewhere; it wraps every route that references its id. Built-in layouts (padded, full, bare) are reserved.'},
+ 'walkthroughs': {
+ 'type': 'array',
+ 'description': 'Declarative guided flows: {id, title, description, duration?, icon?, tone?, secondary?, permissions?, steps}. Steps use stable data-walkthrough target tokens and completion {type: manual|route|signal|check|target, ...}. Definitions are namespaced to the contributing extension at runtime and cannot contain executable code.',
+ },
},
},
},
diff --git a/backend/app/api/walkthroughs.py b/backend/app/api/walkthroughs.py
index 43686c30..f4ac3dff 100644
--- a/backend/app/api/walkthroughs.py
+++ b/backend/app/api/walkthroughs.py
@@ -2,7 +2,11 @@
from flask import Blueprint, jsonify, request
-from app.middleware.rbac import get_current_user, require_role, viewer_required
+from app.middleware.rbac import admin_required, get_current_user, require_role, viewer_required
+from app.services.walkthrough_definition_service import (
+ WalkthroughDefinitionError,
+ WalkthroughDefinitionService,
+)
from app.services.walkthrough_service import (
WalkthroughService,
WalkthroughStateError,
@@ -29,3 +33,24 @@ def update_walkthrough_state():
except WalkthroughStateError as exc:
return jsonify({'error': str(exc)}), 400
return jsonify({'success': True, 'state': state}), 200
+
+
+@walkthroughs_bp.route('/definitions', methods=['GET'])
+@viewer_required
+def get_walkthrough_definitions():
+ return jsonify({
+ 'definitions': WalkthroughDefinitionService.get_definitions(),
+ }), 200
+
+
+@walkthroughs_bp.route('/definitions', methods=['PUT'])
+@admin_required
+def update_walkthrough_definitions():
+ data = request.get_json(silent=True) or {}
+ try:
+ definitions = WalkthroughDefinitionService.save_definitions(
+ data.get('definitions', data),
+ )
+ except WalkthroughDefinitionError as exc:
+ return jsonify({'error': str(exc)}), 400
+ return jsonify({'success': True, 'definitions': definitions}), 200
diff --git a/backend/app/services/contribution_service.py b/backend/app/services/contribution_service.py
index 8eec9d5a..d60bd3af 100644
--- a/backend/app/services/contribution_service.py
+++ b/backend/app/services/contribution_service.py
@@ -12,7 +12,8 @@ A plugin manifest may declare a `contributions` block with any subset of:
"dashboard_widgets": [{ id, name, component, icon?, category?,
description?, w?, h?, min?, default_cfg? }],
"layouts": [{ id, component }],
- "tabs": [{ group, to, label, icon?, end?, order? }]
+ "tabs": [{ group, to, label, icon?, end?, order? }],
+ "walkthroughs": [{ id, title, description, steps, ... }]
}
`widgets` and `dashboard_widgets` are different surfaces and are easy to
@@ -113,6 +114,7 @@ def get_active_contributions():
dashboard_widgets = []
layouts = []
tabs = []
+ walkthroughs = []
# AI assistant contributions: per-route suggested prompts + custom
# tool-result renderers, consumed by the core AIAssistant.
ai = {'suggested_prompts': [], 'tool_renderers': []}
@@ -129,6 +131,7 @@ def get_active_contributions():
dashboard_widgets.extend(_tag(contrib.get('dashboard_widgets'), p.slug))
layouts.extend(_tag(contrib.get('layouts'), p.slug))
tabs.extend(_tag(contrib.get('tabs'), p.slug))
+ walkthroughs.extend(_tag(contrib.get('walkthroughs'), p.slug))
ai_contrib = contrib.get('ai')
if isinstance(ai_contrib, dict):
@@ -150,6 +153,7 @@ def get_active_contributions():
'dashboard_widgets': dashboard_widgets,
'layouts': layouts,
'tabs': tabs,
+ 'walkthroughs': walkthroughs,
'ai': ai,
# Panel SDK version the client uses to gate runtime bundles (plan 25 #1).
'sdk_version': SDK_VERSION,
diff --git a/backend/app/services/plugin_service.py b/backend/app/services/plugin_service.py
index d09002f3..8ebb3843 100644
--- a/backend/app/services/plugin_service.py
+++ b/backend/app/services/plugin_service.py
@@ -443,6 +443,7 @@ _REQUIRED_CONTRIB_KEYS = {
'widgets': ('slot', 'component'),
'dashboard_widgets': ('id', 'name', 'component'),
'layouts': ('id', 'component'),
+ 'walkthroughs': ('id', 'title', 'description', 'steps'),
}
_KNOWN_CONTRIB_KINDS = set(_REQUIRED_CONTRIB_KEYS) | {'page_titles', 'ai'}
@@ -534,6 +535,16 @@ def _validate_manifest(manifest):
if titles is not None and not isinstance(titles, dict):
problems.append('contributions.page_titles must be an object of path -> title')
+ walkthroughs = contrib.get('walkthroughs')
+ if walkthroughs is not None:
+ from app.services.walkthrough_definition_service import (
+ validate_walkthrough_definitions,
+ )
+ problems.extend(validate_walkthrough_definitions(
+ walkthroughs,
+ field='contributions.walkthroughs',
+ ))
+
if problems:
raise ValueError(
'Manifest validation failed: ' + '; '.join(problems)
diff --git a/backend/app/services/walkthrough_definition_service.py b/backend/app/services/walkthrough_definition_service.py
new file mode 100644
index 00000000..bbb15878
--- /dev/null
+++ b/backend/app/services/walkthrough_definition_service.py
@@ -0,0 +1,206 @@
+"""Validation and storage for declarative walkthrough definitions.
+
+Walkthroughs are intentionally data-only. They may point at routes and stable
+``data-walkthrough`` targets, listen for named UI signals, or use a host-owned
+status check. They may never embed JavaScript, selectors outside the
+walkthrough namespace, commands, or arbitrary API requests.
+"""
+
+import json
+import re
+from copy import deepcopy
+from typing import Any, Dict, List
+
+from app import db
+from app.models.system_settings import SystemSettings
+
+
+MAX_WALKTHROUGHS = 32
+MAX_STEPS = 32
+MAX_DOCUMENT_BYTES = 128 * 1024
+COMPLETION_TYPES = frozenset({'manual', 'route', 'signal', 'check', 'target'})
+
+_CUSTOM_KEY = 'walkthroughs.custom.definitions'
+_ID_RE = re.compile(r'^[a-z0-9][a-z0-9._-]{0,79}$')
+_TOKEN_RE = re.compile(r'^[a-z0-9][a-z0-9._:-]{0,119}$')
+_TARGET_RE = re.compile(r'^[a-z0-9][a-z0-9._:-]{0,79}$')
+_LEVELS = {'read', 'write', 'admin'}
+_GUIDE_FIELDS = {
+ '$schema', 'id', 'title', 'title_key', 'description', 'description_key',
+ 'duration', 'duration_key', 'icon', 'tone', 'secondary', 'permissions', 'steps',
+}
+_STEP_FIELDS = {
+ 'id', 'title', 'title_key', 'description', 'description_key', 'action',
+ 'action_key', 'path', 'target', 'completion',
+}
+_COMPLETION_FIELDS = {'type', 'path', 'signal', 'check'}
+
+
+class WalkthroughDefinitionError(ValueError):
+ """Raised when a declarative walkthrough document is invalid."""
+
+
+def _bounded_string(value: Any, *, maximum: int) -> bool:
+ return isinstance(value, str) and 0 < len(value.strip()) <= maximum
+
+
+def validate_walkthrough_definitions(raw: Any, *, field: str = 'walkthroughs') -> List[str]:
+ """Return precise validation problems for a walkthrough definition list."""
+ if not isinstance(raw, list):
+ return [f'{field} must be a list']
+ if len(raw) > MAX_WALKTHROUGHS:
+ return [f'{field} may contain at most {MAX_WALKTHROUGHS} walkthroughs']
+
+ problems = []
+ seen_guides = set()
+ for guide_index, guide in enumerate(raw):
+ base = f'{field}[{guide_index}]'
+ if not isinstance(guide, dict):
+ problems.append(f'{base} must be an object')
+ continue
+
+ unknown_guide_fields = sorted(set(guide) - _GUIDE_FIELDS)
+ if unknown_guide_fields:
+ problems.append(f'{base} contains unsupported fields: {", ".join(unknown_guide_fields)}')
+
+ guide_id = guide.get('id')
+ if not isinstance(guide_id, str) or not _ID_RE.fullmatch(guide_id):
+ problems.append(f'{base}.id must match {_ID_RE.pattern}')
+ elif guide_id in seen_guides:
+ problems.append(f'{base}.id duplicates {guide_id!r}')
+ else:
+ seen_guides.add(guide_id)
+
+ for name, maximum in (
+ ('title', 120), ('description', 320), ('duration', 80)):
+ if name in guide and not _bounded_string(guide[name], maximum=maximum):
+ problems.append(f'{base}.{name} must be a non-empty string up to {maximum} characters')
+ if not _bounded_string(guide.get('title'), maximum=120):
+ problems.append(f'{base}.title is required')
+ if not _bounded_string(guide.get('description'), maximum=320):
+ problems.append(f'{base}.description is required')
+
+ for name in ('title_key', 'description_key', 'duration_key', 'icon', 'tone'):
+ if name in guide and not _bounded_string(guide[name], maximum=120):
+ problems.append(f'{base}.{name} must be a non-empty string up to 120 characters')
+ if 'secondary' in guide and not isinstance(guide['secondary'], bool):
+ problems.append(f'{base}.secondary must be a boolean')
+
+ permissions = guide.get('permissions', [])
+ if not isinstance(permissions, list) or len(permissions) > 16:
+ problems.append(f'{base}.permissions must be a list with at most 16 entries')
+ else:
+ for permission_index, permission in enumerate(permissions):
+ pbase = f'{base}.permissions[{permission_index}]'
+ if not isinstance(permission, dict):
+ problems.append(f'{pbase} must be an object')
+ continue
+ if not _bounded_string(permission.get('feature'), maximum=80):
+ problems.append(f'{pbase}.feature is required')
+ if permission.get('level') not in _LEVELS:
+ problems.append(f'{pbase}.level must be read, write, or admin')
+
+ steps = guide.get('steps')
+ if not isinstance(steps, list) or not steps:
+ problems.append(f'{base}.steps must be a non-empty list')
+ continue
+ if len(steps) > MAX_STEPS:
+ problems.append(f'{base}.steps may contain at most {MAX_STEPS} steps')
+ continue
+
+ seen_steps = set()
+ for step_index, step in enumerate(steps):
+ sbase = f'{base}.steps[{step_index}]'
+ if not isinstance(step, dict):
+ problems.append(f'{sbase} must be an object')
+ continue
+ unknown_step_fields = sorted(set(step) - _STEP_FIELDS)
+ if unknown_step_fields:
+ problems.append(f'{sbase} contains unsupported fields: {", ".join(unknown_step_fields)}')
+ step_id = step.get('id')
+ if not isinstance(step_id, str) or not _ID_RE.fullmatch(step_id):
+ problems.append(f'{sbase}.id must match {_ID_RE.pattern}')
+ elif step_id in seen_steps:
+ problems.append(f'{sbase}.id duplicates {step_id!r}')
+ else:
+ seen_steps.add(step_id)
+
+ if not _bounded_string(step.get('title'), maximum=120):
+ problems.append(f'{sbase}.title is required')
+ if not _bounded_string(step.get('description'), maximum=500):
+ problems.append(f'{sbase}.description is required')
+ for name, maximum in (
+ ('action', 80), ('title_key', 120),
+ ('description_key', 120), ('action_key', 120)):
+ if name in step and not _bounded_string(step[name], maximum=maximum):
+ problems.append(f'{sbase}.{name} must be a non-empty string up to {maximum} characters')
+
+ path = step.get('path')
+ if path is not None and (not _bounded_string(path, maximum=500) or not path.startswith('/')):
+ problems.append(f'{sbase}.path must begin with / and contain at most 500 characters')
+ target = step.get('target')
+ if target is not None and (not isinstance(target, str) or not _TARGET_RE.fullmatch(target)):
+ problems.append(f'{sbase}.target must be a stable data-walkthrough token')
+
+ completion = step.get('completion', {'type': 'manual'})
+ if not isinstance(completion, dict):
+ problems.append(f'{sbase}.completion must be an object')
+ continue
+ unknown_completion_fields = sorted(set(completion) - _COMPLETION_FIELDS)
+ if unknown_completion_fields:
+ problems.append(
+ f'{sbase}.completion contains unsupported fields: '
+ f'{", ".join(unknown_completion_fields)}')
+ completion_type = completion.get('type', 'manual')
+ if completion_type not in COMPLETION_TYPES:
+ problems.append(
+ f'{sbase}.completion.type must be one of {", ".join(sorted(COMPLETION_TYPES))}')
+ elif completion_type == 'route':
+ route = completion.get('path') or path
+ if not isinstance(route, str) or not route.startswith('/') or len(route) > 500:
+ problems.append(f'{sbase}.completion.path must be a route beginning with /')
+ elif completion_type == 'signal':
+ signal = completion.get('signal')
+ if not isinstance(signal, str) or not _TOKEN_RE.fullmatch(signal):
+ problems.append(f'{sbase}.completion.signal must be a stable event token')
+ elif completion_type == 'check':
+ check = completion.get('check')
+ if not isinstance(check, str) or not _TOKEN_RE.fullmatch(check):
+ problems.append(f'{sbase}.completion.check must be a named host check')
+ elif completion_type == 'target' and target is None:
+ problems.append(f'{sbase}.completion target requires step.target')
+
+ try:
+ encoded_size = len(json.dumps(raw, ensure_ascii=False).encode('utf-8'))
+ if encoded_size > MAX_DOCUMENT_BYTES:
+ problems.append(f'{field} exceeds the {MAX_DOCUMENT_BYTES}-byte limit')
+ except (TypeError, ValueError):
+ problems.append(f'{field} must contain JSON-compatible values')
+
+ return problems
+
+
+class WalkthroughDefinitionService:
+ """Panel-wide custom walkthrough library managed by administrators."""
+
+ @staticmethod
+ def get_definitions() -> List[Dict[str, Any]]:
+ raw = SystemSettings.get(_CUSTOM_KEY, [])
+ if validate_walkthrough_definitions(raw, field='definitions'):
+ return []
+ return deepcopy(raw)
+
+ @staticmethod
+ def save_definitions(raw: Any) -> List[Dict[str, Any]]:
+ problems = validate_walkthrough_definitions(raw, field='definitions')
+ if problems:
+ raise WalkthroughDefinitionError('; '.join(problems))
+ definitions = deepcopy(raw)
+ SystemSettings.set(
+ key=_CUSTOM_KEY,
+ value=definitions,
+ value_type='json',
+ description='Panel-wide custom guided walkthrough definitions',
+ )
+ db.session.commit()
+ return definitions
diff --git a/backend/app/utils/sdk.py b/backend/app/utils/sdk.py
index de402065..21d065cf 100644
--- a/backend/app/utils/sdk.py
+++ b/backend/app/utils/sdk.py
@@ -31,6 +31,7 @@ from app.utils.version import compare_versions
# Keep in lock-step with frontend/src/plugins/sdk/index.js `SDK_VERSION`.
#
+# 1.5.0 — declarative walkthrough authoring helpers and useWalkthroughs.
# 1.3.0 — plan 79: localization. useTranslation/Trans/t, useLocale, useLabel,
# and the locale-aware format door (useFormat + formatDate/Number/Relative/…).
# i18next and react-i18next also became SHARED vendor singletons, so an
@@ -40,7 +41,7 @@ from app.utils.version import compare_versions
# 1.2.0 — plan 52 Phases 4-5: layout/feedback primitives, ui/* form kit,
# common hooks, format utils, and the cross-feature embeds (git repo-connect,
# backups ProtectionPanel) the WordPress runtime-ESM extraction needed.
-SDK_VERSION = '1.4.0'
+SDK_VERSION = '1.5.0'
def _version_tuple(v):
diff --git a/backend/tests/test_plugins_pipeline.py b/backend/tests/test_plugins_pipeline.py
index 634eecc0..f0beb697 100644
--- a/backend/tests/test_plugins_pipeline.py
+++ b/backend/tests/test_plugins_pipeline.py
@@ -72,6 +72,19 @@ def _write_builtin(builtin_dir, slug='serverkit-demo', version='1.0.0',
'component': 'DemoWidget', 'category': 'Utility',
'w': 3, 'h': 2, 'min': [2, 2],
'default_cfg': {'limit': 5}}],
+ 'walkthroughs': [{
+ 'id': 'demo-first-run',
+ 'title': 'Try Demo',
+ 'description': 'Open Demo and complete one safe action.',
+ 'steps': [{
+ 'id': 'open-demo',
+ 'title': 'Open Demo',
+ 'description': 'Navigate to the Demo extension.',
+ 'path': '/demo',
+ 'target': 'demo-page',
+ 'completion': {'type': 'route', 'path': '/demo'},
+ }],
+ }],
},
}
(folder / 'plugin.json').write_text(json.dumps(manifest), encoding='utf-8')
@@ -219,7 +232,7 @@ def test_contributions_endpoint_envelope(app, client, auth_headers, plugin_dirs)
# The envelope always carries every key.
for key in ('nav', 'routes', 'page_titles', 'command_palette', 'widgets',
- 'dashboard_widgets', 'layouts', 'tabs', 'ai'):
+ 'dashboard_widgets', 'layouts', 'tabs', 'walkthroughs', 'ai'):
assert key in data
# Contributions are tagged with the source plugin slug.
@@ -243,6 +256,10 @@ def test_contributions_endpoint_envelope(app, client, auth_headers, plugin_dirs)
for w in data['dashboard_widgets'])
assert not any(w.get('id') == 'demo-widget' for w in data['widgets'])
+ assert any(w.get('plugin') == 'serverkit-demo'
+ and w.get('id') == 'demo-first-run'
+ for w in data['walkthroughs'])
+
def test_disabled_plugin_drops_from_contributions(app, client, auth_headers, plugin_dirs):
_write_builtin(plugin_dirs['builtin'])
@@ -356,6 +373,21 @@ def test_manifest_lint_rejects_bad_shapes():
'contributions': {'routes': [{'path': 'x'}]}})
with pytest.raises(ValueError, match='lifecycle.install'):
_validate_manifest({**_LINT_BASE, 'lifecycle': {'install': 'no-colon'}})
+ with pytest.raises(ValueError, match=r'walkthroughs\[0\].steps\[0\].target'):
+ _validate_manifest({
+ **_LINT_BASE,
+ 'contributions': {'walkthroughs': [{
+ 'id': 'bad-guide',
+ 'title': 'Bad Guide',
+ 'description': 'Uses an arbitrary selector.',
+ 'steps': [{
+ 'id': 'bad-step',
+ 'title': 'Bad Step',
+ 'description': 'This must fail.',
+ 'target': '#password',
+ }],
+ }]},
+ })
def test_manifest_lint_unknown_contrib_kind_warns_not_fails():
diff --git a/backend/tests/test_walkthroughs.py b/backend/tests/test_walkthroughs.py
index b617b730..d54c62de 100644
--- a/backend/tests/test_walkthroughs.py
+++ b/backend/tests/test_walkthroughs.py
@@ -53,3 +53,76 @@ def test_walkthrough_state_rejects_unbounded_or_unknown_data(client, db_session)
def test_walkthrough_state_requires_authentication(client):
assert client.get('/api/v1/walkthroughs/state').status_code in (401, 422)
assert client.put('/api/v1/walkthroughs/state', json={}).status_code in (401, 422)
+
+
+def _definition(guide_id='custom-guide'):
+ return {
+ 'id': guide_id,
+ 'title': 'Custom guide',
+ 'description': 'Complete a safe, declarative task.',
+ 'duration': 'About 3 minutes',
+ 'secondary': True,
+ 'permissions': [{'feature': 'applications', 'level': 'write'}],
+ 'steps': [{
+ 'id': 'open-services',
+ 'title': 'Open services',
+ 'description': 'Navigate to the services list.',
+ 'action': 'Open services',
+ 'path': '/services',
+ 'target': 'services-list',
+ 'completion': {'type': 'route', 'path': '/services'},
+ }],
+ }
+
+
+def test_admin_can_publish_panel_walkthroughs_visible_to_viewers(client, db_session):
+ admin = make_user(db_session, role='admin', username='guide-admin')
+ viewer = make_user(db_session, role='viewer', username='guide-reader')
+
+ response = client.put(
+ '/api/v1/walkthroughs/definitions',
+ headers=headers_for(admin),
+ json={'definitions': [_definition()]},
+ )
+ assert response.status_code == 200
+ assert response.get_json()['definitions'][0]['id'] == 'custom-guide'
+
+ response = client.get(
+ '/api/v1/walkthroughs/definitions',
+ headers=headers_for(viewer),
+ )
+ assert response.status_code == 200
+ assert response.get_json()['definitions'][0]['title'] == 'Custom guide'
+
+
+def test_viewer_cannot_publish_walkthrough_definitions(client, db_session):
+ viewer = make_user(db_session, role='viewer', username='guide-publisher')
+ response = client.put(
+ '/api/v1/walkthroughs/definitions',
+ headers=headers_for(viewer),
+ json={'definitions': [_definition()]},
+ )
+ assert response.status_code == 403
+
+
+def test_walkthrough_definition_rejects_executable_or_arbitrary_targets(client, db_session):
+ admin = make_user(db_session, role='admin', username='guide-validator')
+ definition = _definition()
+ definition['steps'][0]['target'] = '#password-field'
+ definition['steps'][0]['javascript'] = 'alert(1)'
+
+ response = client.put(
+ '/api/v1/walkthroughs/definitions',
+ headers=headers_for(admin),
+ json={'definitions': [definition]},
+ )
+ assert response.status_code == 400
+ assert 'data-walkthrough token' in response.get_json()['error']
+
+
+def test_walkthrough_definitions_require_authentication(client):
+ assert client.get('/api/v1/walkthroughs/definitions').status_code in (401, 422)
+ assert client.put(
+ '/api/v1/walkthroughs/definitions',
+ json={'definitions': [_definition()]},
+ ).status_code in (401, 422)
diff --git a/docs/EXTENSIONS.md b/docs/EXTENSIONS.md
index 1eb18c0c..bcdb957b 100644
--- a/docs/EXTENSIONS.md
+++ b/docs/EXTENSIONS.md
@@ -604,6 +604,74 @@ call `i18next.init()` or `changeLanguage()` from an extension: the panel owns
both, and calling them would reconfigure or switch the language for the whole
panel.
+## Guided walkthrough contributions
+
+Extensions can add safe, declarative guides to the panel's Walkthroughs dock.
+The panel namespaces every contributed id with the extension slug, filters the
+guide through the declared RBAC requirements, and removes it immediately when
+the extension is disabled. No extension JavaScript is needed for route,
+manual, or target-visible steps:
+
+```jsonc
+"contributions": {
+ "walkthroughs": [{
+ "id": "first-site",
+ "title": "Launch your first site",
+ "description": "Create the site and verify that it is online.",
+ "duration": "About 5 minutes",
+ "icon": "globe",
+ "tone": "green",
+ "secondary": true,
+ "permissions": [{ "feature": "applications", "level": "write" }],
+ "steps": [{
+ "id": "open-create",
+ "title": "Open the create flow",
+ "description": "Start from the extension's site list.",
+ "action": "Create site",
+ "path": "/my-extension/new",
+ "target": "myext-create-site",
+ "completion": { "type": "route", "path": "/my-extension/new" }
+ }, {
+ "id": "launch-site",
+ "title": "Launch the site",
+ "description": "Submit the reviewed configuration.",
+ "target": "myext-submit-site",
+ "completion": { "type": "signal", "signal": "myext.site-created" }
+ }]
+ }]
+}
+```
+
+`target` is the value of a stable `data-walkthrough` attribute, never a CSS
+selector. For the example above, the extension renders
+`data-walkthrough="myext-submit-site"`. This restriction prevents a guide from
+reaching into password fields or depending on fragile generated class names.
+
+Five completion modes are supported:
+
+| Type | Completes when |
+|---|---|
+| `manual` | The operator chooses **Done · next step**. |
+| `route` | The current path matches `completion.path` (or the step's `path`). |
+| `signal` | The UI emits the named signal after a successful operation. |
+| `check` | A host-owned, allowlisted status check returns success. |
+| `target` | The stable `data-walkthrough` target becomes visible. |
+
+Emit success signals through the SDK only after the operation succeeds:
+
+```js
+import { emitWalkthroughSignal } from 'serverkit-sdk';
+
+await createSite(values);
+emitWalkthroughSignal('myext.site-created', { siteId });
+```
+
+Definitions cannot contain JavaScript, commands, arbitrary API calls, or raw
+selectors. The same validator runs during extension install and when an admin
+publishes a custom guide from Walkthrough Studio. The editor schema lives at
+`docs/schemas/walkthrough.schema.json`; TypeScript definitions live at
+`frontend/src/plugins/sdk/walkthroughs.d.ts`.
+
### Checking your own extension
The panel's censuses take a `--root`, so run them against your repo instead of
@@ -678,6 +746,7 @@ readable *"needs panel SDK ^1.3.0 (this panel offers 1.2.0)"* at install time.
| SDK | Added |
|---|---|
+| `^1.5.0` | Declarative walkthrough authoring: manifest contributions, validation/normalization helpers, success-signal emission, and the walkthrough runtime hook. |
| `^1.3.0` | Localization: `useTranslation`, `Trans`, `t`, `useLocale`, `useLabel`, `useFormat` and the `formatDate`/`formatNumber`/`formatRelative` door. `i18next` and `react-i18next` became shared singletons, so an extension that **externalizes** them needs this SDK or newer. |
| `^1.2.0` | Layout/feedback primitives, the `ui/*` form kit, common hooks, format utils, and the cross-feature embeds (git repo-connect, backups `ProtectionPanel`). |
diff --git a/docs/schemas/walkthrough.schema.json b/docs/schemas/walkthrough.schema.json
new file mode 100644
index 00000000..91d8d56e
--- /dev/null
+++ b/docs/schemas/walkthrough.schema.json
@@ -0,0 +1,116 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://serverkit.ai/schemas/walkthrough.schema.json",
+ "title": "ServerKit Walkthrough",
+ "description": "A safe, declarative guided flow contributed by an extension or created in Walkthrough Studio.",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["id", "title", "description", "steps"],
+ "properties": {
+ "$schema": { "type": "string" },
+ "id": { "$ref": "#/$defs/id" },
+ "title": { "type": "string", "minLength": 1, "maxLength": 120 },
+ "title_key": { "type": "string", "minLength": 1, "maxLength": 120 },
+ "description": { "type": "string", "minLength": 1, "maxLength": 320 },
+ "description_key": { "type": "string", "minLength": 1, "maxLength": 120 },
+ "duration": { "type": "string", "minLength": 1, "maxLength": 80 },
+ "duration_key": { "type": "string", "minLength": 1, "maxLength": 120 },
+ "icon": { "type": "string", "minLength": 1, "maxLength": 120 },
+ "tone": { "type": "string", "minLength": 1, "maxLength": 120 },
+ "secondary": { "type": "boolean", "default": true },
+ "permissions": {
+ "type": "array",
+ "maxItems": 16,
+ "items": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["feature", "level"],
+ "properties": {
+ "feature": { "type": "string", "minLength": 1, "maxLength": 80 },
+ "level": { "enum": ["read", "write", "admin"] }
+ }
+ }
+ },
+ "steps": {
+ "type": "array",
+ "minItems": 1,
+ "maxItems": 32,
+ "items": { "$ref": "#/$defs/step" }
+ }
+ },
+ "$defs": {
+ "id": {
+ "type": "string",
+ "pattern": "^[a-z0-9][a-z0-9._-]{0,79}$"
+ },
+ "target": {
+ "type": "string",
+ "description": "The value of a data-walkthrough attribute. CSS selectors are not accepted.",
+ "pattern": "^[a-z0-9][a-z0-9._:-]{0,79}$"
+ },
+ "token": {
+ "type": "string",
+ "pattern": "^[a-z0-9][a-z0-9._:-]{0,119}$"
+ },
+ "completion": {
+ "oneOf": [
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["type"],
+ "properties": { "type": { "const": "manual" } }
+ },
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["type"],
+ "properties": {
+ "type": { "const": "route" },
+ "path": { "type": "string", "pattern": "^/", "maxLength": 500 }
+ }
+ },
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["type", "signal"],
+ "properties": {
+ "type": { "const": "signal" },
+ "signal": { "$ref": "#/$defs/token" }
+ }
+ },
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["type", "check"],
+ "properties": {
+ "type": { "const": "check" },
+ "check": { "$ref": "#/$defs/token" }
+ }
+ },
+ {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["type"],
+ "properties": { "type": { "const": "target" } }
+ }
+ ]
+ },
+ "step": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["id", "title", "description"],
+ "properties": {
+ "id": { "$ref": "#/$defs/id" },
+ "title": { "type": "string", "minLength": 1, "maxLength": 120 },
+ "title_key": { "type": "string", "minLength": 1, "maxLength": 120 },
+ "description": { "type": "string", "minLength": 1, "maxLength": 500 },
+ "description_key": { "type": "string", "minLength": 1, "maxLength": 120 },
+ "action": { "type": "string", "minLength": 1, "maxLength": 80 },
+ "action_key": { "type": "string", "minLength": 1, "maxLength": 120 },
+ "path": { "type": "string", "pattern": "^/", "maxLength": 500 },
+ "target": { "$ref": "#/$defs/target" },
+ "completion": { "$ref": "#/$defs/completion" }
+ }
+ }
+ }
+}
diff --git a/scripts/new-extension.mjs b/scripts/new-extension.mjs
index cd57fdb5..64767d48 100644
--- a/scripts/new-extension.mjs
+++ b/scripts/new-extension.mjs
@@ -25,6 +25,7 @@
import { promises as fs } from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';
+import { validateWalkthroughDefinition } from '../frontend/src/services/walkthroughRegistry.js';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const ROOT = path.resolve(__dirname, '..');
@@ -43,6 +44,7 @@ const REQUIRED_CONTRIB_KEYS = {
command_palette: ['label', 'path'],
widgets: ['slot', 'component'],
layouts: ['id', 'component'],
+ walkthroughs: ['id', 'title', 'description', 'steps'],
};
const KNOWN_CONTRIB_KINDS = new Set([...Object.keys(REQUIRED_CONTRIB_KEYS), 'page_titles', 'ai']);
@@ -133,6 +135,14 @@ function validateManifest(manifest) {
&& (typeof contrib.page_titles !== 'object' || Array.isArray(contrib.page_titles))) {
problems.push('contributions.page_titles must be an object of path -> title');
}
+ if (Array.isArray(contrib.walkthroughs)) {
+ contrib.walkthroughs.forEach((walkthrough, i) => {
+ for (const item of validateWalkthroughDefinition(walkthrough)) {
+ const suffix = item.path ? `.${item.path}` : '';
+ problems.push(`contributions.walkthroughs[${i}]${suffix}: ${item.message}`);
+ }
+ });
+ }
}
return { problems, warnings };