@lincyaw/addon-content 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,38 @@
-# Temporary Holding Version
+# @lincyaw/addon-content
 
-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.
+Rich content: mind maps, PlantUML diagrams, video, audio, animations and YouTube.
+
+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-content
+```
+
+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
+
+- Mind maps, media with multilingual captions, and diagrams through component definitions.
+- Structured component data and readable static fallbacks, with files localized into `.presmium/assets/` when required.
+
+Native `PmMedia` video and audio keep the browser's controls and clock. Playback joins the runtime's
+shared playback lease: starting another player pauses the previous one, and a pending start cannot
+resume after navigation, cancellation or removal. Playback failures appear in the shared notice.
+
+The document editor's initial positioning pauses media; if it cancels autoplay, use the native Play
+control to start through the same authorization. Ordinary reading keeps native autoplay subject to
+browser policy. Pausing media stays paused across step navigation. This coordination applies to
+native video and audio; it does not control cross-origin YouTube players.
+
+## 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/PmMarkmap.tsx

@@ -0,0 +1 @@
+export { default } from '../src/client/MarkmapView.tsx'

package/components/PmMedia.css

@@ -0,0 +1,24 @@
+.pm-media {
+  margin: 0;
+}
+.pm-media :is(video, audio, img) {
+  display: block;
+  max-width: 100%;
+}
+.pm-media figcaption {
+  margin-top: 0.4em;
+  color: var(--pm-color-muted);
+  font-family: var(--pm-font-sans);
+  font-size: 0.85em;
+}
+.pm-media .pm-media-still {
+  display: none;
+}
+@media (prefers-reduced-motion: reduce) {
+  .pm-media .pm-media-motion {
+    display: none;
+  }
+  .pm-media .pm-media-still {
+    display: block;
+  }
+}

package/components/PmMedia.tsx

@@ -0,0 +1,77 @@
+import { PmNotice, useLocale, useMessages } from '@lincyaw/host'
+import { createElement, useRef } from 'react'
+import { useMediaPlayback } from '../src/client/media.ts'
+import { captionTracks, mediaElements, MESSAGES } from '../src/domain/index.ts'
+import type { MediaKind } from '../src/domain/index.ts'
+import './PmMedia.css'
+interface Props {
+  kind: MediaKind
+  src: string
+  still?: string
+  poster?: string
+  captions?: Record<string, string>
+  captionsDefault?: string
+  caption?: string
+  controls?: boolean
+  autoplay?: boolean
+  loop?: boolean
+  muted?: boolean
+  width?: number
+  height?: number
+  alt?: string
+}
+export default function PmMedia(props: Props) {
+  const locale = useLocale(),
+    t = useMessages(MESSAGES),
+    figure = useRef<HTMLElement>(null),
+    failed = useMediaPlayback(figure, `${props.kind}\0${props.src}`)
+  const elements = mediaElements(props.kind, props, props.still !== undefined),
+    tracks =
+      props.kind === 'video'
+        ? captionTracks(props.captions, props.captionsDefault, locale)
+        : []
+  return (
+    <figure
+      ref={figure}
+      className="pm-media"
+      data-kind={props.kind}
+    >
+      {elements.map(({ tag, file, attrs }, i) => {
+        const {
+          class: className,
+          autoplay: autoPlay,
+          playsinline: playsInline,
+          ...rest
+        } = attrs
+        return createElement(
+          tag,
+          {
+            ...rest,
+            className,
+            autoPlay,
+            playsInline,
+            src: file === 'still' ? props.still : props.src,
+            ...(tag === 'video' && props.poster
+              ? { poster: props.poster }
+              : {}),
+            key: i,
+          },
+          tag === 'video'
+            ? tracks.map((track) => (
+                <track
+                  key={track.srclang}
+                  kind="captions"
+                  src={track.src}
+                  srcLang={track.srclang}
+                  label={track.label}
+                  default={track.default}
+                />
+              ))
+            : undefined,
+        )
+      })}
+      {props.caption && <figcaption>{props.caption}</figcaption>}
+      {failed && <PmNotice tone="danger">{t.mediaPlaybackFailed}</PmNotice>}
+    </figure>
+  )
+}

package/components/PmYoutube.css

@@ -0,0 +1,5 @@
+.pm-youtube iframe {
+  display: block;
+  max-width: 100%;
+  border: 0;
+}

package/components/PmYoutube.tsx

@@ -0,0 +1,31 @@
+import './PmYoutube.css'
+export default function PmYoutube({
+  id,
+  start,
+  width = 560,
+  height = 315,
+  caption,
+}: {
+  id: string
+  start?: number
+  width?: number
+  height?: number
+  caption?: string
+}) {
+  const src = `https://www.youtube-nocookie.com/embed/${encodeURIComponent(id)}${start ? `?start=${start}` : ''}`
+  return (
+    <figure className="pm-media pm-youtube" data-kind="youtube">
+      <iframe
+        src={src}
+        title={caption || 'YouTube'}
+        width={width}
+        height={height}
+        loading="lazy"
+        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+        referrerPolicy="strict-origin-when-cross-origin"
+        allowFullScreen
+      />
+      {caption && <figcaption>{caption}</figcaption>}
+    </figure>
+  )
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@lincyaw/addon-content",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.1",
+  "description": "Presmium plugin: rich content: diagrams, mind maps, media, and web components",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lincyaw/presmium.git",
+    "directory": "packages/addon-content"
+  },
+  "homepage": "https://github.com/Lincyaw/presmium/tree/main/packages/addon-content#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",
+    "./presmium": "./src/node/presmium.ts",
+    "./media/*": "./media/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "components",
+    "media",
+    "src"
+  ],
+  "presmium": {
+    "preview": {
+      "restartable": true
+    }
+  },
+  "dependencies": {
+    "markmap-lib": "^0.18.12",
+    "markmap-view": "^0.18.12",
+    "plantuml-encoder": "^1.4.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/cli": "1.0.0-rc.1",
+    "@lincyaw/kernel": "1.0.0-rc.1"
+  }
 }

