feat: implement preview result handling and token management across components

Author: PierreRaybaut

CHANGELOG.md

@@ -12,8 +12,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
   can now render a temporary result while their parameters are edited. The
   preview is disabled by default, reuses the already-loaded computation worker
   without changing the workspace, supports bounded numeric sliders and
-  image-profile geometry, and is discarded on Cancel or Escape; OK still
-  performs the normal processing from the original source.
+  image-profile geometry, and is discarded on Cancel or Escape. For a single
+  source, OK reuses a completed current preview once; stale, running and
+  multi-selection previews fall back to normal processing.
 
 ### Changed
 

doc/architecture.md

@@ -275,9 +275,13 @@ from pickle, add_group, get/set selection, etc.).
 `ProcessingPreviewController` coordinates requests per `RuntimeApi`: one
 computation may run while a single pending slot retains only the latest
 parameters. `bootstrap.preview_feature` deep-copies the source and delegates
-to the same `BaseProcessor.apply` path as publication, then returns only a
-binary plotting payload. It never inserts the temporary object into `_MODEL`,
-updates processing history, or dirties the workspace.
+to the same `BaseProcessor.apply` path as publication, then returns a binary
+plotting payload. For a single-source dialog it also retains the complete raw
+result behind an opaque token. `apply_feature` consumes that result at most once
+after checking the feature, source data revision and parameters, then performs
+the usual publication and history updates. A missing, stale or mismatched token
+falls back to normal computation. Preview never inserts the temporary object
+into `_MODEL`, updates processing history, or dirties the workspace.
 
 Disabling preview, Cancel, Escape, or dialog unmount drops pending work and
 invalidates late results. A Python call that has already started is allowed to
@@ -484,9 +488,9 @@ compatibility independently of the application version.
 3. If params needed → ProcessingDataSetDialog (auto-generated from JSON schema)
 4. Optional Preview → runtime.previewFeature(featureId, sourceOid, paramValues)
 5. bootstrap deep-copies the source and returns a private plotting payload
