@lincyaw/addon-guide 0.0.0-stage → 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @lincyaw/addon-guide
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Guidance: a simulated cursor, spotlights and hints that follow the steps.
+
+Part of [Presmium](https://github.com/Lincyaw/presmium), which compiles canonical lecture.json teaching documents into web pages, slides, Jupyter notebooks and narrated playback.
+
+## Install
+
+```sh
+pnpm add -D @lincyaw/addon-guide
+```
+
+Add this package to `metadata.plugins` in the document's `lecture.json`.
+
+It is a Presmium plugin: its components work on the web page and in the slides. It needs `@lincyaw/cli` and the renderers in the same project, and declares the Presmium packages it shares with them as peer dependencies (Presmium 1.x).
+
+## What it provides
+
+- Cursor, spotlight and hint components declared through versioned definitions.
+- Structured narration cues can target stable blocks and code lines through the shared host services.
+
+## Documentation
+
+- [Author guide](https://github.com/Lincyaw/presmium/blob/main/site/guide/locales/en/lecture.json) (Chinese: `site/guide/lecture.json`)
+- [Document contract](https://github.com/Lincyaw/presmium/blob/main/.agents/skills/presmium-author/references/document.md): normalized entities, parameters, states and shared validation
+
+## License
+
+Apache-2.0

package/components/PmCursor.tsx

@@ -0,0 +1,7 @@
+import CursorPath from '../src/client/CursorPath.tsx'
+import { planCursorPath } from '../src/domain/index.ts'
+import type { Waypoint } from '../src/domain/index.ts'
+export default function PmCursor({ path }: { path: Waypoint[] }) {
+  const plan = planCursorPath(path ?? [])
+  return <CursorPath key={JSON.stringify(plan)} plan={plan} />
+}

package/components/PmHint.css

@@ -0,0 +1,20 @@
+[data-pm-hint='inline'] {
+  outline: var(--pm-size-stroke) solid var(--pm-color-accent);
+  outline-offset: var(--pm-size-rule);
+  animation: pm-hint-ring var(--pm-duration-guide-ring) ease-out infinite;
+}
+@keyframes pm-hint-ring {
+  from {
+    outline-offset: var(--pm-size-stroke);
+    outline-color: var(--pm-color-accent);
+  }
+  to {
+    outline-offset: var(--pm-guide-ring-spread);
+    outline-color: transparent;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-pm-hint='inline'] {
+    animation: none;
+  }
+}

package/components/PmHint.tsx

@@ -0,0 +1,19 @@
+import CueNote from '../src/client/CueNote.tsx'
+import { requestHint, useCue } from '../src/client/index.ts'
+import type { CueProps } from '../src/client/cue.ts'
+import './PmHint.css'
+export default function PmHint(props: CueProps) {
+  const { anchor, look, note } = useCue(props, 'data-pm-hint', requestHint)
+  return (
+    <>
+      <CueNote title={props.title} text={props.text} state={note} />
+      <span
+        ref={anchor}
+        className="pm-hint"
+        hidden
+        data-target={props.target}
+        data-look={look ?? 'off'}
+      />
+    </>
+  )
+}

package/components/PmSpotlight.css

@@ -0,0 +1,5 @@
+[data-pm-spotlight='inline'] {
+  outline: var(--pm-size-rule) solid var(--pm-color-warn);
+  outline-offset: var(--pm-space-1);
+  border-radius: var(--pm-radius-chip);
+}

package/components/PmSpotlight.tsx

@@ -0,0 +1,23 @@
+import CueNote from '../src/client/CueNote.tsx'
+import { requestSpotlight, useCue } from '../src/client/index.ts'
+import type { CueProps } from '../src/client/cue.ts'
+import './PmSpotlight.css'
+export default function PmSpotlight(props: CueProps) {
+  const { anchor, look, note } = useCue(
+    props,
+    'data-pm-spotlight',
+    requestSpotlight,
+  )
+  return (
+    <>
+      <CueNote title={props.title} text={props.text} state={note} />
+      <span
+        ref={anchor}
+        className="pm-spotlight"
+        hidden
+        data-target={props.target}
+        data-look={look ?? 'off'}
+      />
+    </>
+  )
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@lincyaw/addon-guide",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.1",
+  "description": "Presmium plugin: guidance cues: a simulated cursor, spotlights and hints",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lincyaw/presmium.git",
+    "directory": "packages/addon-guide"
+  },
+  "homepage": "https://github.com/Lincyaw/presmium/tree/main/packages/addon-guide#readme",
+  "bugs": "https://github.com/Lincyaw/presmium/issues",
+  "keywords": [
+    "presmium"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./domain": "./src/domain/index.ts",
+    "./client": "./src/client/index.ts",
+    "./presmium": "./src/node/presmium.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "components",
+    "src"
+  ],
+  "dependencies": {
+    "driver.js": "^1.9.0"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "@lincyaw/host": "^1.0.0-rc.1",
+    "@lincyaw/kernel": "^1.0.0-rc.1"
+  },
+  "devDependencies": {
+    "react": "18.3.1",
+    "@types/react": "18.3.28",
+    "@lincyaw/host": "1.0.0-rc.1",
+    "@lincyaw/viewer": "1.0.0-rc.1",
+    "@lincyaw/kernel": "1.0.0-rc.1"
+  },
+  "presmium": {
+    "preview": {
+      "restartable": true
+    }
+  }
 }

package/src/client/CueNote.tsx

@@ -0,0 +1,27 @@
+import { useMessages } from '@lincyaw/host'
+import { GUIDE_MESSAGES } from '../domain/index.ts'
+export default function CueNote({
+  title,
+  text,
+  state,
+}: {
+  title?: string
+  text?: string
+  state?: 'shown' | 'hidden'
+}) {
+  const t = useMessages(GUIDE_MESSAGES)
+  return state && (title || text) ? (
+    <div
+      className="pm-cue-note"
+      data-state={state}
+      style={state === 'shown' ? undefined : { visibility: 'hidden' }}
+      aria-hidden={state === 'shown' ? undefined : true}
+    >
+      <p>
+        {title && <strong>{title}</strong>}
+        {title && text ? t.separator : ''}
+        {text}
+      </p>
+    </div>
+  ) : null
+}

package/src/client/CursorPath.css

@@ -0,0 +1,58 @@
+.pm-cursor {
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: 0;
+  height: 0;
+  z-index: 20;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity var(--pm-duration);
+}
+.pm-cursor:not([data-waypoint='-1']) {
+  opacity: 1;
+}
+.pm-cursor__arrow {
+  position: absolute;
+  left: calc(-1 * var(--pm-size-stroke));
+  top: calc(-1 * var(--pm-size-stroke));
+  /* The page's base styles cap an svg at the width of its box, which is 0 here. */
+  max-width: none;
+  width: var(--pm-size-pointer-arrow);
+  height: var(--pm-size-pointer-ring);
+  fill: var(--pm-color-pointer-fill);
+  stroke: var(--pm-color-pointer-stroke);
+  stroke-width: 1.5;
+  stroke-linejoin: round;
+  filter: drop-shadow(var(--pm-shadow-pointer));
+}
+.pm-cursor__ring {
+  position: absolute;
+  left: calc(-0.5 * var(--pm-size-pointer-ring));
+  top: calc(-0.5 * var(--pm-size-pointer-ring));
+  width: var(--pm-size-pointer-ring);
+  height: var(--pm-size-pointer-ring);
+  border-radius: 50%;
+  border: var(--pm-size-rule) solid var(--pm-color-accent);
+  opacity: 0;
+}
+.pm-cursor[data-action='hover'] .pm-cursor__ring {
+  opacity: 0.35;
+}
+.pm-cursor[data-action='click'] .pm-cursor__ring {
+  opacity: calc(0.7 * var(--pm-cursor-press, 1));
+  transform: scale(calc(2.2 - 1.2 * var(--pm-cursor-press, 1)));
+}
+.pm-cursor[data-motion='reduced'] {
+  transition: none;
+}
+
+
+[data-pm-cursor='hover'] {
+  outline: var(--pm-size-stroke) dashed var(--pm-color-accent);
+  outline-offset: var(--pm-size-rule);
+}
+[data-pm-cursor='click'] {
+  outline: var(--pm-size-stroke) solid var(--pm-color-accent);
+  outline-offset: var(--pm-size-rule);
+}

package/src/client/CursorPath.tsx

@@ -0,0 +1,85 @@
+import {
+  useStep,
+  usePrefersReducedMotion,
+  useStepScope,
+  useStepTime,
+} from '@lincyaw/host'
+import { useLayoutEffect, useRef, useState } from 'react'
+import type { CSSProperties } from 'react'
+import type { PlannedWaypoint } from '../domain/index.ts'
+import { centerIn } from './geometry.ts'
+import type { Point } from './geometry.ts'
+import { resolveTarget, useTargetMark } from './targets.ts'
+import './CursorPath.css'
+export default function CursorPath({ plan }: { plan: PlannedWaypoint[] }) {
+  const scope = useStepScope(),
+    hostStep = useStep(),
+    stepTime = useStepTime({ until: 850 }),
+    reduced = usePrefersReducedMotion()
+  const index =
+      plan.filter((point) => scope.localStepAt(hostStep) >= point.at).length - 1,
+    point = plan[index]
+  const time = point && scope.localStepAt(hostStep) === point.at ? stepTime : Infinity
+  const cursor = useRef<HTMLDivElement>(null)
+  const [points, setPoints] = useState<{ from?: Point; to?: Point }>({})
+  useLayoutEffect(() => {
+    const measure = () => {
+      const el = cursor.current,
+        frame = el?.offsetParent
+      if (!(frame instanceof HTMLElement)) return
+      const at = (i: number) => {
+        const target = resolveTarget(el ?? undefined, plan[i]?.to)
+        return target ? centerIn(target, frame) : undefined
+      }
+      const to = at(Math.max(index, 0))
+      setPoints({ to, from: index > 0 ? (at(index - 1) ?? to) : to })
+    }
+    const observer = new ResizeObserver(measure)
+    if (cursor.current?.parentElement)
+      observer.observe(cursor.current.parentElement)
+    for (const waypoint of plan) {
+      const target = resolveTarget(cursor.current ?? undefined, waypoint.to)
+      if (target) observer.observe(target)
+    }
+    measure()
+    return () => observer.disconnect()
+  }, [index, plan])
+  useTargetMark(
+    cursor,
+    point?.to ?? '',
+    'data-pm-cursor',
+    point?.action === 'move' ? undefined : point?.action,
+  )
+  const k = 1 - (1 - Math.min(1, time / 500)) ** 3
+  const position =
+    points.from && points.to
+      ? {
+          x: points.from.x + (points.to.x - points.from.x) * k,
+          y: points.from.y + (points.to.y - points.from.y) * k,
+        }
+      : points.to
+  const press = Math.min(1, Math.max(0, (time - 450) / 400))
+  return (
+    <div
+      ref={cursor}
+      className="pm-cursor"
+      aria-hidden="true"
+      data-waypoint={index}
+      data-action={point?.action ?? 'none'}
+      data-motion={reduced ? 'reduced' : 'full'}
+      style={
+        {
+          ...(position
+            ? { transform: `translate(${position.x}px, ${position.y}px)` }
+            : {}),
+          '--pm-cursor-press': press,
+        } as CSSProperties
+      }
+    >
+      <span className="pm-cursor__ring" />
+      <svg className="pm-cursor__arrow" viewBox="-2 -2 20 26">
+        <path d="M0 0V18L5 13.5L8.5 21L11.5 19.5L8 12H14.5Z" />
+      </svg>
+    </div>
+  )
+}

package/src/client/cue.ts

@@ -0,0 +1,28 @@
+import { usePrefersReducedMotion, useStep, useStepScope, useStepState, useViewRole } from '@lincyaw/host'
+import { useLayoutEffect, useRef } from 'react'
+import { cueRange, cueSteps } from '../domain/index.ts'
+import { useIsOnStage } from './stage.ts'
+import { resolveTarget, useTargetMark } from './targets.ts'
+export interface CueProps { target: string, at?: number | string, until?: number | string, title?: string, text?: string }
+export interface CueRequest { element: HTMLElement, title?: string, text?: string, animate: boolean }
+export type ShowCue = (owner: object, request: CueRequest | undefined) => void
+export function sameCue(a: CueRequest | undefined, b: CueRequest | undefined): boolean { return !!a && !!b && a.element === b.element && a.title === b.title && a.text === b.text && a.animate === b.animate }
+export type CueLook = 'stage' | 'inline'
+export function useCue(props: CueProps, attribute: string, show: ShowCue) {
+  const range = cueRange(props.at, props.until), state = useStepState(range), scope = useStepScope(), onStage = useIsOnStage(), reduced = usePrefersReducedMotion(), role = useViewRole(), step = useStep()
+  const anchor = useRef<HTMLSpanElement>(null), owner = useRef({})
+  const look: CueLook | undefined = state.active ? onStage ? 'stage' : 'inline' : undefined
+  const note = role !== 'reader' ? undefined : state.active || step === Infinity ? 'shown' as const : 'hidden' as const
+  useTargetMark(anchor, props.target, attribute, look)
+  useLayoutEffect(() => {
+    const element = look === 'stage' ? resolveTarget(anchor.current ?? undefined, props.target) : undefined
+    const request = element ? { element, title: props.title, text: props.text, animate: !reduced } : undefined
+    show(owner.current, request)
+    let frame = 0, still = 0, box = ''
+    const track = () => { frame = 0; if (!request) return; const rect = request.element.getBoundingClientRect(); const next = `${rect.x} ${rect.y} ${rect.width} ${rect.height}`; if (next !== box) { show(owner.current, request); box = next; still = 0 } else still++; if (still < 30) frame = requestAnimationFrame(track) }
+    const wake = () => { still = 0; if (request && !frame) frame = requestAnimationFrame(track) }
+    wake(); window.addEventListener('resize', wake); document.addEventListener('transitionrun', wake, true); document.addEventListener('transitionend', wake, true)
+    return () => { cancelAnimationFrame(frame); window.removeEventListener('resize', wake); document.removeEventListener('transitionrun', wake, true); document.removeEventListener('transitionend', wake, true); show(owner.current, undefined) }
+  }, [look, reduced, props.target, props.title, props.text, show])
+  return { anchor, look, note, steps: cueSteps(range).map(scope.step) }
+}

package/src/client/env.d.ts

@@ -0,0 +1 @@
+declare module '*.css'

package/src/client/geometry.ts

@@ -0,0 +1,15 @@
+export interface Point {
+  x: number
+  y: number
+}
+
+export function centerIn(target: Element, frame: HTMLElement): Point | undefined {
+  const box = frame.getBoundingClientRect()
+  if (!frame.offsetWidth || !box.width) return undefined
+  const scale = box.width / frame.offsetWidth
+  const rect = target.getBoundingClientRect()
+  return {
+    x: (rect.left + rect.width / 2 - box.left) / scale - frame.clientLeft + frame.scrollLeft,
+    y: (rect.top + rect.height / 2 - box.top) / scale - frame.clientTop + frame.scrollTop,
+  }
+}

package/src/client/hints.css

@@ -0,0 +1,7 @@
+.pm-hint-beacon {
+  --driver-hint-size: var(--pm-size-pointer-beacon);
+}
+body .driver-hint.pm-hint-beacon,
+body .driver-popover.pm-hint-popover {
+  z-index: calc(var(--pm-cue-z, 1) + 1);
+}

package/src/client/hints.ts

@@ -0,0 +1,40 @@
+import { hints } from 'driver.js/hints'
+import type { DriverHint, Hints } from 'driver.js/hints'
+import 'driver.js/dist/hints.css'
+import './hints.css'
+import { sameCue } from './cue.ts'
+import type { CueRequest } from './cue.ts'
+
+const requests = new Map<object, CueRequest>()
+let beacons: Hints | undefined
+
+function beacon({ element, title, text, animate }: CueRequest): DriverHint {
+  return {
+    element,
+    beacon: { animate, className: 'pm-hint-beacon' },
+    popover: title || text ? { title, description: text, showButton: false } : undefined,
+  }
+}
+
+function release(event: FocusEvent) {
+  const target = event.target
+  if (target instanceof HTMLElement && target.closest('.pm-hint-beacon, .pm-hint-popover')) target.blur()
+}
+
+function create(): Hints {
+  document.addEventListener('focusin', release)
+  return hints({ popoverClass: 'pm-hint-popover' })
+}
+
+export function requestHint(owner: object, request: CueRequest | undefined): void {
+  if (sameCue(requests.get(owner), request)) {
+    beacons?.refresh()
+    return
+  }
+  if (request) requests.set(owner, request)
+  else requests.delete(owner)
+  beacons ??= create()
+  beacons.hide()
+  beacons.setHints([...requests.values()].map(beacon))
+  if (requests.size) beacons.show()
+}

package/src/client/index.ts

@@ -0,0 +1,9 @@
+export { useCue } from './cue.ts'
+export type { CueLook, CueProps, CueRequest, ShowCue } from './cue.ts'
+export { centerIn } from './geometry.ts'
+export type { Point } from './geometry.ts'
+export { requestHint } from './hints.ts'
+export { requestSpotlight } from './spotlight.ts'
+export { STAGE_PROBE, useIsOnStage } from './stage.ts'
+export type { StageProbe } from './stage.ts'
+export { resolveTarget, useTargetMark } from './targets.ts'

package/src/client/operation-cues.ts

@@ -0,0 +1,122 @@
+import { blockElement, codeLinesBox } from '@lincyaw/host'
+import type { Navigation } from '@lincyaw/host'
+import type { CueRequest, ShowCue } from './cue.ts'
+import { requestHint } from './hints.ts'
+import { requestSpotlight } from './spotlight.ts'
+
+export interface OperationCue {
+  block?: string
+  selector?: string
+  lines?: string
+  span?: number
+  title?: string
+  text?: string
+}
+
+const REFRESH_MS = 250
+
+function firstVisible(elements: Iterable<HTMLElement>): HTMLElement | undefined {
+  for (const el of elements) {
+    if (!el.closest('[inert], .pm-hidden') && el.getClientRects().length > 0) return el
+  }
+  return undefined
+}
+
+function sameTarget(a: OperationCue, b: OperationCue): boolean {
+  return a.block === b.block && a.selector === b.selector && a.lines === b.lines
+}
+
+export function toOperationCue(data: Record<string, unknown>): OperationCue | undefined {
+  const text = (value: unknown) => (typeof value === 'string' && value ? value : undefined)
+  const cue: OperationCue = {
+    block: text(data.block),
+    selector: text(data.selector),
+    lines: typeof data.lines === 'number' ? String(data.lines) : text(data.lines),
+    span: typeof data.span === 'number' && data.span > 0 ? data.span : undefined,
+    title: text(data.title),
+    text: text(data.text),
+  }
+  return cue.block || cue.selector ? cue : undefined
+}
+
+export class OperationCues {
+  private current?: { cue: OperationCue, slide: number, step: number }
+  private readonly owner = {}
+  private box?: HTMLElement
+  private timer?: ReturnType<typeof setInterval>
+  private navigation?: Navigation
+  private unwatch?: () => void
+  private readonly show: ShowCue
+
+  constructor(show: ShowCue) {
+    this.show = show
+  }
+
+  bind(navigation: Navigation | undefined): void {
+    this.unwatch?.()
+    this.navigation = navigation
+    this.unwatch = navigation && navigation.position.subscribe(() => {
+      const { slide, step } = navigation.position.getSnapshot()
+      const now = this.current
+      if (now && (slide !== now.slide || step < now.step || step > now.step + (now.cue.span ?? 0))) this.hide()
+    })
+  }
+
+  unbind(): void {
+    this.hide()
+    this.unwatch?.()
+    this.unwatch = undefined
+    this.navigation = undefined
+  }
+
+  get shown(): OperationCue | undefined {
+    return this.current?.cue
+  }
+
+  apply(data: Record<string, unknown>, animate = true): void {
+    const cue = toOperationCue(data)
+    if (!cue) return this.hide()
+    const position = this.navigation?.position.getSnapshot() ?? { slide: 0, step: 0 }
+    this.current = { cue, slide: position.slide, step: position.step }
+    this.draw(animate)
+    clearInterval(this.timer)
+    this.timer = setInterval(() => this.draw(animate), REFRESH_MS)
+  }
+
+  isShowing(data: Record<string, unknown>): boolean {
+    const cue = toOperationCue(data)
+    return Boolean(cue && this.current && sameTarget(cue, this.current.cue))
+  }
+
+  hide(): void {
+    clearInterval(this.timer)
+    this.timer = undefined
+    this.current = undefined
+    this.box?.remove()
+    this.box = undefined
+    this.show(this.owner, undefined)
+  }
+
+  private draw(animate: boolean): void {
+    const cue = this.current?.cue
+    if (!cue) return
+    let element: HTMLElement | undefined
+    try {
+      element = cue.block ? blockElement(cue.block) : firstVisible(document.querySelectorAll<HTMLElement>(cue.selector!))
+    } catch {
+      element = undefined
+    }
+    const lines = element && cue.lines ? codeLinesBox(element, cue.lines) : undefined
+    if (lines) {
+      this.box ??= Object.assign(document.createElement('div'), { className: 'pm-cue-lines' })
+      Object.assign(this.box.style, { position: 'fixed', pointerEvents: 'none', left: `${lines.left}px`, top: `${lines.top}px`, width: `${lines.width}px`, height: `${lines.height}px` })
+      if (!this.box.isConnected) document.body.append(this.box)
+      element = this.box
+    }
+    const request: CueRequest | undefined = element && { element, title: cue.title, text: cue.text, animate }
+    this.show(this.owner, request)
+  }
+}
+
+export const spotlightCues = new OperationCues(requestSpotlight)
+export const hintCues = new OperationCues(requestHint)

package/src/client/plugin.ts

@@ -0,0 +1,40 @@
+import { NAVIGATION, OPERATIONS } from '@lincyaw/host'
+import type { PluginDefinition, Unsubscribe } from '@lincyaw/kernel'
+import { version } from '../../package.json'
+import { GUIDE_ID } from '../domain/index.ts'
+import { hintCues, spotlightCues } from './operation-cues.ts'
+
+let unregister: Unsubscribe[] = []
+
+const plugin: PluginDefinition = {
+  // dispose releases everything setup made; a paused preview starts the same definition again.
+  restartable: true,
+  manifest: {
+    id: GUIDE_ID,
+    name: { 'zh-CN': '导览提示', en: 'Guidance Cues' },
+    version,
+    kernel: '^1.0.0',
+    requires: [{ token: OPERATIONS, optional: true }, { token: NAVIGATION, optional: true }],
+  },
+  setup(ctx) {
+    const operations = ctx.tryGet(OPERATIONS)
+    const navigation = ctx.tryGet(NAVIGATION)
+    unregister = [spotlightCues, hintCues].map((cues, i) => {
+      cues.bind(navigation)
+      const off = operations?.onReplay(i === 0 ? 'spot' : 'hint', {
+        apply: (data, seeking) => cues.apply(data, !seeking),
+        clear: () => cues.hide(),
+      })
+      return () => {
+        off?.()
+        cues.unbind()
+      }
+    })
+  },
+  dispose() {
+    unregister.forEach(off => off())
+    unregister = []
+  },
+}
+
+export default plugin

package/src/client/spotlight.css

@@ -0,0 +1,32 @@
+.driver-overlay {
+  z-index: var(--pm-cue-z, 1) !important;
+}
+.driver-overlay,
+.driver-overlay * {
+  pointer-events: none !important;
+}
+body .driver-popover.pm-spotlight-popover {
+  z-index: calc(var(--pm-cue-z, 1) + 1);
+}
+
+body .driver-popover:is(.pm-spotlight-popover, .pm-hint-popover) {
+  border: var(--pm-size-hairline) solid var(--pm-color-line);
+  border-radius: var(--pm-radius-card);
+  background: var(--pm-color-surface);
+  color: var(--pm-color-ink);
+  box-shadow: var(--pm-shadow-float);
+  font-family: var(--pm-font-sans);
+}
+body .driver-popover:is(.pm-spotlight-popover, .pm-hint-popover) .driver-popover-title {
+  font-family: var(--pm-font-serif);
+  font-weight: 600;
+}
+body .driver-popover:is(.pm-spotlight-popover, .pm-hint-popover) .driver-popover-description {
+  color: var(--pm-color-ink);
+}
+body .driver-popover:is(.pm-spotlight-popover, .pm-hint-popover) .driver-popover-arrow {
+  border-color: var(--pm-color-surface);
+}
+body .driver-popover:is(.pm-spotlight-popover, .pm-hint-popover) .driver-popover-close-btn {
+  color: var(--pm-color-muted);
+}

package/src/client/spotlight.ts

@@ -0,0 +1,64 @@
+import { driver } from 'driver.js'
+import type { Config, Driver } from 'driver.js'
+import 'driver.js/dist/driver.css'
+import './spotlight.css'
+import { sameCue } from './cue.ts'
+import type { CueRequest } from './cue.ts'
+
+const requests = new Map<object, CueRequest>()
+let current: { driver: Driver; animate: boolean } | undefined
+let lit: { element: HTMLElement; tabindex: boolean } | undefined
+
+function config(animate: boolean): Config {
+  return {
+    animate,
+    allowClose: false,
+    allowKeyboardControl: false,
+    overlayClickBehavior: 'none',
+    showButtons: [],
+    smoothScroll: false,
+    stagePadding: 8,
+    stageRadius: 8,
+    popoverClass: 'pm-spotlight-popover',
+    onHighlightStarted: () => document.body.classList.remove('driver-active'),
+  }
+}
+
+const FOCUSABLE = 'a[href], button, input, select, textarea, [tabindex], [contenteditable]'
+
+function light(element: HTMLElement | undefined): void {
+  if (lit?.element === element) return
+  if (lit?.tabindex) lit.element.removeAttribute('tabindex')
+  lit = element && { element, tabindex: !element.matches(FOCUSABLE) }
+  if (lit?.tabindex) element!.setAttribute('tabindex', '-1')
+}
+
+function focusLit(event: KeyboardEvent): void {
+  if (event.key !== 'Tab' || event.altKey || event.ctrlKey || event.metaKey || !lit || lit.element.contains(document.activeElement)) return
+  event.preventDefault()
+  event.stopImmediatePropagation()
+  lit.element.focus({ preventScroll: true })
+}
+
+export function requestSpotlight(owner: object, request: CueRequest | undefined): void {
+  if (sameCue(requests.get(owner), request)) {
+    current?.driver.refresh()
+    return
+  }
+  requests.delete(owner)
+  if (request) requests.set(owner, request)
+  const shown = [...requests.values()].at(-1)
+  light(shown?.element)
+  if (current && current.animate !== shown?.animate) {
+    current.driver.destroy()
+    current = undefined
+    window.removeEventListener('keydown', focusLit, true)
+  }
+  if (!shown) return
+  if (!current) {
+    current = { driver: driver(config(shown.animate)), animate: shown.animate }
+    window.addEventListener('keydown', focusLit, true)
+  }
+  const { element, title, text } = shown
+  current.driver.highlight({ element, popover: title || text ? { title, description: text } : undefined })
+}

package/src/client/stage.ts

@@ -0,0 +1,5 @@
+import { useViewRole } from '@lincyaw/host'
+import { createContext, useContext } from 'react'
+export type StageProbe = () => boolean
+export const STAGE_PROBE = createContext<StageProbe | undefined>(undefined)
+export function useIsOnStage(): boolean { const probe = useContext(STAGE_PROBE); const role = useViewRole(); return probe ? probe() : role === 'audience' }

package/src/client/targets.ts

@@ -0,0 +1,25 @@
+import { useLayoutEffect } from 'react'
+import type { RefObject } from 'react'
+
+export function resolveTarget(from: Element | undefined, selector: string | undefined): HTMLElement | undefined {
+  if (!from || !selector) return undefined
+  try {
+    for (let scope = from.parentElement; scope; scope = scope.parentElement) {
+      const found = scope.querySelector<HTMLElement>(selector)
+      if (found) return found
+    }
+  } catch (error) {
+    console.warn(`[presmium] invalid cue target "${selector}"`, error)
+  }
+  return undefined
+}
+
+export function useTargetMark(anchor: RefObject<Element | null | undefined>, selector: string | (() => string | undefined), attribute: string, value: string | undefined | (() => string | undefined)): void {
+  const targetSelector = typeof selector === 'function' ? selector() : selector
+  const current = typeof value === 'function' ? value() : value
+  useLayoutEffect(() => {
+    const marked = current === undefined ? undefined : resolveTarget(anchor.current ?? undefined, targetSelector)
+    if (marked && current !== undefined) marked.setAttribute(attribute, current)
+    return () => marked?.removeAttribute(attribute)
+  }, [anchor, targetSelector, attribute, current])
+}

package/src/client/viewer.ts

@@ -0,0 +1,23 @@
+import { blockAt, OPERATIONS, presmiumService } from '@lincyaw/host'
+import type { ViewerPluginContext } from '@lincyaw/viewer'
+import type { OperationCues } from './operation-cues.ts'
+import { hintCues, spotlightCues } from './operation-cues.ts'
+
+let pointer: { x: number, y: number } | undefined
+
+function toggle(type: 'spot' | 'hint', cues: OperationCues): boolean {
+  const block = pointer && blockAt(pointer.x, pointer.y)?.key
+  if (!block) return false
+  const data = cues.isShowing({ block }) ? {} : { block }
+  cues.apply(data)
+  presmiumService(OPERATIONS)?.report({ type, data })
+  return true
+}
+
+export default function guideViewerPlugin({ registerAction }: ViewerPluginContext): void {
+  window.addEventListener('pointermove', (event) => {
+    pointer = { x: event.clientX, y: event.clientY }
+  }, { passive: true })
+  registerAction({ id: 'presmium.guide.spot', keys: ['s'], run: () => toggle('spot', spotlightCues) })
+  registerAction({ id: 'presmium.guide.hint', keys: ['h'], run: () => toggle('hint', hintCues) })
+}

package/src/domain/cues.ts

@@ -0,0 +1,54 @@
+import type { StepRange } from '@lincyaw/kernel/contracts'
+
+export const GUIDE_ID = 'presmium.guide'
+
+export type CueTarget = string
+
+export type CursorAction = 'move' | 'hover' | 'click'
+
+export interface Waypoint {
+  to: CueTarget
+  action?: CursorAction
+  at?: number | string
+}
+
+export interface PlannedWaypoint {
+  to: CueTarget
+  action: CursorAction
+  at: number
+}
+
+const ACTIONS: readonly string[] = ['move', 'hover', 'click']
+
+function step(value: unknown): number | undefined {
+  const n = typeof value === 'string' && value.trim() !== '' ? Number(value) : value
+  return typeof n === 'number' && Number.isInteger(n) && n >= 0 ? n : undefined
+}
+
+export function planCursorPath(path: readonly Waypoint[]): PlannedWaypoint[] {
+  const planned: PlannedWaypoint[] = []
+  for (const point of path) {
+    const previous = planned.at(-1)?.at ?? -1
+    const at = Math.max(step(point.at) ?? previous + 1, previous, 0)
+    const action = point.action && ACTIONS.includes(point.action) ? point.action : 'move'
+    planned.push({ to: point.to, action, at })
+  }
+  return planned
+}
+
+export function parseCursorPath(body: string): Waypoint[] {
+  return body.split('\n').map(line => line.trim()).filter(Boolean).map((line) => {
+    const [first = '', ...rest] = line.split(/\s+/)
+    return rest.length > 0 && ACTIONS.includes(first) ? { to: rest.join(' '), action: first as CursorAction } : { to: line }
+  })
+}
+
+export function cueRange(at?: number | string, until?: number | string): StepRange {
+  const from = step(at) ?? 0
+  const to = step(until)
+  return to !== undefined && to > from ? { from, to } : { from }
+}
+
+export function cueSteps(range: StepRange): number[] {
+  return range.from > 0 ? [range.from] : []
+}

package/src/domain/index.ts

@@ -0,0 +1,4 @@
+export { cueRange, cueSteps, GUIDE_ID, parseCursorPath, planCursorPath } from './cues.ts'
+export type { CueTarget, CursorAction, PlannedWaypoint, Waypoint } from './cues.ts'
+export { GUIDE_MESSAGES } from './messages.ts'
+export type { GuideMessages } from './messages.ts'

package/src/domain/messages.ts

@@ -0,0 +1,10 @@
+import type { Locale } from '@lincyaw/kernel/contracts'
+
+export interface GuideMessages {
+  separator: string
+}
+
+export const GUIDE_MESSAGES: Record<Locale, GuideMessages> = {
+  'zh-CN': { separator: '：' },
+  'en': { separator: ': ' },
+}

package/src/node/presmium.ts

@@ -0,0 +1,53 @@
+import { createRequire } from 'node:module'
+import { deckLocale } from '@lincyaw/kernel'
+import type { ComponentNode, DirectiveSpec, MdastNode, PresmiumNodePlugin } from '@lincyaw/kernel'
+import { GUIDE_ID, GUIDE_MESSAGES, parseCursorPath, planCursorPath } from '../domain/index.ts'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+function component(name: string, props: Record<string, unknown>, fallback: MdastNode): ComponentNode {
+  const defined = Object.fromEntries(Object.entries(props).filter(([, value]) => value !== undefined))
+  return { type: 'component', plugin: GUIDE_ID, name, props: defined, fallback }
+}
+
+function popover(lang: string | undefined, title?: string, text?: string): MdastNode {
+  const children: MdastNode[] = []
+  if (title) children.push({ type: 'strong', children: [{ type: 'text', value: title }] })
+  if (text) children.push({ type: 'text', value: title ? `${GUIDE_MESSAGES[deckLocale(lang)].separator}${text}` : text })
+  return { type: 'root', children: children.length > 0 ? [{ type: 'paragraph', children }] : [] }
+}
+
+const cursor: DirectiveSpec = {
+  name: 'cursor',
+  body: true,
+  toIR(input, ctx) {
+    const path = planCursorPath(parseCursorPath(input.body))
+    if (path.length === 0) ctx.report({ checkId: GUIDE_ID, severity: 'error', message: '{cursor} needs at least one waypoint, e.g. `click #run`' })
+    return { node: { ...component('PmCursor', { path }, popover(ctx.lang)), layer: 'overlay' }, span: path.at(-1)?.at ?? 0 }
+  },
+}
+
+function cue(name: string, tag: string): DirectiveSpec {
+  return {
+    name,
+    arg: true,
+    body: true,
+    options: { title: 'string', span: 'number' },
+    toIR(input, ctx) {
+      if (!input.arg) ctx.report({ checkId: GUIDE_ID, severity: 'error', message: `{${name}} needs the CSS selector of its target, e.g. {${name}} #run` })
+      const span = typeof input.options.span === 'number' && Number.isInteger(input.options.span) && input.options.span > 0 ? input.options.span : 0
+      const title = typeof input.options.title === 'string' && input.options.title ? input.options.title : undefined
+      const text = input.body.trim() || undefined
+      return { node: component(tag, { target: input.arg ?? '', until: span + 1, title, text }, popover(ctx.lang, title, text)), span }
+    },
+  }
+}
+
+const plugin: PresmiumNodePlugin = {
+  id: GUIDE_ID,
+  version,
+  kernel: '^1.0.0',
+  directives: [cursor, cue('spotlight', 'PmSpotlight'), cue('hint', 'PmHint')],
+}
+
+export default plugin