package/src/client/MarkmapView.css

@@ -0,0 +1,12 @@
+.pm-markmap {
+  display: block;
+  width: 100%;
+  height: var(--pm-markmap-height, 18rem);
+}
+.pm-markmap.markmap {
+  --markmap-text-color: var(--pm-color-ink);
+}
+.pm-markmap g.markmap-node > circle:focus-visible {
+  outline: var(--pm-size-stroke) solid currentColor;
+  outline-offset: var(--pm-size-stroke);
+}

package/src/client/MarkmapView.tsx

@@ -0,0 +1,106 @@
+import {
+  currentLocale,
+  usePrefersReducedMotion,
+  usePresentationMode,
+} from '@lincyaw/host'
+import { deriveOptions, Markmap } from 'markmap-view'
+import { useEffect, useRef, useState } from 'react'
+import { decodeMarkmap, MESSAGES } from '../domain/index.ts'
+import './MarkmapView.css'
+export default function MarkmapView({ data }: { data: string }) {
+  const interactive = usePresentationMode() === 'document',
+    reduced = usePrefersReducedMotion(),
+    svg = useRef<SVGSVGElement>(null),
+    [failure, setFailure] = useState<unknown>()
+  useEffect(() => {
+    const el = svg.current
+    if (!el) return
+    const { root, options } = decodeMarkmap(data)
+    let map: Markmap | undefined
+    let disposed = false
+    const fit = () => {
+      if (!map) return
+      const { x1, y1, x2, y2 } = map.state.rect,
+        width = el.clientWidth,
+        height = el.clientHeight
+      const scale =
+        map.options.fitRatio *
+        Math.min(
+          width / (x2 - x1 + 16),
+          height / (y2 - y1 + 16),
+          map.options.maxInitialScale,
+        )
+      map.zoom.extent([
+        [0, 0],
+        [width, height],
+      ])
+      map.zoom.scaleTo(map.svg, scale)
+      map.zoom.translateTo(map.svg, (x1 + x2) / 2, (y1 + y2) / 2)
+    }
+    const draw = async () => {
+      if (disposed || !el.clientWidth) return
+      if (map) return fit()
+      map = Markmap.create(el, {
+        ...deriveOptions(options),
+        autoFit: false,
+        zoom: interactive,
+        pan: interactive,
+      })
+      const duration = map.options.duration
+      await map.setData(root, { duration: 0 })
+      if (disposed) return
+      fit()
+      map.setOptions({ duration: reduced ? 0 : duration })
+    }
+    const observer = new ResizeObserver(() => void draw().catch(setFailure))
+    observer.observe(el)
+    const toggles = new MutationObserver(() => {
+      for (const circle of el.querySelectorAll('g.markmap-node > circle')) {
+        const node = circle.parentElement!
+        circle.setAttribute('tabindex', '0')
+        circle.setAttribute('role', 'button')
+        circle.setAttribute(
+          'aria-expanded',
+          String(!node.classList.contains('markmap-fold')),
+        )
+        circle.setAttribute(
+          'aria-label',
+          MESSAGES[currentLocale()].toggle(
+            node.querySelector('foreignObject')?.textContent?.trim() ?? '',
+          ),
+        )
+      }
+    })
+    toggles.observe(el, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: ['class'],
+    })
+    void draw().catch(setFailure)
+    return () => {
+      disposed = true
+      observer.disconnect()
+      toggles.disconnect()
+      map?.destroy()
+    }
+  }, [data, interactive, reduced])
+  if (failure) throw failure
+  return (
+    <svg
+      ref={svg}
+      className="pm-markmap"
+      onKeyDown={(event) => {
+        const target = event.target as Element
+        if (
+          (event.key === 'Enter' || event.key === ' ') &&
+          target.matches('g.markmap-node > circle')
+        ) {
+          event.preventDefault()
+          event.stopPropagation()
+          target.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+        }
+      }}
+    />
+  )
+}

