Skip to content

CanvasAnvil is an open source AI diagram maker and flowchart generator - an infinite-canvas diagram editor and self-hosted drawio alternative that writes editable .drawio files. Text to diagram, then fix nodes, layout and labels in place. Also AI presentations, interior design CAD/BOM, posters and infographics.

refactor(ppt): drive the deck flows through a state machine

codingFeng101910af8cdbe78
diff --git a/client/workspaces/ppt/canvas/PptCanvas.tsx b/client/workspaces/ppt/canvas/PptCanvas.tsx
index d609740..eb511ca 100644
--- a/client/workspaces/ppt/canvas/PptCanvas.tsx
+++ b/client/workspaces/ppt/canvas/PptCanvas.tsx
@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useRef, useCallback } from 'react';
+import React, { useState, useEffect, useRef, useCallback, useReducer } from 'react';
import { motion } from "motion/react";
import { useLatestRef } from "@/shared/lib/use-latest-ref";
import { errorText, isRetryableBeautifyError } from "./lib/errors";
@@ -6,6 +6,12 @@ import { runInParallel, sleep } from "./lib/concurrency";
import { parseJsonLoose } from "./lib/parse-json";
import { extractPdfPagesAsImages, isPdfFile } from "./lib/deck-source";
import { getSlideshowDimensions } from "./lib/slideshow-size";
+import {
+ creationReducer,
+ initialCreationState,
+ isGenerating,
+ type CreationState,
+} from "./lib/creation-machine";
import { useTemplateLibrary } from "./hooks/use-template-library";
import { useSlideshow } from "./hooks/use-slideshow";
import { buildBeautifyInstruction } from "./lib/beautify-instruction";
@@ -81,7 +87,6 @@ import {
} from "@/workspaces/ppt/canvas/persisted-state";
import type {
CreationMode,
- CreationStep,
EditableExtractionStatus,
PptData,
ReferenceFile,
@@ -232,11 +237,15 @@ export function PptCanvas({
const [isExporting, setIsExporting] = useState<null | "pptx" | "pptx_editable" | "pdf">(null);
// Creation Wizard State
- const [creationStep, setCreationStep] = useState<CreationStep>(() => {
- const v = initialPptState?.creationStep;
- if (v === "idle" || v === "input" || v === "outline" || v === "done") return v;
- return localSlides.length > 0 ? "done" : "idle";
- });
+ const [creation, dispatchCreation] = useReducer(
+ creationReducer,
+ ((): CreationState => {
+ const v = initialPptState?.creationStep;
+ if (v === "idle" || v === "input" || v === "outline" || v === "done") return initialCreationState(v);
+ return initialCreationState(localSlides.length > 0 ? "done" : "idle");
+ })(),
+ );
+ const { step: creationStep, progress } = creation;
useEffect(() => {
if (creationStep === "done") {
onPptStageChange?.("slides");
@@ -310,7 +319,6 @@ export function PptCanvas({
const [materialPickerActiveIndex, setMaterialPickerActiveIndex] = useState(0);
const materialPickerReplaceRangeRef = useRef<Range | null>(null);
const materialPickerRef = useRef<HTMLDivElement | null>(null);
- const [progress, setProgress] = useState({ current: 0, total: 0, message: "" });
const referenceFileInputRef = useRef<HTMLInputElement | null>(null);
const beautifyFileInputRef = useRef<HTMLInputElement | null>(null);
const imageTransformFileInputRef = useRef<HTMLInputElement | null>(null);
@@ -475,16 +483,18 @@ export function PptCanvas({
),
);
setRenderLayers(nextRenderLayers);
- setCreationStep(
- coreState?.creationStep === "idle" ||
+ dispatchCreation({
+ type: "restored",
+ step:
+ coreState?.creationStep === "idle" ||
coreState?.creationStep === "input" ||
coreState?.creationStep === "outline" ||
coreState?.creationStep === "done"
- ? coreState.creationStep
- : nextSlides.length > 0
- ? "done"
- : "idle",
- );
+ ? coreState.creationStep
+ : nextSlides.length > 0
+ ? "done"
+ : "idle",
+ });
setCreationMode(
coreState?.creationMode === "idea" ||
coreState?.creationMode === "outline" ||
@@ -753,7 +763,7 @@ export function PptCanvas({
useEffect(() => {
if (data && data.slides && data.slides.length > 0) {
setSlidesKeepingSelection(data.slides);
- setCreationStep('done');
+ dispatchCreation({ type: "finished" });
onPptReadyChangeRef.current?.(true);
}
}, [data, onPptReadyChangeRef, setSlidesKeepingSelection]);
@@ -2202,7 +2212,8 @@ export function PptCanvas({
return zhLabel;
};
const setStage = (current: number, zhLabel: string, enLabel: string) => {
- setProgress({
+ dispatchCreation({
+ type: "progress",
current,
total: safeTotal,
message: localizeProgress(zhLabel, enLabel),
@@ -2705,7 +2716,6 @@ export function PptCanvas({
};
const resetGenerationState = () => {
- console.log("Resetting generation state...");
setGeneratedImages({});
setImageVersions({});
setCurrentImageVersionId({});
@@ -2719,7 +2729,8 @@ export function PptCanvas({
// extractPdfPagesAsImages counts pages; the wording stays here with tr.
const reportPdfParseProgress = useCallback((done: number, total: number) => {
- setProgress({
+ dispatchCreation({
+ type: "progress",
current: done,
total,
message: tr(`正在解析 PDF... (${done}/${total})`, `Parsing PDF... (${done}/${total})`),
@@ -2807,15 +2818,13 @@ export function PptCanvas({
resetGenerationState();
setBeautifyFailures({});
setImageTransformFailures({});
- setCreationStep("generating_content");
- setProgress({ current: 0, total: 0, message: tr("正在解析文件...", "Parsing file...") });
+ dispatchCreation({ type: "writing", message: tr("正在解析文件...", "Parsing file...") });
try {
const pageImages = await extractImageDeckPages(file);
if (pageImages.length === 0) {
alert(tr("无法解析页面图片,请确认文件格式。", "Failed to extract slide images. Please check the file format."));
- setCreationStep("idle");
- setProgress({ current: 0, total: 0, message: "" });
+ dispatchCreation({ type: "failed" });
return;
}
@@ -2827,7 +2836,7 @@ export function PptCanvas({
}));
setLocalSlides(slides);
- setCreationStep("generating_images");
+ dispatchCreation({ type: "rendering" });
const progressTracker = createTwoStageSlideProgressTracker(
slides.length,
@@ -2855,14 +2864,12 @@ export function PptCanvas({
});
await runInParallel(tasks, MODEL_CONCURRENCY);
- setCreationStep("done");
+ dispatchCreation({ type: "finished" });
onPptReadyChange?.(true);
} catch (error) {
console.error("Image PPT transform failed", error);
alert(getErrorMessage(error));
- setCreationStep("idle");
- } finally {
- setProgress({ current: 0, total: 0, message: "" });
+ dispatchCreation({ type: "failed" });
}
};
@@ -2905,8 +2912,7 @@ export function PptCanvas({
resetGenerationState();
setBeautifyFailures({});
- setCreationStep("generating_content");
- setProgress({ current: 0, total: 0, message: tr("正在解析文件...", "Parsing file...") });
+ dispatchCreation({ type: "writing", message: tr("正在解析文件...", "Parsing file...") });
try {
const pageImages = isPdfFile(file)
@@ -2915,8 +2921,7 @@ export function PptCanvas({
if (pageImages.length === 0) {
alert(tr("无法解析页面图片,请确认文件格式(仅支持 .pdf)。", "Failed to extract pages. Please upload a .pdf file."));
- setCreationStep("idle");
- setProgress({ current: 0, total: 0, message: "" });
+ dispatchCreation({ type: "failed" });
return;
}
@@ -2948,7 +2953,7 @@ export function PptCanvas({
setCurrentImageVersionId(initialCurrent);
setImageVersions(initialVersions);
- setCreationStep("generating_images");
+ dispatchCreation({ type: "rendering" });
const progressTracker = createTwoStageSlideProgressTracker(
slides.length,
"正在生成美化页图...",
@@ -2992,14 +2997,12 @@ export function PptCanvas({
});
await runInParallel(tasks, BEAUTIFY_CONCURRENCY);
- setCreationStep("done");
+ dispatchCreation({ type: "finished" });
onPptReadyChange?.(true);
} catch (e) {
console.error("Beautify failed", e);
alert(tr("美化失败,请重试", "Beautify failed. Please retry."));
- setCreationStep("idle");
- } finally {
- setProgress({ current: 0, total: 0, message: "" });
+ dispatchCreation({ type: "failed" });
}
};
@@ -3010,7 +3013,7 @@ export function PptCanvas({
.filter((id) => !!beautifyFailures[id]);
if (failedSlideIds.length === 0) return;
- setCreationStep("generating_images");
+ dispatchCreation({ type: "rendering" });
const progressTracker = createTwoStageSlideProgressTracker(
failedSlideIds.length,
"正在重试生成页图...",
@@ -3058,25 +3061,22 @@ export function PptCanvas({
});
await runInParallel(tasks, BEAUTIFY_CONCURRENCY);
- setCreationStep("done");
+ dispatchCreation({ type: "finished" });
onPptReadyChange?.(true);
} catch (e) {
console.error("Retry failed slides error", e);
alert(tr("重试失败页时出错,请重试。", "Retrying failed slides failed. Please try again."));
- setCreationStep("done");
- } finally {
- setProgress({ current: 0, total: 0, message: "" });
+ dispatchCreation({ type: "finished" });
}
};
const handleLoadOutline = async () => {
if (!outlineInput.trim()) return;
resetGenerationState();
- setCreationStep("input");
- setProgress({ current: 0, total: 0, message: tr("正在解析参考素材...", "Preparing reference assets...") });
+ dispatchCreation({ type: "preparing", message: tr("正在解析参考素材...", "Preparing reference assets...") });
try {
const referenceVisualAssets = await buildReferenceVisualAssetsWithCaptions();
- setProgress({ current: 0, total: 0, message: tr("正在生成计划...", "Generating plan...") });
+ dispatchCreation({ type: "progress", current: 0, total: 0, message: tr("正在生成计划...", "Generating plan...") });
const pages = await pptService.generatePlanFromOutline(
outlineInput,
uiLang as "zh" | "en",
@@ -3099,26 +3099,24 @@ export function PptCanvas({
const autoMaterial = buildSlideMaterialsFromAutoLabels(pages, slides, referenceVisualAssets);
setSlideMaterials(autoMaterial.nextMaterials);
setLocalSlides(autoMaterial.nextSlides);
- setCreationStep("outline");
+ dispatchCreation({ type: "outlined" });
onPptReadyChange?.(true);
} catch (e) {
console.error("Failed to build plan from outline", e);
alert(e instanceof Error ? e.message : tr("大纲转计划失败,请重试。", "Failed to build plan from outline. Please retry."));
- setCreationStep("idle");
- } finally {
- setProgress({ current: 0, total: 0, message: "" });
+ dispatchCreation({ type: "failed" });
}
};
const handleGenerateOutline = async () => {
if (!ideaInput.trim()) return;
resetGenerationState();
- setCreationStep('input'); // Keep input visible but loading
- setProgress({ current: 0, total: 0, message: tr("正在解析参考素材...", "Preparing reference assets...") });
+ // The input form stays up while the plan is being built.
+ dispatchCreation({ type: "preparing", message: tr("正在解析参考素材...", "Preparing reference assets...") });
try {
const referenceVisualAssets = await buildReferenceVisualAssetsWithCaptions();
- setProgress({ current: 0, total: 0, message: tr("正在生成大纲...", "Generating outline...") });
+ dispatchCreation({ type: "progress", current: 0, total: 0, message: tr("正在生成大纲...", "Generating outline...") });
const pages = await pptService.generateOutline(
ideaInput,
uiLang as "zh" | "en",
@@ -3144,7 +3142,7 @@ export function PptCanvas({
const autoMaterial = buildSlideMaterialsFromAutoLabels(pages, slides, referenceVisualAssets);
setSlideMaterials(autoMaterial.nextMaterials);
setLocalSlides(autoMaterial.nextSlides);
- setCreationStep('outline');
+ dispatchCreation({ type: "outlined" });
onPptReadyChange?.(true);
} catch (e) {
console.error("Failed to generate outline", e);
@@ -3156,14 +3154,12 @@ export function PptCanvas({
? e.message
: tr("生成大纲失败,请重试", "Failed to generate outline. Please retry.");
alert(msg);
- setCreationStep("idle");
- } finally {
- setProgress({ current: 0, total: 0, message: "" });
+ dispatchCreation({ type: "failed" });
}
};
const handleGenerateFullPpt = async () => {
- setCreationStep('generating_images');
+ dispatchCreation({ type: "rendering" });
// Convert SlideData back to PptPage for service
const pages: PptPage[] = localSlides.map(s => ({
@@ -3211,13 +3207,13 @@ export function PptCanvas({
await runInParallel(imageTasks, MODEL_CONCURRENCY);
- setCreationStep('done');
+ dispatchCreation({ type: "finished" });
onPptReadyChange?.(true);
} catch (e) {
console.error("Full generation failed", e);
alert(tr("生成过程中出错。", "An error occurred during generation."));
- setCreationStep('done'); // Allow viewing what's done
+ dispatchCreation({ type: "finished" }); // Show whatever did render
onPptReadyChange?.(true);
}
};
@@ -3496,7 +3492,7 @@ export function PptCanvas({
});
setLocalSlides([]);
resetGenerationState();
- setCreationStep("idle");
+ dispatchCreation({ type: "cleared" });
setIdeaInput("");
setOutlineInput("");
setBeautifyRequirement("");
@@ -3519,7 +3515,7 @@ export function PptCanvas({
setCurrentImageVersionId({});
setGeneratedImages({});
restoreTemplateSelection(null);
- setProgress({ current: 0, total: 0, message: "" });
+ dispatchCreation({ type: "progress", current: 0, total: 0, message: "" });
};
const handleBackToStart = () => {
@@ -3530,7 +3526,7 @@ export function PptCanvas({
setLocalSlides([]);
setSlideMaterials({});
resetGenerationState();
- setCreationStep("idle");
+ dispatchCreation({ type: "cleared" });
};
const createOutlineSlide = (displayIndex: number): SlideData => ({
id: `slide-${Date.now()}-${Math.random().toString(16).slice(2)}`,
@@ -4369,7 +4365,7 @@ export function PptCanvas({
}
// Render Progress
- if (creationStep === 'generating_content' || creationStep === 'generating_images') {
+ if (isGenerating(creationStep)) {
const progressRatio = progress.total > 0 ? progress.current / progress.total : 0;
const clampedRatio = Math.max(0, Math.min(1, progressRatio));
const dash = clampedRatio * 251.2;
diff --git a/client/workspaces/ppt/canvas/lib/creation-machine.ts b/client/workspaces/ppt/canvas/lib/creation-machine.ts
new file mode 100644
index 0000000..0ee7735
--- /dev/null
+++ b/client/workspaces/ppt/canvas/lib/creation-machine.ts
@@ -0,0 +1,96 @@
+import type { CreationStep } from "@/workspaces/ppt/canvas/types";
+
+export interface CreationProgress {
+ current: number;
+ total: number;
+ message: string;
+}
+
+export interface CreationState {
+ step: CreationStep;
+ progress: CreationProgress;
+}
+
+/**
+ * What happened, rather than which state to enter.
+ *
+ * Six flows drive the deck through the same shape -- prepare, write, render,
+ * finish or fail -- and each used to set the step and the progress bar as two
+ * separate calls. Pairing them here is what stops the two from drifting: a
+ * finished deck cannot be left showing a progress message, which is what the
+ * one flow missing a `finally` used to do.
+ */
+export type CreationEvent =
+ /** A stored workspace was loaded; resume where the user left off. */
+ | { type: "restored"; step: CreationStep }
+ /** A flow started. The input form stays up, showing this message. */
+ | { type: "preparing"; message: string }
+ /** A plan is ready for the user to review before rendering. */
+ | { type: "outlined" }
+ /** Slide text is being written. */
+ | { type: "writing"; message: string }
+ /** Slide images are being generated; the tracker owns the message from here. */
+ | { type: "rendering"; message?: string }
+ /** The deck is ready to show -- including when some slides failed. */
+ | { type: "finished" }
+ /** The flow gave up; go back to the start screen. */
+ | { type: "failed" }
+ /** The user started over. */
+ | { type: "cleared" }
+ /** Progress within the current step. */
+ | { type: "progress"; current: number; total: number; message: string };
+
+const NO_PROGRESS: CreationProgress = { current: 0, total: 0, message: "" };
+
+export const initialCreationState = (step: CreationStep = "idle"): CreationState => ({
+ step,
+ progress: NO_PROGRESS,
+});
+
+export function creationReducer(state: CreationState, event: CreationEvent): CreationState {
+ switch (event.type) {
+ case "restored":
+ return { step: event.step, progress: NO_PROGRESS };
+
+ case "preparing":
+ return { step: "input", progress: { current: 0, total: 0, message: event.message } };
+
+ case "outlined":
+ return { step: "outline", progress: NO_PROGRESS };
+
+ case "writing":
+ return {
+ step: "generating_content",
+ progress: { current: 0, total: 0, message: event.message },
+ };
+
+ case "rendering":
+ return {
+ step: "generating_images",
+ // Without a message of its own, whatever the caller's progress tracker
+ // has already reported stays on screen.
+ progress: event.message ? { current: 0, total: 0, message: event.message } : state.progress,
+ };
+
+ case "finished":
+ return { step: "done", progress: NO_PROGRESS };
+
+ case "failed":
+ case "cleared":
+ return { step: "idle", progress: NO_PROGRESS };
+
+ case "progress":
+ return {
+ step: state.step,
+ progress: { current: event.current, total: event.total, message: event.message },
+ };
+
+ default:
+ return state;
+ }
+}
+
+/** The steps that put the canvas into its full-screen progress view. */
+export function isGenerating(step: CreationStep): boolean {
+ return step === "generating_content" || step === "generating_images";
+}
diff --git a/tests/ppt-creation-machine.test.ts b/tests/ppt-creation-machine.test.ts
new file mode 100644
index 0000000..e6fdfd4
--- /dev/null
+++ b/tests/ppt-creation-machine.test.ts
@@ -0,0 +1,123 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+ creationReducer,
+ initialCreationState,
+ isGenerating,
+ type CreationEvent,
+ type CreationState,
+} from "../client/workspaces/ppt/canvas/lib/creation-machine";
+
+/**
+ * The state machine behind the deck-building flows. Which step the canvas is
+ * in decides which whole screen the user sees, so a wrong transition here is
+ * not a cosmetic bug -- it strands the user on a progress bar or throws away
+ * a finished deck.
+ */
+
+const run = (events: CreationEvent[], from: CreationState = initialCreationState()) =>
+ events.reduce(creationReducer, from);
+
+const NO_PROGRESS = { current: 0, total: 0, message: "" };
+
+test("a fresh workspace starts idle with no progress", () => {
+ assert.deepEqual(initialCreationState(), { step: "idle", progress: NO_PROGRESS });
+});
+
+test("a restored workspace resumes at its stored step", () => {
+ assert.equal(run([{ type: "restored", step: "outline" }]).step, "outline");
+ assert.equal(run([{ type: "restored", step: "done" }]).step, "done");
+});
+
+test("a restore never brings back a stale progress bar", () => {
+ const mid = run([{ type: "writing", message: "half way" }]);
+ assert.deepEqual(creationReducer(mid, { type: "restored", step: "done" }).progress, NO_PROGRESS);
+});
+
+test("the outline flow walks input to outline to done", () => {
+ const steps = [
+ { type: "preparing", message: "reading files" },
+ { type: "outlined" },
+ { type: "rendering" },
+ { type: "finished" },
+ ] as CreationEvent[];
+
+ const seen = steps.reduce<string[]>((acc, event, i) => {
+ acc.push(run(steps.slice(0, i + 1)).step);
+ return acc;
+ }, []);
+ assert.deepEqual(seen, ["input", "outline", "generating_images", "done"]);
+});
+
+test("preparing keeps the user on the input form with a message", () => {
+ const state = run([{ type: "preparing", message: "正在解析参考素材..." }]);
+ assert.equal(state.step, "input", "the form stays up while the plan is built");
+ assert.equal(state.progress.message, "正在解析参考素材...");
+});
+
+test("a finished deck never shows a progress message", () => {
+ // The flow that lacked a `finally` used to leave one on screen, which
+ // disabled the retry button on the deck view.
+ const mid = run([
+ { type: "rendering" },
+ { type: "progress", current: 4, total: 9, message: "Rendering images..." },
+ ]);
+ assert.equal(mid.progress.message, "Rendering images...");
+ assert.deepEqual(creationReducer(mid, { type: "finished" }).progress, NO_PROGRESS);
+});
+
+test("a failure returns to the start screen and clears progress", () => {
+ const mid = run([{ type: "writing", message: "Parsing file..." }]);
+ const failed = creationReducer(mid, { type: "failed" });
+ assert.equal(failed.step, "idle");
+ assert.deepEqual(failed.progress, NO_PROGRESS);
+});
+
+test("starting over clears everything", () => {
+ const mid = run([{ type: "rendering" }, { type: "progress", current: 2, total: 5, message: "x" }]);
+ assert.deepEqual(creationReducer(mid, { type: "cleared" }), {
+ step: "idle",
+ progress: NO_PROGRESS,
+ });
+});
+
+test("rendering keeps whatever the progress tracker already reported", () => {
+ // The image flows hand the bar to a two-stage tracker before entering this
+ // step; clearing here would blank a bar that is already counting.
+ const mid = run([{ type: "progress", current: 3, total: 10, message: "Generating..." }]);
+ const rendering = creationReducer(mid, { type: "rendering" });
+ assert.equal(rendering.step, "generating_images");
+ assert.deepEqual(rendering.progress, { current: 3, total: 10, message: "Generating..." });
+});
+
+test("rendering with its own message replaces the bar", () => {
+ const mid = run([{ type: "progress", current: 3, total: 10, message: "old" }]);
+ assert.deepEqual(creationReducer(mid, { type: "rendering", message: "new" }).progress, {
+ current: 0,
+ total: 0,
+ message: "new",
+ });
+});
+
+test("progress updates never move the step", () => {
+ const mid = run([{ type: "writing", message: "start" }]);
+ const stepped = creationReducer(mid, { type: "progress", current: 1, total: 3, message: "1/3" });
+ assert.equal(stepped.step, "generating_content");
+ assert.deepEqual(stepped.progress, { current: 1, total: 3, message: "1/3" });
+});
+
+test("the reducer never mutates the state it was given", () => {
+ const before = initialCreationState("outline");
+ const snapshot = JSON.parse(JSON.stringify(before));
+ creationReducer(before, { type: "finished" });
+ assert.deepEqual(before, snapshot);
+});
+
+test("isGenerating covers exactly the two full-screen progress steps", () => {
+ assert.equal(isGenerating("generating_content"), true);
+ assert.equal(isGenerating("generating_images"), true);
+ assert.equal(isGenerating("idle"), false);
+ assert.equal(isGenerating("input"), false);
+ assert.equal(isGenerating("outline"), false);
+ assert.equal(isGenerating("done"), false);
+});