@guidelytech/guide-runtime

中文文档
0.18.0发布于 2026/11/09MITTypeScriptESM + CJS近 30 天下载 4983

Guidely browser runtime: selectors, positioning, overlays and step rendering

原始使用文档
文档目录7 节
  1. Selectors
  2. Host and theme
  3. Rendering
  4. Controller
  5. Widgets
  6. Sanitizer
  7. Authoring

@guidelytech/guide-runtime

Framework-free DOM engine used by the Guidely SDK and the dashboard editor: element resolution, Shadow-DOM host and theming, step renderers (floating-ui positioning), the guide controller, checklist / survey / resource-center widgets, an allowlist HTML sanitizer and the authoring picker.

pnpm add @guidelytech/guide-runtime
import { runGuide } from "@guidelytech/guide-runtime";

const controller = runGuide(publishedGuide, {
  theme: config.theme,
  ctx: () => targetingContext,
  onEvent: (e) => console.log(e.name, e.stepId),
  onNavigate: (url) => router.push(url),
});
controller.start();

Selectors

ExportDescription
resolveTarget(target | selectors, root?)Tries strategies in order (id, data-attr, aria, css, text, xpath); a strategy wins only when it matches exactly one visible element.
waitForTarget(target, { timeoutMs, signal, root, pollMs })MutationObserver + ≤250ms polling; rejects with TargetTimeoutError / AbortError. timeoutMs: 0 waits forever.
generateSelectors(el)Robust-first strategies for the picker: stable id (generated ids like :r1:, radix-…, long digit runs are skipped), data-testid/data-tour/data-*, aria-label, name/role, short unique CSS path (nth-of-type only when needed), text fallback for buttons/links/headings.
describeElement(el){ selectors, textSnapshot, rect, tag }.
textSnapshotOf(el), isVisible(el), isStableId(id), isGuidelyElement(el), querySelectorStrategy(strategy, root), normalizeText(text), urlMatches(pattern, url)Helpers.

Host and theme

ensureHost() appends a single <div id="guidely-root"> with an open shadow root containing all styles (:host{all:initial}) and a polite live region. createScope(theme, appearance) creates a themed container (--g-primary, --g-bg, --g-text, --g-radius, --g-font, --g-z, --g-overlay; data-theme="light|dark", data-anim). auto follows prefers-color-scheme; prefers-reduced-motion disables animations. resolveTheme, applyTheme, destroyHost, DEFAULT_THEME, HOST_ID, STYLES are also exported.

Rendering

renderStep({ scope, step, index, total, target, asModal, onButton, onClose, onOpen }) renders any step type and returns { el, card, destroy }:

  • modal — centered card, optional overlay, role="dialog" aria-modal, Tab focus trap.
  • tooltip / popover — anchored with floating-ui (offset, flip/autoPlacement, shift, arrow, autoUpdate), role="tooltip", aria-describedby set on the target.
  • spotlight — four-rect overlay with a cut-out around the target (target stays clickable) + ring + anchored card.
  • hotspot — pulsing dot at the target's corner, opens the card on click or hover.
  • banner — fixed top/bottom bar, role="status".
  • slideout — corner card. custom — sanitized customHtml only; elements with data-g-action="next|back|dismiss|complete|skip" act as buttons.

Chrome: close button (Escape when showClose), image, title, sanitized body, progress ("2 of 4"), buttons with variants, focus moved into the card and restored on close, screen-reader announcements, cards clamped to 100vw - 32px, ≥40px touch targets.

anchor(reference, floating, options) and trackRect(el, cb) expose the positioning primitives.

Controller

runGuide(guide, options): GuideController — options: theme, ctx, onEvent, onNavigate, onAction (start_guide / event / open_resource_center), onError, onEnd, eventBus (for advanceOn: "event"), startAtStep, currentUrl, container, doc.

Controller: start(), next(), back(), goTo(stepId), dismiss(), complete(), skip(), resume() (re-check a step waiting for its URL), destroy(), getState().

Handles advanceOn (button, element_click, element_visible, event, delay, any), branches (evaluateRules(branch.when, ctx) when leaving a step), step-level targeting, multi-page steps (step.url), target waits with skip / show_as_modal / end_guide / wait fallbacks, and emits guide_viewed, guide_started, step_viewed, step_completed, guide_completed, guide_skipped, guide_dismissed. Rendering is wrapped in try/catch and reported via onError.

Widgets

  • renderChecklist({ scope, config, progress, open, onTaskClick, onDismiss, onOpen, onClose }) → { open, close, toggle, isOpen, setProgress, destroy }; isChecklistComplete(config, progress).
  • renderSurvey({ scope, config, title, onSubmit, onDismiss, onChange }) → { getAnswers, showThankYou, destroy }; isQuestionVisible(question, answers) evaluates showWhen.
  • renderResourceCenter({ scope, config, guides, search, onStartGuide, onOpenChecklist, onArticleView, onOpen, onClose, hideLauncher }) → { open, close, toggle, isOpen, destroy }.

Sanitizer

sanitizeHtml(html), sanitizeToFragment(html), setSanitizedHtml(el, html) — allowlist of p br strong b em i u a ul ol li img h1-h4 code pre blockquote span div hr button, attributes href src alt title target rel class (+ data-g-action/data-g-value), drops script/style/iframe/object/embed/form/input, on* handlers, javascript:/data: URLs (except data:image/* on img), forces rel="noopener noreferrer" on target="_blank".

Authoring

  • startAuthoring({ onPick, onExit, dashboardOrigin, message }) → { setStatus, setPicking, stop } — toolbar, hover outline, capture-phase click-to-pick calling onPick({ selectors, textSnapshot, rect, url, element }).
  • previewStep(step, theme, { appearance, onEnd }) → { controller, destroy }.
  • highlightSelectors(selectors, { durationMs }) → { counts, resolved, destroy }.

版本与发布记录

@guidelytech/guide-runtime 共发布 21 个版本,首次发布于 2026/10/18;过去 12 个月发布了 21 个版本。

版本发布日期距今
0.18.0latest2026/11/098 天前
0.17.02026/11/098 天前
0.16.02026/11/0413 天前
0.15.02026/10/3018 天前
0.14.02026/10/2820 天前
0.13.02026/10/2820 天前

关于 @guidelytech/guide-runtime 的常见问题

@guidelytech/guide-runtime 是什么?

Guidely browser runtime: selectors, positioning, overlays and step rendering

如何安装 @guidelytech/guide-runtime?

在项目目录运行 npm install @guidelytech/guide-runtime,或使用 pnpm add / yarn add / bun add。

@guidelytech/guide-runtime 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@guidelytech/guide-runtime 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@guidelytech/guide-runtime 可以商用吗?

@guidelytech/guide-runtime 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@guidelytech/guide-runtime 的下载量有多少?

根据 npm 官方下载统计,@guidelytech/guide-runtime 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,983 次,日均约 166 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@guidelytech/guide-runtime 还在维护吗?

最新版本 0.18.0 发布于 2026/11/09(8 天前);至今共发布 21 个版本,其中过去 12 个月发布了 21 个;首次发布于 2026/10/18。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。