package/src/client/media.ts

@@ -0,0 +1,107 @@
+import { PLAYBACK_CONTROL, useService, useStep, useStepState, useViewRole } from '@lincyaw/host'
+import { createContext, useContext, useLayoutEffect, useState } from 'react'
+import type { RefObject } from 'react'
+export const MEDIA_ACTIVE = createContext(true)
+export function useMediaActive(): boolean { const active = useContext(MEDIA_ACTIVE), role = useViewRole(), state = useStepState({ from: 0 }); return active && (role === 'reader' || state.active) }
+
+/** Native controls retain their clock; the runtime lease only authorizes starts. */
+export function useMediaPlayback(figure: RefObject<HTMLElement>, source: string): boolean {
+  const control = useService(PLAYBACK_CONTROL), active = useMediaActive(), step = useStep()
+  const [failed, setFailed] = useState(false)
+  useLayoutEffect(() => {
+    const media = [...figure.current?.querySelectorAll<HTMLMediaElement>('video,audio') ?? []]
+    setFailed(false)
+    if (!media.length) return
+    let disposed = false, generation = 0
+    let current: { element: HTMLMediaElement, generation: number, phase: 'holding' | 'authorizing' | 'starting' | 'playing' } | undefined
+    const pauses = new Map<HTMLMediaElement, (() => void)[]>()
+    const pause = (element: HTMLMediaElement): Promise<void> => {
+      if (element.paused) return Promise.resolve()
+      return new Promise(resolve => {
+        const pending = pauses.get(element) ?? []
+        pending.push(resolve)
+        pauses.set(element, pending)
+        element.pause()
+      })
+    }
+    const stop = () => {
+      generation++
+      current = undefined
+      lease?.cancel()
+      for (const element of media) void pause(element)
+    }
+    const lease = control?.register(stop)
+    const valid = (request: NonNullable<typeof current>) => !disposed && active && current === request && generation === request.generation
+    const start = async (element: HTMLMediaElement) => {
+      lease?.cancel()
+      const request: NonNullable<typeof current> = { element, generation: ++generation, phase: 'holding' }
+      current = request
+      setFailed(false)
+      try {
+        // pause() queues a native event. Drain it before restoring playback so an
+        // old internal pause cannot cancel the permission just granted.
+        await pause(element)
+        if (!valid(request)) return
+        request.phase = 'authorizing'
+        const allowed = lease ? await lease.requestStart() : true
+        if (!valid(request) || !allowed) return
+        request.phase = 'starting'
+        await element.play()
+      } catch (error) {
+        if (!valid(request)) return
+        stop()
+        if (!(error instanceof Error && error.name === 'AbortError')) setFailed(true)
+      }
+    }
+    const onPlay = (event: Event) => {
+      const element = event.currentTarget as HTMLMediaElement
+      if (disposed || !active) { stop(); return }
+      if (current?.element === element && current.phase === 'starting') {
+        if (element.paused) stop()
+        else current.phase = 'playing'
+        return
+      }
+      if (element.paused) return // A play event queued before a newer pause.
+      void start(element)
+    }
+    const onPause = (event: Event) => {
+      const element = event.currentTarget as HTMLMediaElement, pending = pauses.get(element)
+      if (pending?.length) { pending.shift()!(); if (!pending.length) pauses.delete(element); return }
+      if (current?.element !== element || !element.paused) return
+      // During authorization the element is deliberately paused. A native
+      // control cannot pause it again; external cancellation calls stop().
+      if (current.phase === 'authorizing' || current.phase === 'holding' || current.phase === 'starting') return
+      stop()
+    }
+    const onStop = () => stop()
+    const onSeek = () => {
+      // Seeking during an authorization invalidates that start. Once playing,
+      // native scrubbing and loop seeks keep their existing lease and clock.
+      if (current && current.phase !== 'playing') stop()
+    }
+    const onError = () => { stop(); if (!disposed) setFailed(true) }
+    for (const element of media) {
+      element.addEventListener('play', onPlay)
+      element.addEventListener('pause', onPause)
+      element.addEventListener('ended', onStop)
+      element.addEventListener('seeking', onSeek)
+      element.addEventListener('error', onError)
+    }
+    if (!active) stop()
+    return () => {
+      disposed = true
+      stop()
+      lease?.dispose()
+      for (const element of media) {
+        element.removeEventListener('play', onPlay)
+        element.removeEventListener('pause', onPause)
+        element.removeEventListener('ended', onStop)
+        element.removeEventListener('seeking', onSeek)
+        element.removeEventListener('error', onError)
+      }
+      for (const pending of pauses.values()) for (const resolve of pending) resolve()
+      pauses.clear()
+    }
+  }, [figure, control, active, step, source])
+  return failed
+}