-6. OK invalidates preview and calls runtime.applyFeature(featureId, selectedOids, paramValues)
-7. pyodide.runPython → processor.apply_*(feature, oids, params)
-8. Sigima computes; new SignalObj/ImageObj added to _MODEL
+6. OK detaches a current single-source preview token, if available, and calls runtime.applyFeature(featureId, selectedOids, paramValues, token)
+7. bootstrap consumes a matching result once, or calls processor.apply_*(feature, oids, params)
+8. The result is published as a new SignalObj/ImageObj in _MODEL
 9. bootstrap returns new oids; UI refreshes ObjectTree + plots
 10. WorkspaceContext is marked dirty
 ```

doc/userguide/computation-engine.md

@@ -48,11 +48,14 @@ batch operation.
 
 **Cancel** and **Esc** discard the temporary result and any waiting refresh.
 An already-running computation finishes in the background and its late result
-is ignored. **OK** runs the normal processing path from the original source
-and current parameters. Preview is hidden in the `runtime=main` fallback to
-avoid running this interactive work on the UI thread. The Processing tab in
-the object side panel retains its explicit **Apply** and **Reset** controls;
-editing that tab never republishes a result automatically.
+is ignored. With one source, **OK** consumes a completed, up-to-date preview
+once and publishes it through the normal processing path. A running or stale
+preview, a changed source, and multi-object or group selections fall back to
+normal computation from the original source and current parameters. Preview is
+hidden in the `runtime=main` fallback to avoid running this interactive work on
+the UI thread. The Processing tab in the object side panel retains its explicit
+**Apply** and **Reset** controls; editing that tab never republishes a result
+automatically.
 
 ## What the desktop docs do **not** cover
 

src/App.tsx

@@ -1511,8 +1511,16 @@ export default function App() {
       operandId: string | null,
       values: Record<string, unknown> | null,
       groupIds: string[] = [],
+      previewToken: string | null = null,
     ) => {
       if (!runtime) return;
+      const reusablePreviewToken =
+        previewToken !== null &&
+        feature.pattern === "1_to_1" &&
+        sourceIds.length === 1 &&
+        groupIds.length === 0
+          ? previewToken
+          : null;
       setBusy(true);
       try {
         // Cooperative cancellation: when a 1-to-1 / 2-to-1 feature is applied
@@ -1541,6 +1549,7 @@ export default function App() {
                 operandId,
                 values,
                 [],
+                null,
               ),
           });
           newIds = results.flat();
@@ -1564,6 +1573,7 @@ export default function App() {
                 operandId,
                 values,
                 groupIds,
+                reusablePreviewToken,
               ),
           });
           newIds = results[0] ?? [];
@@ -1589,6 +1599,11 @@ export default function App() {
           traceback: err instanceof Error ? err.message : String(err),
         });
       } finally {
+        if (previewToken !== null) {
+          await runtime
+            .releasePreviewResult(previewToken)
+            .catch(() => undefined);
+        }
         setBusy(false);
       }
     },
@@ -1844,21 +1859,41 @@ export default function App() {
   );
 
   const handleSubmitParams = useCallback(
-    async (values: Record<string, unknown>) => {
+    async (
+      values: Record<string, unknown>,
+      previewToken: string | null = null,
+    ) => {
       if (!pending) return;
       const { feature, sourceIds, operandId, groupIds } = pending;
       setPending(null);
-      await runFeature(feature, sourceIds, operandId, values, groupIds);
+      await runFeature(
+        feature,
+        sourceIds,
+        operandId,
+        values,
+        groupIds,
+        previewToken,
+      );
     },
     [pending, runFeature],
   );
 
   const handleSubmitProfile = useCallback(
-    async (values: Record<string, unknown>) => {
+    async (
+      values: Record<string, unknown>,
+      previewToken: string | null = null,
+    ) => {
       if (!pendingProfile) return;
       const { feature, sourceIds, groupIds } = pendingProfile;
       setPendingProfile(null);
-      await runFeature(feature, sourceIds, null, values, groupIds);
+      await runFeature(
+        feature,
+        sourceIds,
+        null,
+        values,
+        groupIds,
+        previewToken,
+      );
     },
     [pendingProfile, runFeature],
   );

src/components/ProcessingDataSetDialog.tsx

@@ -32,7 +32,10 @@ interface Props {
   resolveActive?: (
     currentValues: Record<string, unknown>,
   ) => Promise<Record<string, boolean>>;
-  onSubmit: (values: Record<string, unknown>) => void | Promise<void>;
+  onSubmit: (
+    values: Record<string, unknown>,
+    previewToken?: string | null,
+  ) => void | Promise<void>;
   onCancel: () => void;
 }
 
@@ -64,11 +67,12 @@ export function ProcessingDataSetDialog(props: Props) {
 
   const submit = async () => {
     if (!formState.valid || formState.resolving) return;
+    const previewToken = previewRef.current?.takeCurrentResult() ?? null;
     previewRef.current?.stop();
     setError(null);
     setSubmitting(true);
     try {
-      await onSubmit(values);
+      await onSubmit(values, previewToken);
     } catch (caught) {
       setError(caught instanceof Error ? caught.message : String(caught));
     } finally {

src/components/ProcessingPreview.tsx

@@ -38,6 +38,7 @@ interface Props {
 
 export interface ProcessingPreviewHandle {
   stop: () => void;
+  takeCurrentResult: () => string | null;
 }
 
 interface SourceOption {
@@ -91,7 +92,15 @@ export const ProcessingPreview = forwardRef<ProcessingPreviewHandle, Props>(
       controller.close();
     }, [controller]);
 
-    useImperativeHandle(ref, () => ({ stop }), [stop]);
+    const takeCurrentResult = useCallback(
+      () => controller.takeCurrentResult(),
+      [controller],
+    );
+
+    useImperativeHandle(ref, () => ({ stop, takeCurrentResult }), [
+      stop,
+      takeCurrentResult,
+    ]);
 
     useEffect(() => {
       let cancelled = false;
@@ -177,8 +186,17 @@ export const ProcessingPreview = forwardRef<ProcessingPreviewHandle, Props>(
         featureId: feature.id,
         sourceId,
         params: values,
+        reuseResult: sourceIds.length === 1,
       });
-    }, [controller, feature.id, resolving, sourceId, valid, values]);
+    }, [
+      controller,
+      feature.id,
+      resolving,
+      sourceId,
+      sourceIds.length,
+      valid,
+      values,
+    ]);
 
     useLayoutEffect(() => {
       requestPreviewRef.current = requestPreview;

src/components/ProfileDefinitionDialog.tsx

@@ -64,7 +64,10 @@ interface Props {
   resolveActive?: (
     currentValues: Record<string, unknown>,
   ) => Promise<Record<string, boolean>>;
-  onSubmit: (values: Record<string, unknown>) => void | Promise<void>;
+  onSubmit: (
+    values: Record<string, unknown>,
+    previewToken?: string | null,
+  ) => void | Promise<void>;
   onCancel: () => void;
 }
 
@@ -265,11 +268,12 @@ export function ProfileDefinitionDialog(props: Props) {
 
   const submit = async () => {
     if (!formState.valid || formState.resolving) return;
+    const previewToken = previewRef.current?.takeCurrentResult() ?? null;
     previewRef.current?.stop();
     setError(null);
     setSubmitting(true);
     try {
-      await onSubmit(values);
+      await onSubmit(values, previewToken);
     } catch (err) {
       setError(err instanceof Error ? err.message : String(err));
     } finally {

src/runtime/ProcessingPreviewController.ts

@@ -4,6 +4,7 @@ export interface ProcessingPreviewRequest {
   featureId: string;
   sourceId: string;
   params: Record<string, unknown>;
+  reuseResult?: boolean;
 }
 
 export type ProcessingPreviewState =
@@ -19,6 +20,13 @@ interface QueuedRequest extends ProcessingPreviewRequest {
   id: number;
   epoch: number;
   revision: number;
+  previewToken: string | null;
+}
+
+let nextPreviewToken = 1;
+
+function createPreviewToken(): string {
+  return `preview-${Date.now().toString(36)}-${nextPreviewToken++}`;
 }
 
 function cloneParams(values: Record<string, unknown>): Record<string, unknown> {
@@ -80,11 +88,18 @@ export class ProcessingPreviewController {
   private nextId = 1;
   private epoch = 0;
   private revision = 0;
+  private currentResult: Pick<
+    QueuedRequest,
+    "previewToken" | "epoch" | "revision"
+  > | null = null;
   private readonly coordinator: ProcessingPreviewCoordinator;
 
   constructor(
     private readonly onState: (state: ProcessingPreviewState) => void,
-    private readonly runtime: Pick<RuntimeApi, "previewFeature">,
+    private readonly runtime: Pick<
+      RuntimeApi,
+      "previewFeature" | "releasePreviewResult"
+    >,
   ) {
     this.coordinator = coordinatorFor(runtime as RuntimeApi);
   }
@@ -99,11 +114,13 @@ export class ProcessingPreviewController {
   }
 
   markDirty(): void {
+    this.releaseCurrentResult();
     this.revision += 1;
     this.coordinator.cancelPending(this);
   }
 
   invalidate(): void {
+    this.releaseCurrentResult();
     this.epoch += 1;
     this.revision += 1;
     this.coordinator.cancelPending(this);
@@ -115,6 +132,7 @@ export class ProcessingPreviewController {
 
   request(request: ProcessingPreviewRequest): void {
     if (!this.enabled) return;
+    this.releaseCurrentResult();
     if (this.targetSourceId !== request.sourceId) {
       this.epoch += 1;
       this.targetSourceId = request.sourceId;
@@ -126,6 +144,7 @@ export class ProcessingPreviewController {
       id: this.nextId++,
       epoch: this.epoch,
       revision: this.revision,
+      previewToken: request.reuseResult === false ? null : createPreviewToken(),
     };
     this.onState({ status: "computing" });
     this.coordinator.submit({
@@ -146,15 +165,26 @@ export class ProcessingPreviewController {
         request.featureId,
         request.sourceId,
         request.params,
+        request.previewToken,
       );
       const sameEpoch = this.enabled && request.epoch === this.epoch;
-      if (!sameEpoch) return;
+      if (!sameEpoch) {
+        this.releaseToken(request.previewToken);
+        return;
+      }
+      const current = request.revision === this.revision;
+      if (current && request.previewToken !== null) {
+        this.currentResult = request;
+      } else {
+        this.releaseToken(request.previewToken);
+      }
       this.onState({
         status: "result",
         result,
-        current: request.revision === this.revision,
+        current,
       });
     } catch (error) {
+      this.releaseToken(request.previewToken);
       const current =
         this.enabled &&
         request.epoch === this.epoch &&
@@ -177,9 +207,36 @@ export class ProcessingPreviewController {
   }
 
   private invalidateSession(): void {
+    this.releaseCurrentResult();
     this.epoch += 1;
     this.revision += 1;
     this.targetSourceId = null;
     this.coordinator.cancelPending(this);
   }
+
+  takeCurrentResult(): string | null {
+    const candidate = this.currentResult;
+    this.currentResult = null;
+    if (
+      !this.enabled ||
+      candidate === null ||
+      candidate.epoch !== this.epoch ||
+      candidate.revision !== this.revision
+    ) {
+      this.releaseToken(candidate?.previewToken ?? null);
+      return null;
+    }
+    return candidate.previewToken;
+  }
+
+  private releaseCurrentResult(): void {
+    const token = this.currentResult?.previewToken ?? null;
+    this.currentResult = null;
+    this.releaseToken(token);
+  }
+
+  private releaseToken(token: string | null): void {
+    if (token === null) return;
+    void this.runtime.releasePreviewResult(token).catch(() => undefined);
+  }
 }