@bendyline/squisq-react 2.4.7 → 2.6.0

package/README.md

@@ -57,6 +57,25 @@ state rather than crashing.
 | `MediaClipLayer`       | Hidden `<audio>`/`<video>` elements for timed media clips           |
 | `JsonView`             | Read-only viewer for JSON values bound to a Squisq-annotated schema |
 
+### Fenced-code copy control
+
+`MarkdownRenderer` and the linear document surfaces keep code-copy UI off by
+default. Opt in with `showCodeCopyButton`. Web hosts can rely on
+`navigator.clipboard`; Electron or native embeddings can provide their own
+clipboard bridge:
+
+````tsx
+<LinearDocView
+  markdown={'```\n$ node packages/tooling/dist/cli.mjs components\n```'}
+  showCodeCopyButton
+  onCopyCode={(code, { language }) => hostClipboard.writeText(code)}
+/>
+````
+
+The same two props are available on `DocPlayer` (for linear mode), and on the
+standalone static `mount()` options. The callback receives the exact fence
+contents, without the backtick delimiters.
+
 ## Layers
 
 Blocks are composed of typed layers rendered as SVG:

package/dist/MarkdownRenderer-CerBKw-c.d.ts

@@ -0,0 +1,53 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Theme } from '@bendyline/squisq/schemas';
+import { MarkdownBlockNode, HtmlPolicy } from '@bendyline/squisq/markdown';
+
+interface CodeBlockCopyContext {
+    /** Authored fence language, when one was supplied. */
+    language?: string;
+}
+/**
+ * Host-owned clipboard adapter for fenced code blocks.
+ *
+ * The callback runs directly from the button's click handler so Electron
+ * bridges and browser Clipboard APIs retain their user-gesture context.
+ */
+type CodeBlockCopyHandler = (code: string, context: CodeBlockCopyContext) => void | Promise<void>;
+interface MarkdownRendererProps {
+    /** Block-level AST nodes to render */
+    nodes: MarkdownBlockNode[];
+    /** Optional CSS class for the wrapper element */
+    className?: string;
+    /**
+     * Raw HTML policy. Defaults to `sanitize`, which removes unsafe tags,
+     * event handlers, and executable URL schemes before rendering.
+     */
+    htmlPolicy?: HtmlPolicy;
+    /**
+     * Extra URL schemes to allow on links (e.g. a host app's internal
+     * navigation scheme it intercepts on click). Executable schemes are
+     * never allowed regardless. See {@link SanitizeUrlOptions}.
+     */
+    linkSchemes?: readonly string[];
+    /** Resolved Squisq theme inherited by embedded Mermaid diagrams. */
+    theme?: Theme;
+    /** Show a subtle Copy button on ordinary fenced code blocks (default: false). */
+    showCodeCopyButton?: boolean;
+    /**
+     * Optional host clipboard adapter. When omitted, enabled copy buttons use
+     * `navigator.clipboard.writeText`. Supply this for Electron, native shells,
+     * or hosts with their own clipboard permission/error handling.
+     */
+    onCopyCode?: CodeBlockCopyHandler;
+}
+/**
+ * Renders MarkdownBlockNode[] AST as React HTML elements.
+ *
+ * @example
+ * ```tsx
+ * <MarkdownRenderer nodes={block.contents} />
+ * ```
+ */
+declare function MarkdownRenderer({ nodes, className, htmlPolicy, linkSchemes, theme, showCodeCopyButton, onCopyCode, }: MarkdownRendererProps): react_jsx_runtime.JSX.Element | null;
+
+export { type CodeBlockCopyHandler as C, MarkdownRenderer as M, type CodeBlockCopyContext as a, type MarkdownRendererProps as b };

package/dist/{chunk-KF4DTT46.js → chunk-GWD62KLD.js}

@@ -1,13 +1,13 @@
 import {
   BlockRenderer,
   LinearDocView
-} from "./chunk-3HYSWEKG.js";
+} from "./chunk-U6P7HBUY.js";
 import {
   useAudioSync,
   useDocPlayback,
   useMediaSchedule,
   useViewportOrientation
-} from "./chunk-BOZJ655L.js";
+} from "./chunk-MVJQL2W2.js";
 import {
   useAutoSurface
 } from "./chunk-TT6ENR6T.js";