package/src/domain/config.ts

@@ -0,0 +1,8 @@
+export const CONTENT_ID = 'presmium.content'
+
+const CUSTOM_ELEMENT_PREFIX = 'presmium-'
+
+/** Tags the slides form leaves to the browser as custom elements (web components), not Vue components. */
+export function isCustomElementTag(tag: string): boolean {
+  return tag.startsWith(CUSTOM_ELEMENT_PREFIX)
+}

package/src/domain/index.ts

@@ -0,0 +1,7 @@
+export { CONTENT_ID, isCustomElementTag } from './config.ts'
+export { decodeMarkmap, encodeMarkmap, markmapOutline } from './markmap.ts'
+export type { MarkmapData, MarkmapNode } from './markmap.ts'
+export { captionTracks, isRemote, languageName, languageTag, MEDIA_KINDS, MEDIA_OPTIONS, mediaElements, mediaFallback, parseCaptions, videoHtml, youtubeId } from './media.ts'
+export type { CaptionTrack, MediaElement, MediaKind, MediaOptions } from './media.ts'
+export { MESSAGES } from './messages.ts'
+export type { ContentMessages } from './messages.ts'

package/src/domain/markmap.ts

@@ -0,0 +1,42 @@
+import type { MdastNode } from '@lincyaw/kernel'
+
+export interface MarkmapNode {
+  content: string
+  children: MarkmapNode[]
+  payload?: Record<string, unknown>
+}
+
+export interface MarkmapData {
+  root: MarkmapNode
+  options?: Record<string, unknown>
+}
+
+export function encodeMarkmap(data: MarkmapData): string {
+  return encodeURIComponent(JSON.stringify(data))
+}
+
+export function decodeMarkmap(value: string): MarkmapData {
+  return JSON.parse(decodeURIComponent(value)) as MarkmapData
+}
+
+const ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: '\'', nbsp: ' ' }
+
+function text(html: string): string {
+  return html.replace(/<[^>]*>/g, '').replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (entity, name: string) => {
+    if (name[0] !== '#') return ENTITIES[name] ?? entity
+    return String.fromCodePoint(name[1] === 'x' || name[1] === 'X' ? Number.parseInt(name.slice(2), 16) : Number(name.slice(1)))
+  }).trim()
+}
+
+export function markmapOutline(root: MarkmapNode): MdastNode {
+  const item = (node: MarkmapNode): MdastNode => ({
+    type: 'listItem',
+    spread: false,
+    children: [
+      { type: 'paragraph', children: [{ type: 'text', value: text(node.content) }] },
+      ...node.children.length > 0 ? [list(node.children)] : [],
+    ],
+  })
+  const list = (nodes: MarkmapNode[]): MdastNode => ({ type: 'list', ordered: false, spread: false, children: nodes.map(item) })
+  return { type: 'root', children: [list([root])] }
+}

