Improve onboarding scaffold & demo choices

Refactor onboarding scaffolding and add a read-only onboarding demo for choices.

Key changes:
- Moved onboarding scaffold startup out of App.jsx and into SidebarEditor/useStoryState.
- useStoryState: refactored ensureOnboardingScaffold to use a selectedNodeId ref, more robust target selection, seed demo choices, and set selection after nodes update.
- SidebarEditor: triggers scaffold creation for onboarding steps and shows a read-only demo node when no node is selected during the choices tour.
- ChoicesEditor & ChoiceRow: support a readOnly demo preview (hides add/remove/edit controls and shows explanatory hint).
- onboardingDemo.js: added ONBOARDING_DEMO_NODE and helper functions.

Files changed: src/App.jsx, src/hooks/useStoryState.js, src/components/editor/SidebarEditor.jsx, src/components/editor/ChoicesEditor.jsx, src/components/editor/ChoiceRow.jsx, src/data/onboardingDemo.js

This makes the onboarding tour reliably display example choices without modifying real story data.

Author: monapdx

src/App.jsx

@@ -1,4 +1,4 @@
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import StoryCanvas from "./components/canvas/StoryCanvas";
 import SidebarEditor from "./components/editor/SidebarEditor";
 import VariablesScreen from "./components/editor/VariablesScreen";
@@ -108,23 +108,6 @@ function EditorApp() {
     return () => window.clearTimeout(timerId);
   }, [activeScreen, onboarding.shouldAutoStart, onboarding.start]);
 