@@ -1243,7 +1243,10 @@ function DocControlsSlideshow({
 }
 
 // src/docPlayer/playerAppearance.ts
-import { resolveThemeForDoc } from "@bendyline/squisq/doc";
+import {
+  resolveCoverSlideSettings,
+  resolveThemeForDoc
+} from "@bendyline/squisq/doc";
 function readFrontmatterSetting(frontmatter, canonical, legacy) {
   if (!frontmatter) return void 0;
   return Object.prototype.hasOwnProperty.call(frontmatter, canonical) ? frontmatter[canonical] : frontmatter[legacy];
@@ -1291,20 +1294,14 @@ function resolvePipPosition(value) {
   };
   return aliases[normalized];
 }
-function resolveBoolean(value) {
-  if (typeof value === "boolean") return value;
-  if (typeof value !== "string") return void 0;
-  const normalized = value.trim().toLowerCase();
-  if (normalized === "true" || normalized === "yes" || normalized === "on" || normalized === "show" || normalized === "visible") {
-    return true;
-  }
-  if (normalized === "false" || normalized === "no" || normalized === "off" || normalized === "hide" || normalized === "hidden") {
-    return false;
-  }
-  return void 0;
-}
 function resolveDocPlayerAppearance(doc, overrides = {}) {
   const frontmatter = doc.frontmatter;
+  const cover = resolveCoverSlideSettings(frontmatter, {
+    ...overrides.showCoverSlide !== void 0 ? { enabled: overrides.showCoverSlide } : {},
+    ...overrides.coverSlideTemplate !== void 0 ? { template: overrides.coverSlideTemplate } : {},
+    ...overrides.coverSlideDuration !== void 0 ? { duration: overrides.coverSlideDuration } : {},
+    ...overrides.coverSlidePlayback !== void 0 ? { playback: overrides.coverSlidePlayback } : {}
+  });
   return {
     theme: overrides.theme ?? resolveThemeForDoc(doc),
     videoPresentation: overrides.videoPresentation ?? resolveVideoPresentation(
@@ -1315,7 +1312,10 @@ function resolveDocPlayerAppearance(doc, overrides = {}) {
     pipPosition: overrides.pipPosition ?? resolvePipPosition(
       readFrontmatterSetting(frontmatter, "squisq-pip-position", "pip-position")
     ) ?? "bottom-right",
-    showCoverSlide: overrides.showCoverSlide ?? resolveBoolean(readFrontmatterSetting(frontmatter, "squisq-cover-slide", "cover-slide")) ?? true
+    showCoverSlide: cover.enabled,
+    coverSlideTemplate: cover.template,
+    coverSlideDuration: cover.duration,
+    coverSlidePlayback: cover.playback
   };
 }
 
@@ -1567,17 +1567,36 @@ function isVisiblyPresented(video) {
   }
   return true;
 }
+function createCaptureWatchdog(ownerDocument, timeoutMs, expire) {
+  let timeout = null;
+  const clear = () => {
+    if (timeout === null) return;
+    clearTimeout(timeout);
+    timeout = null;
+  };
+  return {
+    arm: () => {
+      clear();
+      if (ownerDocument.visibilityState !== "visible") return;
+      timeout = setTimeout(expire, timeoutMs);
+    },
+    clear
+  };
+}
 function seekVideoByAssignment(video, targetTime, timeoutMs = DEFAULT_VIDEO_FRAME_TIMEOUT_MS) {
   video.pause();
   return new Promise((resolve, reject) => {
     let settled = false;
     let videoFrameRequest = null;
+    const ownerDocument = video.ownerDocument;
+    const isInactive = () => ownerDocument.visibilityState !== "visible";
     const cleanup = () => {
-      clearTimeout(timeout);
+      watchdog.clear();
       clearInterval(readinessPoll);
       video.removeEventListener("seeked", handleMediaReady);
       video.removeEventListener("loadeddata", handleMediaReady);
       video.removeEventListener("canplay", handleMediaReady);
+      ownerDocument.removeEventListener("visibilitychange", handleVisibilityChange);
       if (videoFrameRequest !== null && typeof video.cancelVideoFrameCallback === "function") {
         video.cancelVideoFrameCallback(videoFrameRequest);
       }
@@ -1615,34 +1634,48 @@ function seekVideoByAssignment(video, targetTime, timeoutMs = DEFAULT_VIDEO_FRAM
     function handleMediaReady() {
       requestPresentedFrame();
     }
-    const timeout = setTimeout(fail, timeoutMs);
+    const watchdog = createCaptureWatchdog(ownerDocument, timeoutMs, fail);
+    const assignTargetTime = () => {
+      try {
+        video.currentTime = reachableMediaTime(video, targetTime);
+        queueMicrotask(requestPresentedFrame);
+        return true;
+      } catch (error) {
+        settled = true;
+        cleanup();
+        reject(error);
+        return false;
+      }
+    };
+    function handleVisibilityChange() {
+      if (settled) return;
+      if (isInactive()) {
+        watchdog.clear();
+        return;
+      }
+      requestPresentedFrame();
+      if (settled) return;
+      if (!video.seeking && !isAtReachableMediaTime(video, targetTime) && !assignTargetTime()) {
+        return;
+      }
+      watchdog.arm();
+    }
     const readinessPoll = setInterval(requestPresentedFrame, VIDEO_FRAME_READINESS_POLL_MS);
     video.addEventListener("seeked", handleMediaReady);
     video.addEventListener("loadeddata", handleMediaReady);
     video.addEventListener("canplay", handleMediaReady);
-    try {
-      video.currentTime = reachableMediaTime(video, targetTime);
-      queueMicrotask(requestPresentedFrame);
-    } catch (error) {
-      settled = true;
-      cleanup();
-      reject(error);
-    }
+    ownerDocument.addEventListener("visibilitychange", handleVisibilityChange);
+    watchdog.arm();
+    assignTargetTime();
   });
 }
 function advanceSequentialCaptureVideo(video, targetTime, timeoutMs) {
   return new Promise((resolve, reject) => {
     let settled = false;
-    let timeout = null;
     const ownerDocument = video.ownerDocument;
     const isInactive = () => ownerDocument.visibilityState !== "visible";
-    const clearWatchdog = () => {
-      if (timeout === null) return;
-      clearTimeout(timeout);
-      timeout = null;
-    };
     const cleanup = () => {
-      clearWatchdog();
+      watchdog.clear();
       clearInterval(readinessPoll);
       video.removeEventListener("timeupdate", check);
       video.removeEventListener("loadeddata", check);
@@ -1696,21 +1729,17 @@ function advanceSequentialCaptureVideo(video, targetTime, timeoutMs) {
         handlePlaybackFailure();
       }
     };
-    const armWatchdog = () => {
-      clearWatchdog();
-      if (settled || isInactive()) return;
-      timeout = setTimeout(fail, timeoutMs);
-    };
+    const watchdog = createCaptureWatchdog(ownerDocument, timeoutMs, fail);
     const pauseWhileInactive = () => {
       video.pause();
-      clearWatchdog();
+      watchdog.clear();
     };
     const resumeWhenActive = () => {
       if (settled || isInactive()) return;
       check();
       if (settled) return;
       startPlayback();
-      armWatchdog();
+      watchdog.arm();
     };
     function handleVisibilityChange() {
       if (ownerDocument.visibilityState !== "visible") {
@@ -1818,6 +1847,9 @@ function DocPlayerContent({
   forceViewport,
   displayMode = "video",
   showCoverSlide,
+  coverSlideTemplate,
+  coverSlideDuration,
+  coverSlidePlayback,
   coverVisible,
   theme,
   surface,
@@ -1827,7 +1859,9 @@ function DocPlayerContent({
   pipShape,
   pipPosition,
   enableSwipe = true,
-  globalKeyboardShortcuts = false
+  globalKeyboardShortcuts = false,
+  showCodeCopyButton = false,
+  onCopyCode
 }) {
   const isSlideshowMode = displayMode === "slideshow";
   const isLinearMode = displayMode === "linear";
@@ -1844,12 +1878,17 @@ function DocPlayerContent({
     const params = new URLSearchParams(window.location.search);
     return params.get("debug") === "true";
   }, []);
+  const syntheticDuration = useMemo3(
+    () => audioMode === "synthetic" ? getDocPlaybackDuration(doc) : 0,
+    [audioMode, doc]
+  );
   const internalAudio = useAudioSync(
     audioRef,
     doc.audio,
     basePath,
     !externalAudioController,
-    audioMode
+    audioMode,
+    syntheticDuration
   );
   const audio = externalAudioController || internalAudio;
   useEffect5(() => {
@@ -1973,9 +2012,23 @@ function DocPlayerContent({
       pipSize,
       pipShape,
       pipPosition,
-      showCoverSlide
+      showCoverSlide,
+      coverSlideTemplate,
+      coverSlideDuration,
+      coverSlidePlayback
     }),
-    [doc, theme, videoPresentation, pipSize, pipShape, pipPosition, showCoverSlide]
+    [
+      doc,
+      theme,
+      videoPresentation,
+      pipSize,
+      pipShape,
+      pipPosition,
+      showCoverSlide,
+      coverSlideTemplate,
+      coverSlideDuration,
+      coverSlidePlayback
+    ]
   );
   const effectiveTheme = useMemo3(() => {
     const base = appearance.theme;
@@ -2018,7 +2071,7 @@ function DocPlayerContent({
     if (!appearance.showCoverSlide) return null;
     if (!startBlockConfig) return null;
     const context = createTemplateContext(effectiveTheme, 0, 1, activeViewport);
-    const layers = expandCoverBlock(startBlockConfig, context);
+    const layers = expandCoverBlock(startBlockConfig, context, appearance.coverSlideTemplate);
     return {
       id: "cover-block",
       startTime: -1,
@@ -2028,7 +2081,13 @@ function DocPlayerContent({
       audioSegment: -1,
       layers
     };
-  }, [doc.startBlock, activeViewport, effectiveTheme, appearance.showCoverSlide]);
+  }, [
+    doc.startBlock,
+    activeViewport,
+    effectiveTheme,
+    appearance.showCoverSlide,
+    appearance.coverSlideTemplate
+  ]);
   const hasManagedCover = !!coverBlock;
   const [slideshowCoverVisible, setSlideshowCoverVisible] = useState5(false);
   const [isSlideshowPickerOpen, setIsSlideshowPickerOpen] = useState5(false);
@@ -2066,9 +2125,12 @@ function DocPlayerContent({
       coverWasShowing.current = false;
       hasPlayedOnce.current = true;
       setCoverGraceActive(true);
-      coverGraceTimer.current = setTimeout(() => setCoverGraceActive(false), 3e3);
+      coverGraceTimer.current = setTimeout(
+        () => setCoverGraceActive(false),
+        appearance.coverSlideDuration * 1e3
+      );
     }
-  }, [isPlaying, coverBlock, renderMode, isSlideshowMode]);
+  }, [isPlaying, coverBlock, renderMode, isSlideshowMode, appearance.coverSlideDuration]);
   useEffect5(() => () => clearTimeout(coverGraceTimer.current), []);
   useEffect5(() => () => clearTimeout(tapFeedbackTimer.current), []);
   const showVideoCoverBlock = !isSlideshowMode && !isLinearMode && !!coverBlock && (coverForced || coverGraceActive || !isPlaying && currentTime === 0 && !hasPlayedOnce.current && !renderMode && !autoPlay);
@@ -2605,7 +2667,9 @@ function DocPlayerContent({
             viewport: activeViewport,
             theme,
             surface,
-            animationsEnabled
+            animationsEnabled,
+            showCodeCopyButton,
+            onCopyCode
           }
         )
       }

package/dist/{chunk-BOZJ655L.js → chunk-MVJQL2W2.js}

@@ -16,7 +16,7 @@ function useMediaSchedule(schedule, currentTime) {
 }
 
 // src/hooks/useAudioSync.ts
-import { useState, useEffect, useRef, useCallback } from "react";
+import { useState, useEffect, useMemo as useMemo2, useRef, useCallback } from "react";
 import { fetchResourceBytes, isResourceUrlAllowed } from "@bendyline/squisq/markdown";
 
 // src/hooks/AudioController.ts
@@ -61,7 +61,14 @@ function resolveAudioUrl(src, basePath) {
   if (!basePath) return src;
   return `${basePath.replace(/\/$/, "")}/${src.replace(/^\//, "")}`;
 }
-function useAudioSync(audioRef, audioTrack, basePath = "", enabled = true, mode = "media") {
+function useAudioSync(audioRef, track, basePath = "", enabled = true, mode = "media", syntheticDuration = 0) {
+  const audioTrack = useMemo2(() => {
+    if (mode !== "synthetic" || track?.segments?.length || syntheticDuration <= 0) return track;
+    return {
+      ...track,
+      segments: [{ src: "", name: "synthetic", duration: syntheticDuration, startTime: 0 }]
+    };
+  }, [track, mode, syntheticDuration]);
   const resourcePolicy = useResourcePolicy();
   const [currentTime, setCurrentTime] = useState(0);
   const [isPlaying, setIsPlaying] = useState(false);
@@ -468,7 +475,7 @@ function useAudioSync(audioRef, audioTrack, basePath = "", enabled = true, mode
 }
 
 // src/hooks/useDocPlayback.ts
-import { useMemo as useMemo2, useCallback as useCallback2, useRef as useRef2 } from "react";
+import { useMemo as useMemo3, useCallback as useCallback2, useRef as useRef2 } from "react";
 import {
   DEFAULT_THEME,
   getBlockAtTime,
@@ -489,7 +496,7 @@ function useDocPlayback(script, currentTime, options = {}) {
     onSeek,
     useAudioSegmentTiming = true
   } = options;
-  const blocks = useMemo2(() => {
+  const blocks = useMemo3(() => {
     if (!script?.blocks) {
       return [];
     }
@@ -532,20 +539,20 @@ function useDocPlayback(script, currentTime, options = {}) {
     theme,
     useAudioSegmentTiming
   ]);
-  const currentBlock = useMemo2(() => getBlockAtTime(blocks, currentTime), [blocks, currentTime]);
-  const currentBlockIndex = useMemo2(
+  const currentBlock = useMemo3(() => getBlockAtTime(blocks, currentTime), [blocks, currentTime]);
+  const currentBlockIndex = useMemo3(
     () => currentBlock ? blocks.indexOf(currentBlock) : -1,
     [blocks, currentBlock]
   );
-  const blockTime = useMemo2(() => {
+  const blockTime = useMemo3(() => {
     if (!currentBlock) return 0;
     return Math.max(0, currentTime - currentBlock.startTime);
   }, [currentBlock, currentTime]);
-  const blockProgress = useMemo2(() => {
+  const blockProgress = useMemo3(() => {
     if (!currentBlock || currentBlock.duration === 0) return 0;
     return Math.min(1, blockTime / currentBlock.duration);
   }, [currentBlock, blockTime]);
-  const docProgress = useMemo2(() => {
+  const docProgress = useMemo3(() => {
     if (!script || script.duration === 0) return 0;
     return Math.min(1, currentTime / script.duration);
   }, [script, currentTime]);
@@ -612,7 +619,7 @@ function useDocPlayback(script, currentTime, options = {}) {
 }
 
 // src/hooks/useViewportOrientation.ts
-import { useState as useState2, useEffect as useEffect2, useMemo as useMemo3 } from "react";
+import { useState as useState2, useEffect as useEffect2, useMemo as useMemo4 } from "react";
 import {
   VIEWPORT_PRESETS as VIEWPORT_PRESETS2
 } from "@bendyline/squisq/doc";
@@ -661,11 +668,11 @@ function useViewportOrientation() {
       clearTimeout(timeoutId);
     };
   }, []);
-  const orientation = useMemo3(
+  const orientation = useMemo4(
     () => getOrientationFromWindow(windowSize.width, windowSize.height),
     [windowSize.width, windowSize.height]
   );
-  const viewport = useMemo3(() => getViewportForOrientation(orientation), [orientation]);
+  const viewport = useMemo4(() => getViewportForOrientation(orientation), [orientation]);
   return {
     viewport,
     orientation,

package/dist/{chunk-VMPQEUJH.js → chunk-TMCLQNLM.js}

@@ -50,13 +50,72 @@ function InlineAudioPlayer({
 }
 
 // src/MarkdownRenderer.tsx
-import { Fragment } from "react";
+import { Fragment, useEffect, useRef, useState } from "react";
 import {
   sanitizeHtmlNodes,
   sanitizeUrl
 } from "@bendyline/squisq/markdown";
 import { jsx as jsx3, jsxs } from "react/jsx-runtime";
 var DEFAULT_CTX = { htmlPolicy: "sanitize" };
+var CODE_COPY_LABELS = {
+  idle: "Copy",
+  copying: "Copying\u2026",
+  copied: "Copied",
+  failed: "Copy failed"
+};
+async function writeCodeToClipboard(code, language, onCopyCode) {
+  if (onCopyCode) {
+    await onCopyCode(code, language === void 0 ? {} : { language });
+    return;
+  }
+  if (typeof navigator === "undefined" || !navigator.clipboard?.writeText) {
+    throw new Error("Clipboard access is unavailable in this host");
+  }
+  await navigator.clipboard.writeText(code);
+}
+function CodeBlock({
+  value,
+  language,
+  ctx
+}) {
+  const [status, setStatus] = useState("idle");
+  const resetTimer = useRef();
+  useEffect(
+    () => () => {
+      if (resetTimer.current !== void 0) clearTimeout(resetTimer.current);
+    },
+    []
+  );
+  const pre = /* @__PURE__ */ jsx3("pre", { className: "squisq-md-code-block", children: /* @__PURE__ */ jsx3("code", { className: language ? `language-${language}` : void 0, children: value }) });
+  if (!ctx.showCodeCopyButton) return pre;
+  const handleCopy = async () => {
+    if (status === "copying") return;
+    setStatus("copying");
+    try {
+      await writeCodeToClipboard(value, language ?? void 0, ctx.onCopyCode);
+      setStatus("copied");
+    } catch {
+      setStatus("failed");
+    }
+    if (resetTimer.current !== void 0) clearTimeout(resetTimer.current);
+    resetTimer.current = setTimeout(() => setStatus("idle"), 1600);
+  };
+  return /* @__PURE__ */ jsxs("div", { className: "squisq-md-code-frame", children: [
+    pre,
+    /* @__PURE__ */ jsx3(
+      "button",
+      {
+        type: "button",
+        className: "squisq-md-code-copy",
+        "data-copy-state": status,
+        disabled: status === "copying",
+        onClick: () => void handleCopy(),
+        "aria-label": "Copy code to clipboard",
+        children: CODE_COPY_LABELS[status]
+      }
+    )
+  ] });
+}
 function renderInline(nodes, keyPrefix = "", ctx = DEFAULT_CTX) {
   return nodes.map((node, i) => {
     const key = `${keyPrefix}i${i}`;
@@ -181,7 +240,7 @@ function renderBlock(node, key, ctx = DEFAULT_CTX) {
           key
         );
       }
-      return /* @__PURE__ */ jsx3("pre", { className: "squisq-md-code-block", children: /* @__PURE__ */ jsx3("code", { className: node.lang ? `language-${node.lang}` : void 0, children: node.value }) }, key);
+      return /* @__PURE__ */ jsx3(CodeBlock, { value: node.value, language: node.lang, ctx }, key);
     case "thematicBreak":
       return /* @__PURE__ */ jsx3("hr", { className: "squisq-md-hr" }, key);
     case "table":
@@ -393,10 +452,18 @@ function MarkdownRenderer({
   className,
   htmlPolicy = "sanitize",
   linkSchemes,
-  theme
+  theme,
+  showCodeCopyButton = false,
+  onCopyCode
 }) {
   if (!nodes || nodes.length === 0) return null;
-  return /* @__PURE__ */ jsx3("div", { className: `squisq-md ${className || ""}`, children: renderBlocks(nodes, "", { htmlPolicy, linkSchemes, theme }) });
+  return /* @__PURE__ */ jsx3("div", { className: `squisq-md ${className || ""}`, children: renderBlocks(nodes, "", {
+    htmlPolicy,
+    linkSchemes,
+    theme,
+    showCodeCopyButton,
+    onCopyCode
+  }) });
 }
 
 export {