package/src/domain/media.ts

@@ -0,0 +1,128 @@
+import { escapeHtml } from '@lincyaw/kernel'
+import type { MdastNode } from '@lincyaw/kernel'
+
+export type MediaKind = 'video' | 'audio' | 'animation'
+
+export const MEDIA_KINDS: readonly MediaKind[] = ['video', 'audio', 'animation']
+
+export interface MediaOptions {
+  controls?: boolean
+  autoplay?: boolean
+  loop?: boolean
+  muted?: boolean
+  width?: number
+  height?: number
+  alt?: string
+}
+
+export const MEDIA_OPTIONS = { controls: 'boolean', autoplay: 'boolean', loop: 'boolean', muted: 'boolean', width: 'number', height: 'number', alt: 'string' } as const
+
+export interface MediaElement {
+  tag: 'video' | 'audio' | 'img'
+  file: 'media' | 'still'
+  attrs: Record<string, string | number | true>
+}
+
+export function mediaElements(kind: MediaKind, options: MediaOptions, still: boolean): MediaElement[] {
+  const size: Record<string, number> = {}
+  for (const key of ['width', 'height'] as const) {
+    const value = options[key]
+    if (typeof value === 'number' && value > 0) size[key] = value
+  }
+  const flags = (names: (keyof MediaOptions)[]) => Object.fromEntries(names.filter(name => options[name] === true).map(name => [name, true as const]))
+  if (kind === 'video') {
+    const autoplay: Record<string, true> = options.autoplay ? { muted: true, playsinline: true } : {}
+    return [{ tag: 'video', file: 'media', attrs: { ...flags(['controls', 'autoplay', 'loop', 'muted']), ...autoplay, preload: 'metadata', ...size } }]
+  }
+  if (kind === 'audio') return [{ tag: 'audio', file: 'media', attrs: { ...flags(['controls', 'autoplay', 'loop']), preload: 'metadata' } }]
+  const alt = { alt: options.alt ?? '' }
+  if (!still) return [{ tag: 'img', file: 'media', attrs: { ...alt, ...size } }]
+  return [
+    { tag: 'img', file: 'media', attrs: { class: 'pm-media-motion', ...alt, ...size } },
+    { tag: 'img', file: 'still', attrs: { class: 'pm-media-still', ...alt, ...size } },
+  ]
+}
+
+export interface CaptionTrack {
+  srclang: string
+  src: string
+  label: string
+  default: boolean
+}
+
+export function parseCaptions(value: string): { captions: Record<string, string>, invalid: string[] } {
+  const captions: Record<string, string> = {}
+  const invalid: string[] = []
+  for (const entry of value.split(',').map(part => part.trim()).filter(Boolean)) {
+    const [lang = '', ...file] = entry.split('=')
+    const tag = languageTag(lang.trim())
+    const path = file.join('=').trim()
+    if (tag && path) captions[tag] = path
+    else invalid.push(entry)
+  }
+  return { captions, invalid }
+}
+
+export function languageTag(value: string): string | undefined {
+  try {
+    return value ? Intl.getCanonicalLocales(value)[0] : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function languageName(lang: string, locale: string): string {
+  try {
+    return new Intl.DisplayNames([locale], { type: 'language' }).of(lang) ?? lang
+  } catch {
+    return lang
+  }
+}
+
+export function captionTracks(captions: Record<string, string> | undefined, chosen: string | undefined, locale: string): CaptionTrack[] {
+  return Object.entries(captions ?? {}).map(([srclang, src]) => ({ srclang, src, label: languageName(srclang, locale), default: srclang === chosen }))
+}
+
+function htmlAttributes(attrs: Record<string, string | number | true | undefined>): string {
+  return Object.entries(attrs)
+    .filter(([, value]) => value !== undefined)
+    .map(([name, value]) => (value === true ? ` ${name}` : ` ${name}="${escapeHtml(String(value))}"`))
+    .join('')
+}
+
+export function videoHtml(video: { src: string, poster?: string, tracks: CaptionTrack[], caption?: string, options: MediaOptions }): string {
+  const [element] = mediaElements('video', video.options, false)
+  const tracks = video.tracks.map(track => `<track${htmlAttributes({ kind: 'captions', src: track.src, srclang: track.srclang, label: track.label, default: track.default || undefined })}>`)
+  const lines = ['<figure>', `<video${htmlAttributes({ ...element!.attrs, src: video.src, poster: video.poster })}>`, ...tracks, '</video>']
+  if (video.caption) lines.push(`<figcaption>${escapeHtml(video.caption)}</figcaption>`)
+  return [...lines, '</figure>'].join('\n')
+}
+
+export function mediaFallback(url: string, caption?: string): MdastNode {
+  const name = caption || url.split(/[?#]/)[0]!.split('/').pop() || url
+  return { type: 'root', children: [{ type: 'paragraph', children: [{ type: 'link', url, children: [{ type: 'text', value: name }] }] }] }
+}
+
+export function isRemote(path: string): boolean {
+  return /^https?:\/\//i.test(path)
+}
+
+const YOUTUBE_ID = /^[\w-]{11}$/
+
+export function youtubeId(value: string): string | undefined {
+  const text = value.trim()
+  if (YOUTUBE_ID.test(text)) return text
+  let url: URL
+  try {
+    url = new URL(text)
+  } catch {
+    return undefined
+  }
+  const host = url.hostname.replace(/^(www\.|m\.)/, '')
+  const id = host === 'youtu.be'
+    ? url.pathname.slice(1)
+    : /^youtube(-nocookie)?\.com$/.test(host)
+      ? url.searchParams.get('v') ?? /^\/(?:embed|shorts|live)\/([^/]+)/.exec(url.pathname)?.[1]
+      : undefined
+  return id && YOUTUBE_ID.test(id) ? id : undefined
+}

package/src/domain/messages.ts

@@ -0,0 +1,12 @@
+import type { Locale } from '@lincyaw/kernel'
+
+export interface ContentMessages {
+  plantUml: string
+  mediaPlaybackFailed: string
+  toggle: (node: string) => string
+}
+
+export const MESSAGES: Record<Locale, ContentMessages> = {
+  'zh-CN': { plantUml: 'PlantUML 图', mediaPlaybackFailed: '无法播放媒体。请检查文件或播放权限，然后重试。', toggle: node => `折叠或展开：${node}` },
+  'en': { plantUml: 'PlantUML diagram', mediaPlaybackFailed: 'Couldn’t play the media. Check the file or playback permission, then try again.', toggle: node => `Fold or unfold: ${node}` },
+}

package/src/node/markmap.ts

@@ -0,0 +1,24 @@
+import { isRecord } from '@lincyaw/kernel'
+import type { DirectiveSpec } from '@lincyaw/kernel'
+import { Transformer } from 'markmap-lib'
+import { CONTENT_ID, encodeMarkmap, markmapOutline } from '../domain/index.ts'
+
+const transformer = new Transformer()
+
+export const markmapDirective: DirectiveSpec = {
+  name: 'markmap',
+  body: true,
+  toIR(input) {
+    const { root, frontmatter } = transformer.transform(input.body)
+    const options = isRecord(input.options.markmap) ? input.options.markmap : frontmatter?.markmap
+    return {
+      node: {
+        type: 'component',
+        plugin: CONTENT_ID,
+        name: 'PmMarkmap',
+        props: { data: encodeMarkmap({ root, ...options ? { options } : {} }) },
+        fallback: markmapOutline(root),
+      },
+    }
+  },
+}

package/src/node/media.ts

@@ -0,0 +1,128 @@
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { deckLocale, docBlocks, isRecord, NON_FILE_URL } from '@lincyaw/kernel'
+import type { ComponentNode, DirectiveContext, DirectiveSpec, IRBlock, IRPass, RenderContext } from '@lincyaw/kernel'
+import { captionTracks, CONTENT_ID, isRemote, languageTag, MEDIA_OPTIONS, mediaFallback, parseCaptions, videoHtml, youtubeId } from '../domain/index.ts'
+import type { MediaKind, MediaOptions } from '../domain/index.ts'
+
+function resolveMedia(path: string, ctx: DirectiveContext): string | undefined {
+  const file = resolve(dirname(ctx.file), path)
+  if (existsSync(file) || path.startsWith('.') || isAbsolute(path)) return existsSync(file) ? file : undefined
+  try {
+    return createRequire(join(ctx.deckDir, 'package.json')).resolve(path)
+  } catch {
+    return undefined
+  }
+}
+
+const posix = (path: string) => path.split(sep).join('/')
+
+/** Resource paths belong to the actual media parameters, including step overrides. */
+function mediaAssets(props: Record<string, unknown>): Record<string, string> {
+  const assets: Record<string, string> = {}
+  for (const key of ['src', 'poster', 'still']) if (typeof props[key] === 'string' && props[key]) assets[key] = props[key]
+  if (isRecord(props.captions)) for (const [lang, value] of Object.entries(props.captions)) if (typeof value === 'string' && value) assets[`captions.${lang}`] = value
+  return assets
+}
+
+export const mediaAssetsPass: IRPass = {
+  name: 'presmium.content.media-assets',
+  run(doc, ctx) {
+    for (const { block } of docBlocks(doc)) {
+      const { node } = block
+      if (node.type !== 'component' || node.plugin !== CONTENT_ID || node.name !== 'PmMedia') continue
+      node.assets = mediaAssets(node.props)
+      for (const state of block.stepStates ?? []) state.assets = mediaAssets(state.parameters ?? node.props)
+      const urls = new Set([node.assets, ...(block.stepStates ?? []).map(state => state.assets)].flatMap(assets => Object.values(assets ?? {})))
+      for (const url of urls) {
+        if (NON_FILE_URL.test(url)) continue
+        let file = url.replace(/[?#].*$/s, '')
+        try { file = decodeURIComponent(file) } catch {}
+        if (file) ctx.watch(file.startsWith('/') ? join(ctx.deckDir, 'public', file) : resolve(dirname(block.source.file), file))
+      }
+    }
+  },
+}
+
+const FILE_OPTIONS = {
+  video: { 'poster': 'string', 'captions': 'string', 'captions-default': 'string' },
+  audio: {},
+  animation: { still: 'string' },
+} as const
+
+export function mediaDirective(kind: MediaKind): DirectiveSpec {
+  return {
+    name: kind,
+    arg: true,
+    body: true,
+    options: { ...MEDIA_OPTIONS, ...FILE_OPTIONS[kind] },
+    toIR(input, ctx) {
+      const report = (severity: 'error' | 'warning', message: string) => ctx.report({ checkId: CONTENT_ID, severity, message: `{${kind}}: ${message}` })
+      const option = (name: string) => (typeof input.options[name] === 'string' ? (input.options[name] as string).trim() : undefined)
+      const media = input.arg?.trim()
+      if (!media) report('error', 'needs the path or URL of the media file')
+      const assets: Record<string, string> = {}
+      const url = (path: string, prop: string) => {
+        if (isRemote(path)) return path
+        const file = resolveMedia(path, ctx)
+        if (!file) report('error', `file not found: ${path}`)
+        return assets[prop] = file ? posix(relative(dirname(ctx.file), file)) : path
+      }
+      const props: Record<string, unknown> = { kind, src: media ? url(media, 'src') : '' }
+      const still = option('still')
+      if (still) props.still = url(still, 'still')
+      const poster = option('poster')
+      if (poster) props.poster = url(poster, 'poster')
+      const { captions, invalid } = parseCaptions(option('captions') ?? '')
+      for (const entry of invalid) report('error', `:captions: "${entry}" is not <language>=<file>, e.g. en=films/loop.en.vtt`)
+      if (Object.keys(captions).length) props.captions = Object.fromEntries(Object.entries(captions).map(([lang, path]) => [lang, url(path, `captions.${lang}`)]))
+      const chosen = option('captions-default')
+      const shown = chosen && Object.keys(captions).find(lang => lang === languageTag(chosen))
+      if (chosen && !shown) report('warning', `:captions-default: ${chosen} is not a language of :captions:; no captions show at first`)
+      if (shown) props.captionsDefault = shown
+      const { still: _still, 'poster': _poster, 'captions': _captions, 'captions-default': _default, ...options } = input.options
+      const caption = input.body.trim()
+      const node: ComponentNode = {
+        type: 'component',
+        plugin: CONTENT_ID,
+        name: 'PmMedia',
+        props: { ...props, ...options, ...caption ? { caption } : {} },
+        ...Object.keys(assets).length ? { assets } : {},
+        fallback: mediaFallback(String(props.src), caption),
+      }
+      return { node }
+    },
+  }
+}
+
+export function notebookMedia(node: ComponentNode, _block: IRBlock, ctx: RenderContext): unknown {
+  const { kind, src, poster, captions, captionsDefault, caption, ...options } = node.props
+  if (kind !== 'video' || (!poster && !captions)) return undefined
+  const tracks = captionTracks(captions as Record<string, string> | undefined, captionsDefault as string | undefined, deckLocale(ctx.lang))
+  const html = videoHtml({ src: String(src), poster: poster as string | undefined, tracks, caption: caption as string | undefined, options: options as MediaOptions })
+  return { cell_type: 'markdown', source: html }
+}
+
+export const youtubeDirective: DirectiveSpec = {
+  name: 'youtube',
+  arg: true,
+  body: true,
+  options: { start: 'number', width: 'number', height: 'number' },
+  toIR(input, ctx) {
+    const id = youtubeId(input.arg ?? '')
+    if (!id) ctx.report({ checkId: CONTENT_ID, severity: 'error', message: `{youtube}: "${input.arg ?? ''}" is no YouTube video id or link` })
+    const caption = input.body.trim()
+    const sizes = Object.fromEntries(['start', 'width', 'height'].flatMap(key => (typeof input.options[key] === 'number' && (input.options[key] as number) > 0 ? [[key, input.options[key]]] : [])))
+    const url = `https://www.youtube.com/watch?v=${id ?? ''}`
+    return {
+      node: {
+        type: 'component',
+        plugin: CONTENT_ID,
+        name: 'PmYoutube',
+        props: { id: id ?? '', ...sizes, ...caption ? { caption } : {} },
+        fallback: { type: 'root', children: [{ type: 'paragraph', children: [{ type: 'link', url, children: [{ type: 'text', value: caption || url }] }] }] },
+      },
+    }
+  },
+}

package/src/node/plantuml-encoder.d.ts

@@ -0,0 +1,4 @@
+declare module 'plantuml-encoder' {
+  const encoder: { encode(text: string): string }
+  export default encoder
+}

package/src/node/plantuml.ts

@@ -0,0 +1,20 @@
+import { deckLocale, docBlocks } from '@lincyaw/kernel'
+import type { IRPass } from '@lincyaw/kernel'
+import plantuml from 'plantuml-encoder'
+import { MESSAGES } from '../domain/index.ts'
+
+const DEFAULT_SERVER = 'https://www.plantuml.com/plantuml'
+
+export const plantUmlPass: IRPass = {
+  name: 'presmium.content.plantuml',
+  run(doc, ctx) {
+    const server = (typeof ctx.config.plantUmlServer === 'string' ? ctx.config.plantUmlServer : DEFAULT_SERVER).replace(/\/+$/, '')
+    const alt = MESSAGES[deckLocale(ctx.lang)].plantUml
+    for (const { block } of docBlocks(doc)) {
+      const { node } = block
+      if (node.type !== 'code' || !/^(?:plantuml|puml)$/i.test(node.lang)) continue
+      const image = { type: 'image', url: `${server}/svg/${plantuml.encode(node.value)}`, alt: node.title ?? alt }
+      block.node = { type: 'markdown', mdast: { type: 'root', children: [{ type: 'paragraph', children: [image] }] } }
+    }
+  },
+}

package/src/node/presmium.ts

@@ -0,0 +1,19 @@
+import { createRequire } from 'node:module'
+import type { PresmiumNodePlugin } from '@lincyaw/kernel'
+import { CONTENT_ID, MEDIA_KINDS } from '../domain/index.ts'
+import { markmapDirective } from './markmap.ts'
+import { mediaAssetsPass, mediaDirective, notebookMedia, youtubeDirective } from './media.ts'
+import { plantUmlPass } from './plantuml.ts'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+const plugin: PresmiumNodePlugin = {
+  id: CONTENT_ID,
+  version,
+  kernel: '^1.0.0',
+  directives: [markmapDirective, ...MEDIA_KINDS.map(kind => mediaDirective(kind)), youtubeDirective],
+  passes: [plantUmlPass, mediaAssetsPass],
+  rendererExtensions: { notebook: { components: { PmMedia: notebookMedia } } },
+}
+
+export default plugin