-  useLayoutEffect(() => {
-    if (!onboarding.isActive || activeScreen !== "editor") return;
-
-    const stepId = onboarding.step?.id;
-    if (stepId === "sidebar") {
-      story.ensureOnboardingScaffold({ seedChoices: false });
-    }
-    if (stepId === "choices" || stepId === "choice-expand") {
-      story.ensureOnboardingScaffold({ seedChoices: true });
-    }
-  }, [
-    onboarding.isActive,
-    onboarding.step?.id,
-    activeScreen,
-    story.ensureOnboardingScaffold,
-  ]);
-
   const selectedMiniGame = useMemo(() => {
     if (!story.selectedNode || !isSupportedMiniGameBlock(story.selectedNode)) {
       return null;

src/components/editor/ChoiceRow.jsx

@@ -20,6 +20,7 @@ export default function ChoiceRow({
   highlightChevron = false,
   revealOnboarding = false,
   revealDelayMs = 0,
+  readOnly = false,
   onExpand,
   onUpdate,
   onRemove,
@@ -100,6 +101,13 @@ export default function ChoiceRow({
 
       {isExpanded && (
         <>
+          {readOnly ? (
+            <p className="sidebar-hint" style={{ marginTop: 8 }}>
+              This is where you edit the choice label, target block, conditions, and
+              effects.
+            </p>
+          ) : (
+            <>
           {isChatBlock && (
             <div className="form-group">
               <label className="form-label">Choice Type</label>
@@ -216,13 +224,17 @@ export default function ChoiceRow({
             onUpdate={(field, value) => onUpdate(choiceIndex, field, value)}
           />
 
-          <button
-            type="button"
-            className="danger-button"
-            onClick={() => onRemove(choiceIndex)}
-          >
-            Remove Choice
-          </button>
+          {!readOnly && (
+            <button
+              type="button"
+              className="danger-button"
+              onClick={() => onRemove(choiceIndex)}
+            >
+              Remove Choice
+            </button>
+          )}
+            </>
+          )}
         </>
       )}
     </div>

src/components/editor/ChoicesEditor.jsx

@@ -1,26 +1,40 @@
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import ChoiceRow from "./ChoiceRow";
+import {
+  ONBOARDING_DEMO_CHOICES,
+  isOnboardingChoiceStep,
+} from "../../data/onboardingDemo";
 
 export default function ChoicesEditor({
   selectedNode,
   nodes,
   variables,
   characters = [],
   onboardingStepId = null,
+  isOnboardingDemoPreview = false,
   addChoiceToSelectedNode,
   updateChoiceOnSelectedNode,
   removeChoiceFromSelectedNode,
 }) {
-  const choices = selectedNode?.data?.choices || [];
   const blockType = selectedNode?.data?.blockType || "narrative";
   const selectedNodeId = selectedNode?.id;
+  const storyChoices = selectedNode?.data?.choices || [];
+  const showOnboardingChoiceDemo = isOnboardingChoiceStep(onboardingStepId);
+  const visibleChoices = useMemo(() => {
+    if (showOnboardingChoiceDemo && storyChoices.length === 0) {
+      return ONBOARDING_DEMO_CHOICES;
+    }
+    return storyChoices;
+  }, [showOnboardingChoiceDemo, storyChoices]);
+  const readOnly = isOnboardingDemoPreview;
+
   const [expandedChoiceIndex, setExpandedChoiceIndex] = useState(null);
   const showChoiceReveal = onboardingStepId === "choices";
   const highlightChoiceChevron = onboardingStepId === "choice-expand";
 
   useEffect(() => {
     setExpandedChoiceIndex(null);
-  }, [selectedNodeId, blockType]);
+  }, [selectedNodeId, blockType, onboardingStepId]);
 
   useEffect(() => {
     if (!highlightChoiceChevron) return;
@@ -33,13 +47,13 @@ export default function ChoicesEditor({
     });
 
     return () => window.cancelAnimationFrame(frameId);
-  }, [highlightChoiceChevron, choices.length]);
+  }, [highlightChoiceChevron, visibleChoices.length]);
 
   useEffect(() => {
-    if (expandedChoiceIndex !== null && expandedChoiceIndex >= choices.length) {
+    if (expandedChoiceIndex !== null && expandedChoiceIndex >= visibleChoices.length) {
       setExpandedChoiceIndex(null);
     }
-  }, [choices.length, expandedChoiceIndex]);
+  }, [visibleChoices.length, expandedChoiceIndex]);
 
   function handleChoiceExpand(index) {
     setExpandedChoiceIndex((current) => (current === index ? null : index));
@@ -49,16 +63,18 @@ export default function ChoicesEditor({
     <div className="editor-section">
       <div className="editor-section-header">
         <h3 className="section-title">Choices</h3>
-        <button className="toolbar-button" onClick={addChoiceToSelectedNode}>
-          + Add Choice
-        </button>
+        {!readOnly && (
+          <button className="toolbar-button" onClick={addChoiceToSelectedNode}>
+            + Add Choice
+          </button>
+        )}
       </div>
 
-      {choices.length === 0 ? (
+      {visibleChoices.length === 0 ? (
         <p className="sidebar-hint">No choices yet.</p>
       ) : (
         <div className="choice-list">
-          {choices.map((choice, index) => (
+          {visibleChoices.map((choice, index) => (
             <ChoiceRow
               key={`${selectedNode.id}-choice-${index}`}
               choiceIndex={index}
@@ -72,13 +88,14 @@ export default function ChoicesEditor({
               highlightChevron={highlightChoiceChevron && index === 0}
               revealOnboarding={showChoiceReveal}
               revealDelayMs={index * 180}
+              readOnly={readOnly}
               onExpand={() => handleChoiceExpand(index)}
-              onUpdate={updateChoiceOnSelectedNode}
-              onRemove={removeChoiceFromSelectedNode}
+              onUpdate={readOnly ? undefined : updateChoiceOnSelectedNode}
+              onRemove={readOnly ? undefined : removeChoiceFromSelectedNode}
             />
           ))}
         </div>
       )}
     </div>
   );
-}
+}

src/components/editor/SidebarEditor.jsx

@@ -1,14 +1,19 @@
-import { useEffect, useState } from "react";
+import { useEffect, useLayoutEffect, useState } from "react";
 import ChoicesEditor from "./ChoicesEditor";
 import StoryDiagnostics from "./StoryDiagnostics";
 import ReferenceTextarea from "./ReferenceTextarea";
+import {
+  ONBOARDING_DEMO_NODE,
+  isOnboardingChoiceStep,
+} from "../../data/onboardingDemo";
 
 export default function SidebarEditor({
   nodes,
   variables,
   characters = [],
   selectedNode,
   onboardingStepId = null,
+  ensureOnboardingScaffold,
   updateSelectedNodeField,
   deleteSelectedNode,
   addChoiceToSelectedNode,
@@ -18,12 +23,54 @@ export default function SidebarEditor({
   onOpenVariables,
 }) {
   const [isNarrativeContentOpen, setIsNarrativeContentOpen] = useState(false);
+  const showOnboardingChoiceDemo = isOnboardingChoiceStep(onboardingStepId);
+
+  useLayoutEffect(() => {
+    if (!ensureOnboardingScaffold || !onboardingStepId) return;
+
+    if (onboardingStepId === "sidebar") {
+      ensureOnboardingScaffold({ seedChoices: false });
+      return;
+    }
+
+    if (isOnboardingChoiceStep(onboardingStepId)) {
+      ensureOnboardingScaffold({ seedChoices: true });
+    }
+  }, [ensureOnboardingScaffold, onboardingStepId]);
+
+  useEffect(() => {
+    if (!ensureOnboardingScaffold || !isOnboardingChoiceStep(onboardingStepId)) return;
+    ensureOnboardingScaffold({ seedChoices: true });
+  }, [ensureOnboardingScaffold, onboardingStepId, selectedNode?.id]);
 
   useEffect(() => {
     setIsNarrativeContentOpen(false);
   }, [selectedNode?.id]);
 
   if (!selectedNode) {
+    if (showOnboardingChoiceDemo) {
+      return (
+        <div>
+          <h2 className="section-title">Block Editor</h2>
+          <p className="sidebar-hint">Tutorial Scene — example choices below.</p>
+
+          <div data-onboarding="choices">
+            <ChoicesEditor
+              selectedNode={ONBOARDING_DEMO_NODE}
+              nodes={nodes}
+              variables={variables}
+              characters={characters}
+              onboardingStepId={onboardingStepId}
+              isOnboardingDemoPreview
+              addChoiceToSelectedNode={addChoiceToSelectedNode}
+              updateChoiceOnSelectedNode={updateChoiceOnSelectedNode}
+              removeChoiceFromSelectedNode={removeChoiceFromSelectedNode}
+            />
+          </div>
+        </div>
+      );
+    }
+
     return (
       <div>
         <h2 className="section-title">Block Editor</h2>

src/data/onboardingDemo.js

@@ -15,3 +15,21 @@ export const ONBOARDING_DEMO_CHOICES = [
     effects: [],
   },
 ];
+
+export const ONBOARDING_DEMO_NODE = {
+  id: ONBOARDING_SCAFFOLD_NODE_ID,
+  data: {
+    title: "Tutorial Scene",
+    blockType: "narrative",
+    choices: ONBOARDING_DEMO_CHOICES,
+  },
+};
+
+/** Tour steps that need example choices visible in the sidebar. */
+export function isOnboardingChoiceStep(stepId) {
+  return stepId === "choices" || stepId === "choice-expand";
+}
+
+export function isOnboardingSidebarStep(stepId) {
+  return stepId === "sidebar" || isOnboardingChoiceStep(stepId);
+}

src/hooks/useStoryState.js

@@ -1,4 +1,4 @@
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import { cloneDemoStoryById, DEMO_STORIES } from "../data/demoStoriesCatalog";
 import {
   ONBOARDING_DEMO_CHOICES,
@@ -70,6 +70,8 @@ export default function useStoryState() {
   const [variables, setVariables] = useState(initial.variables);
   const [characters, setCharacters] = useState(initial.characters);
   const [selectedNodeId, setSelectedNodeId] = useState(null);
+  const selectedNodeIdRef = useRef(selectedNodeId);
+  selectedNodeIdRef.current = selectedNodeId;
 
   const [storyBaselineSignature, setStoryBaselineSignature] = useState(() =>
     stableDemoSignature(initial.nodes, initial.variables, initial.characters)
@@ -383,57 +385,69 @@ export default function useStoryState() {
   }
 
   const ensureOnboardingScaffold = useCallback(({ seedChoices = false } = {}) => {
-    let targetId = null;
+    let targetIdToSelect = null;
 
     setNodes((prev) => {
       let next = [...prev];
 
-      let targetNode = next.find(
-        (node) =>
-          node.id === ONBOARDING_SCAFFOLD_NODE_ID || node.data?.isOnboardingScaffold
-      );
+      let targetId =
+        selectedNodeIdRef.current &&
+        next.some((node) => node.id === selectedNodeIdRef.current)
+          ? selectedNodeIdRef.current
+          : null;
 
-      if (!targetNode && next.length === 0) {
-        targetNode = {
-          id: ONBOARDING_SCAFFOLD_NODE_ID,
-          type: "storyNode",
-          position: { x: 260, y: 120 },
-          data: {
-            title: "Tutorial Scene",
-            content: "Write what the player reads when they reach this scene.",
-            blockType: "narrative",
-            choices: [],
-            isOnboardingScaffold: true,
-            enterEffects: [],
-            graphIssues: [],
-          },
-        };
-        next.push(targetNode);
-      } else if (!targetNode) {
-        targetNode = next[0];
-      }
+      if (!targetId) {
+        const existingScaffold = next.find(
+          (node) =>
+            node.id === ONBOARDING_SCAFFOLD_NODE_ID || node.data?.isOnboardingScaffold
+        );
 
-      targetId = targetNode.id;
+        if (existingScaffold) {
+          targetId = existingScaffold.id;
+        } else if (next.length === 0) {
+          const scaffold = {
+            id: ONBOARDING_SCAFFOLD_NODE_ID,
+            type: "storyNode",
+            position: { x: 260, y: 120 },
+            data: {
+              title: "Tutorial Scene",
+              content: "Write what the player reads when they reach this scene.",
+              blockType: "narrative",
+              choices: [],
+              isOnboardingScaffold: true,
+              enterEffects: [],
+              graphIssues: [],
+            },
+          };
+          next = [...next, scaffold];
+          targetId = scaffold.id;
+        } else {
+          targetId = next[0]?.id || null;
+        }
+      }
 
-      if (seedChoices && (targetNode.data?.choices || []).length === 0) {
+      if (seedChoices && targetId) {
+        const demoChoices = ONBOARDING_DEMO_CHOICES.map((choice) => ({ ...choice }));
         next = next.map((node) =>
           node.id === targetId
             ? {
                 ...node,
                 data: {
                   ...node.data,
-                  choices: ONBOARDING_DEMO_CHOICES.map((choice) => ({ ...choice })),
+                  blockType: node.data?.blockType || "narrative",
+                  choices: demoChoices,
                 },
               }
             : node
         );
       }
 
+      targetIdToSelect = targetId;
       return next;
     });
 
-    if (targetId) {
-      setSelectedNodeId(targetId);
+    if (targetIdToSelect) {
+      setSelectedNodeId(targetIdToSelect);
     }
   }, []);