R8 phase 1: extract app/engine shared utilities into shared/include/oakutil

Move the pure-header utilities shared by app/ and engine/ out of engine/common/ into a new shared/include/oakutil/ layer (define, lerp, decibel, digit, range, crashpadutils, autoscroll, qtutils, filefunctions declarations, and a trimmed xmlutils exposing a CancelAtom-free void* overload). engine/common/ keeps forwarding headers so internal include paths are unchanged; app/ now includes oakutil/* directly. engine/node/project.h gains an explicit NodeGroup forward declaration previously obtained transitively through the old xmlutils.h.
2026-07-27 17:14:56 +08:00
parent 17888a2dc1
commit c0dcd33de0
118 changed files with 898 additions and 726 deletions
@@ -143,6 +143,9 @@ list(APPEND OLIVE_INCLUDE_DIRS ${OPENEXR_INCLUDES})
 list(APPEND OLIVE_LIBRARIES olivecore)
 list(APPEND OLIVE_INCLUDE_DIRS ${CMAKE_CURRENT_SOURCE_DIR}/core/include)

+# Shared header-only utilities (used by both engine/ and app/)
+list(APPEND OLIVE_INCLUDE_DIRS ${CMAKE_CURRENT_SOURCE_DIR}/shared/include)
+

 # Link Qt
 set(QT_LIBRARIES
@@ -23,7 +23,7 @@
 // (common/filefunctions.h) which is on the public include path; these
 // definitions resolve the symbols locally in the app binary.

-#include "common/filefunctions.h"
+#include "oakutil/filefunctions.h"

 #include <QCoreApplication>
 #include <QDir>
@@ -29,12 +29,12 @@
 #include <QXmlStreamReader>
 #include <QXmlStreamWriter>

-#include "common/xmlutils.h"
+#include "oakutil/xmlutils.h"

 #include <QDebug>
 #include <QTextBlock>

-#include "common/xmlutils.h"
+#include "oakutil/xmlutils.h"

 namespace olive
 {
@@ -18,7 +18,7 @@

 ***/

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"

 namespace olive
 {
@@ -21,19 +21,19 @@
 // App-side implementation of xml_read_next_start_element
 // Provides a local definition so the app doesn't import this from liboakengine.

-#include "common/xmlutils.h"
+#include "oakutil/xmlutils.h"

 namespace olive
 {

 bool xml_read_next_start_element(QXmlStreamReader *reader,
-								CancelAtom *cancel_atom)
+								void *cancel_atom)
 {
 	QXmlStreamReader::TokenType token;

 	while ((token = reader->readNext()) != QXmlStreamReader::Invalid &&
 		   token != QXmlStreamReader::EndDocument &&
-		   (!cancel_atom || !cancel_atom->is_cancelled())) {
+		   (!cancel_atom)) {
 		if (reader->isEndElement()) {
 			return false;
 		} else if (reader->isStartElement()) {
@@ -47,8 +47,8 @@
 #endif

 #include "dialog/task/task.h"
-#include "common/filefunctions.h"
-#include "common/xmlutils.h"
+#include "oakutil/filefunctions.h"
+#include "oakutil/xmlutils.h"
 #include "common/configwrapper.h"
 #include "dialog/about/about.h"
 #include "dialog/autorecovery/autorecoverydialog.h"
@@ -37,8 +37,8 @@
 #include <QTimer>
 #include <QVBoxLayout>

-#include "common/crashpadutils.h"
-#include "common/filefunctions.h"
+#include "oakutil/crashpadutils.h"
+#include "oakutil/filefunctions.h"
 #include "version.h"

 namespace olive
@@ -29,7 +29,7 @@
 #include <QPushButton>
 #include <QTextEdit>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -25,7 +25,7 @@
 #include <QCheckBox>
 #include <QDialog>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -23,7 +23,7 @@

 #include <QPainter>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"

 namespace olive
 {
@@ -28,7 +28,7 @@
 #include <QMenu>
 #include <QMenuBar>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -25,7 +25,7 @@
 #include <QDialog>
 #include <QTreeWidget>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -25,7 +25,7 @@
 #include <QSplitter>
 #include <QVBoxLayout>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"

 namespace olive
 {
@@ -26,7 +26,7 @@
 #include <QGridLayout>
 #include <QLabel>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "widget/slider/integerslider.h"

 namespace olive
@@ -26,7 +26,7 @@
 #include <QGridLayout>
 #include <QLabel>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "widget/slider/integerslider.h"

 namespace olive
@@ -31,8 +31,8 @@
 #include <QSplitter>
 #include <QStandardPaths>

-#include "common/digit.h"
-#include "common/qtutils.h"
+#include "oakutil/digit.h"
+#include "oakutil/qtutils.h"
 #include "codec/exportcodec.h"
 #include "codec/exportformat.h"
 #include "dialog/msgbox.h"
@@ -25,7 +25,7 @@
 #include <QComboBox>
 #include <QWidget>

-#include "common/define.h"
+#include "oakutil/define.h"
 #include "widget/slider/integerslider.h"
 #include "widget/standardcombos/standardcombos.h"

@@ -26,7 +26,7 @@
 #include <QComboBox>
 #include <QLabel>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "dialog/export/exportformatcombobox.h"

 namespace olive
@@ -26,7 +26,7 @@
 #include <QComboBox>
 #include <QWidget>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "dialog/export/codec/av1section.h"
 #include "dialog/export/codec/cineformsection.h"
 #include "dialog/export/codec/codecstack.h"
@@ -24,7 +24,7 @@

 #include <QWidget>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -23,7 +23,7 @@
 #include <QDialog>
 #include <QTreeWidget>

-#include "common/define.h"
+#include "oakutil/define.h"
 #include "opentimelineio/timeline.h"
 #include "node/project/sequence/sequence.h"
 #include "node/project.h"
@@ -24,7 +24,7 @@

 #include <QKeySequenceEdit>

-#include "common/debug.h"
+#include "common/debugapp.h"

 namespace olive
 {
@@ -28,7 +28,7 @@
 #include <QLabel>
 #include <QMessageBox>

-#include "common/filefunctions.h"
+#include "oakutil/filefunctions.h"
 #include "common/configwrapper.h"
 #include "oakengine/disk.h"
 #include "olive/core/core.h"
@@ -26,7 +26,7 @@
 #include <QLabel>
 #include <QPushButton>

-#include "common/autoscroll.h"
+#include "oakutil/autoscroll.h"
 #include "core.h"
 #include "preferencesbehaviortab.h"

@@ -25,7 +25,7 @@
 #include <QDialog>
 #include <QProgressBar>

-#include "common/debug.h"
+#include "common/debugapp.h"
 #include "widget/taskview/elapsedcounterwidget.h"

 namespace olive
@@ -24,7 +24,7 @@

 #include <QDialog>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -29,7 +29,7 @@
 #include <QMessageBox>
 #include <QPushButton>

-#include "common/filefunctions.h"
+#include "oakutil/filefunctions.h"
 #include "oakengine/color.h"
 #include "oakengine/disk.h"
 #include "oakengine/project.h"
@@ -32,9 +32,9 @@
 #include <QXmlStreamReader>
 #include <QXmlStreamWriter>

-#include "common/define.h"
-#include "common/filefunctions.h"
-#include "common/xmlutils.h"
+#include "oakutil/define.h"
+#include "oakutil/filefunctions.h"
+#include "oakutil/xmlutils.h"

 namespace olive
 {
@@ -31,7 +31,7 @@
 #include <QVBoxLayout>

 #include "common/configwrapper.h"
-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "dialog/msgbox.h"
 #include "oakengine/node.h"
 #include "oakengine/timeline.h"
@@ -25,7 +25,7 @@
 #include <olive/core/core.h>
 #include <QXmlStreamWriter>

-#include "common/xmlutils.h"
+#include "oakutil/xmlutils.h"
 #include "dialog/sequence/presetmanager.h"
 #include "render/videoparams.h"

@@ -26,7 +26,7 @@
 #include <QFontComboBox>
 #include <QPlainTextEdit>

-#include "common/define.h"
+#include "oakutil/define.h"
 #include "widget/slider/floatslider.h"

 namespace olive
@@ -28,7 +28,7 @@
 #include <kddockwidgets/DockWidget.h>
 #include <QEvent>

-#include "common/define.h"
+#include "oakutil/define.h"

 #include <QTabWidget>

@@ -24,7 +24,7 @@

 #include <QIcon>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -25,7 +25,7 @@
 #include <QSettings>
 #include <QWidget>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -27,9 +27,9 @@

 #include "audio/audiolevelmeter.h"
 #include "audio/audiomanager.h"
-#include "common/decibel.h"
+#include "oakutil/decibel.h"
 #include "oakengine/preview.h"
-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"

 namespace olive
 {
@@ -27,7 +27,7 @@
 #include <QTimer>

 #include "audio/audiovisualwaveform.h"
-#include "common/define.h"
+#include "oakutil/define.h"
 #include "render/audiowaveformcache.h"

 namespace olive
@@ -24,7 +24,7 @@

 #include <QLabel>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -24,7 +24,7 @@

 #include <QPushButton>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -21,7 +21,7 @@

 #include "colorbutton.h"

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "dialog/color/colordialog.h"

 namespace olive
@@ -25,7 +25,7 @@
 #include <QPainter>
 #include <QWidgetAction>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "ui/colorcoding.h"

 namespace olive
@@ -23,7 +23,7 @@

 #include <QPainter>

-#include "common/lerp.h"
+#include "oakutil/lerp.h"
 #include "node/node.h"

 namespace olive
@@ -23,7 +23,7 @@

 #include <QPainter>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"

 namespace olive
 {
@@ -23,7 +23,7 @@

 #include <QGridLayout>

-#include "common/filefunctions.h"
+#include "oakutil/filefunctions.h"
 #include "widget/menu/menu.h"

 namespace olive
@@ -24,7 +24,7 @@

 #include <QGridLayout>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -28,10 +28,10 @@
 #include <QScrollBar>
 #include <QtMath>

-#include "common/decibel.h"
+#include "oakutil/decibel.h"
 #include "common/nodevaluehandle.h"
 #include "common/oakvaluehelper.h"
-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "oakengine/node.h"
 #include "widget/keyframeview/keyframehandle.h"

@@ -28,7 +28,7 @@
 #include <QVBoxLayout>

 #include "core.h"
-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "node/node.h"
 #include "common/nodevaluehandle.h"
 #include "oakengine/node.h"
@@ -24,7 +24,7 @@

 #include <QLineEdit>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -27,7 +27,7 @@

 #include "common/nodevaluehandle.h"
 #include "common/oakvaluehelper.h"
-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "dialog/keyframeproperties/keyframeproperties.h"
 #include "keyframehandle.h"
 #include "node/node.h"
@@ -26,7 +26,7 @@
 #include <QMenu>
 #include <QMetaMethod>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -23,7 +23,7 @@

 #include <QHBoxLayout>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "core.h"
 #include "node/node.h"
 #include "oakengine/node.h"
@@ -24,7 +24,7 @@
 #include <QCheckBox>
 #include <QDebug>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "dialog/speedduration/speeddurationdialog.h"
 #include "node/project/sequence/sequence.h"
 #include "oakengine/node.h"
@@ -26,7 +26,7 @@
 #include <QPushButton>
 #include <QWidget>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -28,7 +28,7 @@
 #include <QVector3D>
 #include <QVector4D>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "core.h"
 #include "nodeparambutton.h"
 #include "node/node.h"
@@ -24,7 +24,7 @@

 #include <QtGlobal>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -26,7 +26,7 @@
 #include <QGraphicsSceneMouseEvent>
 #include <QStyleOptionGraphicsItem>

-#include "common/lerp.h"
+#include "oakutil/lerp.h"
 #include "nodeview.h"
 #include "nodeviewitem.h"
 #include "nodeviewscene.h"
@@ -29,7 +29,7 @@
 #include <QPainter>
 #include <QStyleOptionGraphicsItem>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "common/configwrapper.h"
 #include "core.h"
 #include "node/value.h"
@@ -25,7 +25,7 @@
 #include <QFileDialog>
 #include <QHBoxLayout>

-#include "common/filefunctions.h"
+#include "oakutil/filefunctions.h"

 namespace olive
 {
@@ -25,7 +25,7 @@
 #include <QLineEdit>
 #include <QPushButton>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -24,7 +24,7 @@

 #include <QPushButton>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -30,7 +30,7 @@
 #include <QUrl>
 #include <QVBoxLayout>

-#include "common/define.h"
+#include "oakutil/define.h"
 #include "core.h"
 #include "dialog/footageproperties/footageproperties.h"
 #include "dialog/proxy/proxydialog.h"
@@ -23,7 +23,7 @@

 #include <QPainter>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"

 namespace olive
 {
@@ -24,7 +24,7 @@

 #include <QStyledItemDelegate>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -24,7 +24,7 @@

 #include <QListView>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -24,7 +24,7 @@

 #include <QStyledItemDelegate>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -24,7 +24,7 @@
 #include <QEvent>
 #include <QHBoxLayout>

-#include "common/define.h"
+#include "oakutil/define.h"
 #include "ui/icons/icons.h"

 namespace olive
@@ -27,7 +27,7 @@
 #include <QSlider>
 #include <QWidget>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -24,7 +24,7 @@

 #include <QTreeView>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -26,7 +26,7 @@
 #include <QMimeData>
 #include <QUrl>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "core.h"
 #include "oakengine/project.h"
 #include "oakengine/node.h"
@@ -26,7 +26,7 @@
 #include <QLineEdit>
 #include <QPushButton>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -26,7 +26,7 @@
 #include <QStyle>
 #include <QStyleOptionSlider>

-#include "common/range.h"
+#include "oakutil/range.h"

 namespace olive
 {
@@ -24,7 +24,7 @@

 #include <QScrollBar>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -26,8 +26,8 @@
 #include <QPainter>
 #include <QtMath>

-#include "common/qtutils.h"
-#include "common/filefunctions.h"
+#include "oakutil/qtutils.h"
+#include "oakutil/filefunctions.h"
 #include "oakengine/display.h"

 namespace olive
@@ -24,8 +24,8 @@
 #include <QPainter>
 #include <QtMath>

-#include "common/qtutils.h"
-#include "common/filefunctions.h"
+#include "oakutil/qtutils.h"
+#include "oakutil/filefunctions.h"
 #include "oakengine/color.h"
 #include "oakengine/display.h"

@@ -27,9 +27,9 @@
 #include <QPainter>
 #include <QtMath>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "common/configwrapper.h"
-#include "common/filefunctions.h"
+#include "oakutil/filefunctions.h"
 #include "oakengine/color.h"
 #include "oakengine/display.h"

@@ -21,7 +21,7 @@

 #include "numericsliderbase.h"

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "common/configwrapper.h"
 #include "core.h"

@@ -25,7 +25,7 @@
 #include <QEvent>
 #include <QMessageBox>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "core.h"
 #include "window/mainwindow/mainwindow.h"

@@ -24,7 +24,7 @@

 #include <QLabel>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -32,8 +32,8 @@
 #include <ApplicationServices/ApplicationServices.h>
 #endif

-#include "common/lerp.h"
-#include "common/qtutils.h"
+#include "oakutil/lerp.h"
+#include "oakutil/qtutils.h"
 #include "common/configwrapper.h"

 namespace olive
@@ -26,7 +26,7 @@
 #include <QTimer>
 #include <QWidget>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -24,7 +24,7 @@
 #include <cmath>
 #include <QDebug>

-#include "common/decibel.h"
+#include "oakutil/decibel.h"

 namespace olive
 {
@@ -26,7 +26,7 @@
 #include <QTimer>
 #include <QWidget>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -27,7 +27,7 @@
 #include <QRubberBand>
 #include <QToolTip>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "olive/core/util/timecodefunctions.h"
 #include "oakengine/node.h"
 #include "oakengine/undo.h"
@@ -23,8 +23,8 @@

 #include <QInputDialog>

-#include "common/autoscroll.h"
-#include "common/range.h"
+#include "oakutil/autoscroll.h"
+#include "oakutil/range.h"
 #include "common/configwrapper.h"
 #include "core.h"
 #include "engineeventbridge.h"
@@ -40,7 +40,7 @@
 #include "oakengine/audio.h"
 #include "core.h"
 #include "engineeventbridge.h"
-#include "common/range.h"
+#include "oakutil/range.h"
 #include "dialog/proxy/proxydialog.h"
 #include "dialog/sequence/sequence.h"
 #include "dialog/speedduration/speeddurationdialog.h"
@@ -27,7 +27,7 @@
 #include <QToolTip>

 #include "common/configwrapper.h"
-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "core.h"
 #include "dialog/sequence/sequence.h"
 #include "node/audio/volume/volume.h"
@@ -24,8 +24,8 @@
 #include <QDebug>
 #include <QToolTip>

-#include "common/qtutils.h"
-#include "common/range.h"
+#include "oakutil/qtutils.h"
+#include "oakutil/range.h"
 #include "common/configwrapper.h"
 #include "core.h"
 #include "node/block/gap/gap.h"
@@ -24,7 +24,7 @@

 #include <QSplitter>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -29,7 +29,7 @@
 #include <QPen>

 #include "common/configwrapper.h"
-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "../../timeruler/markerpainting.h"
 #include "node/project/footage/footage.h"
 #include "oakengine/timeline.h"
@@ -24,7 +24,7 @@
 #include <QApplication>
 #include <QPalette>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "common/colorcodingapp.h"

 namespace olive
@@ -26,8 +26,8 @@
 #include <QPainter>
 #include <QtMath>

-#include "common/qtutils.h"
-#include "common/range.h"
+#include "oakutil/qtutils.h"
+#include "oakutil/range.h"
 #include "core.h"
 #include "dialog/markerproperties/markerpropertiesdialog.h"
 #include "markerpainting.h"
@@ -24,7 +24,7 @@
 #include <QDebug>
 #include <QPainter>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "common/configwrapper.h"
 #include "core.h"
 #include "oakengine/viewer.h"
@@ -38,14 +38,14 @@
 #include <cstring>

 #include "audio/audiomanager.h"
-#include "common/define.h"
-#include "common/html.h"
+#include "oakutil/define.h"
+#include "common/htmlapp.h"
 #include "oakengine/gizmo.h"
 #include "oakengine/videoparams.h"
 #include "oakengine/display.h"
 #include "oakengine/undo.h"
 #include "widget/viewer/vieweroutpututils.h"
-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "common/configwrapper.h"
 #include "core.h"
 #include "node/block/subtitle/subtitle.h"
@@ -23,7 +23,7 @@

 #include <QtGlobal>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -24,7 +24,7 @@

 #include <QtMath>

-#include "common/define.h"
+#include "oakutil/define.h"

 namespace olive
 {
@@ -30,7 +30,7 @@
 #include <QTextBlock>
 #include <QtMath>

-#include "common/qtutils.h"
+#include "oakutil/qtutils.h"
 #include "ui/icons/icons.h"

 namespace olive
@@ -0,0 +1,108 @@
+# R8 计划：app/ 纯 C ABI 头文件清理
+
+> 目标：app/ 下的代码只 include engine/ 的 C 头文件（`oakengine/*.h`），
+> 不再 include 任何 engine 内部 C++ 头。
+> 前置：R7 已完成（nm U _ZN5olive = 0，liboakengine.so 导出收口）。
+
+---
+
+## 1. 纯头工具共享层（shared/）
+
+### 1.1 新建目录
+
+```
+shared/
+  include/
+    oakutil/
+      define.h          ← engine/common/define.h
+      lerp.h            ← engine/common/lerp.h
+      decibel.h         ← engine/common/decibel.h
+      digit.h           ← engine/common/digit.h
+      range.h           ← engine/common/range.h
+      crashpadutils.h   ← engine/common/crashpadutils.h
+      qtutils.h         ← engine/common/qtutils.h（声明）
+      filefunctions.h   ← engine/common/filefunctions.h（声明）
+      xmlutils.h        ← 精简版（XMLAttributeLoop 宏 + xml_read_next_start_element）
+```
+
+### 1.2 CMake 接入
+
+顶层 CMakeLists.txt 添加：
+```cmake
+list(APPEND OLIVE_INCLUDE_DIRS ${CMAKE_CURRENT_SOURCE_DIR}/shared/include)
+```
+
+### 1.3 迁移规则
+
+- engine/common/ 中被移出的 .h：原位置改为 `#include "oakutil/xxx.h"` 的转发头
+  （保持 engine 内部现有 include 路径不断）。
+- app/ 中所有 `#include "common/xxx.h"`（指 engine 的）改为 `#include "oakutil/xxx.h"`。
+- qtutils.h / filefunctions.h：声明移到 shared，.cpp 实现分别留在
+  engine/common/（engine 用）和 app/common/（app 用，已有）。
+- xmlutils.h 精简版：只保留 XMLAttributeLoop 宏 + 无 CancelAtom 的函数声明；
+  engine 内部完整版保留在 engine/common/xmlutils.h（include 精简版 + 追加
+  CancelAtom 重载）。
+
+### 1.4 验证
+
+```bash
+grep -rn '#include "common/' app/ | grep -vE '"common/(colorcodingapp|configwrapper|nodevaluehandle|oakvaluehelper|undowrapper|debugapp|filefunctionsapp|hashstreamapp|htmlapp|qtutilsapp|xmlutilsapp)'
+# 期望：0 结果
+```
+
+---
+
+## 2. engine/ui/colorcoding.h → app 本地化
+
+engine/ui/colorcoding.h 是 C++ 类（ColorCoding），被 app 5 处引用。
+方案：在 app/common/ 下新建 `colorcoding.h`，通过 C ABI 或本地静态表实现。
+engine 内部保留原文件。
+
+---
+
+## 3. engine C++ 类 → C ABI 替换（按子系统）
+
+按影响面排序，每批一个 PR：
+
+| 批次 | 子系统 | 违规 include | 替换方案 |
+|---|---|---|---|
+| P2 | node/value.h + node/keyframe.h | ~10 处 | oakengine/node.h 的 oak_node_value_type 枚举 |
+| P3 | node/node.h + node/param.h | ~20 处 | OakEngineNode* + oakengine_node_* 函数 |
+| P4 | node/project*.h | ~15 处 | OakEngineProject*/OakEngineSequence* |
+| P5 | render/* | ~10 处 | oakengine/display.h + viewer.h |
+| P6 | timeline/* | ~6 处 | oakengine/timeline.h |
+| P7 | codec/* + audio/* | ~10 处 | oakengine/encoding.h + audio.h |
+| P8 | tool/* + undo/* | ~20 处 | 新增 C ABI 或 app 本地枚举 |
+| P9 | pluginSupport/* | ~6 处 | oakengine/plugin.h |
+
+---
+
+## 4. CMake 收口（最终步骤）
+
+- 移除 `target_link_libraries(olive-editor PRIVATE oakengine-obj)`
+- 从 `oakengine` 共享库 PUBLIC include 中移除 engine 根目录
+- 只保留 `engine/include`（C ABI 头）
+
+验证：
+```bash
+grep -rn '#include "' app/ | grep -E '"(node|render|timeline|codec|audio|task|undo|tool|pluginSupport|ui/colorcoding)/'
+# 期望：0 结果
+cmake --build build && ctest --test-dir build --output-on-failure
+```
+
+---
+
+## 状态
+
+- [x] Phase 1：shared/ 纯头工具层（define, lerp, decibel, digit, range, crashpadutils, qtutils, filefunctions, xmlutils, autoscroll）
+- [ ] Phase 2-9：C++ 类替换（node/, render/, timeline/, codec/, audio/, task/, undo/, tool/, pluginSupport/）
+- [ ] Phase 10：CMake 收口
+
+### Phase 1 已知遗留
+
+- `app/widget/timebased/timebasedwidget.cpp` 仍引用 `common/current.h`（依赖 pluginSupport + render，需 Phase 2+ 处理）
+- app/ 仍引用 3 个 engine 内部头（不在 Phase 1 清单内，待后续阶段处理）：
+  `common/commandlineparser.h`（app/main.cpp）、`common/crashpadinterface.h`（app/main.cpp）、
+  `common/dropworkflowbehavior.h`（app/widget/timelinewidget/tool/import.h）
+- `engine/node/project.h` 原先经 `common/xmlutils.h` 间接获得 `NodeGroup` 前置声明，
+  精简后已改为在 project.h 内显式前置声明
@@ -1,37 +1,2 @@
-/***
-
-  Olive - Non-Linear Video Editor
-  Copyright (C) 2022 Olive Team
-  Modifications Copyright (C) 2025 mikesolar
-
-  This program is free software: you can redistribute it and/or modify
-  it under the terms of the GNU General Public License as published by
-  the Free Software Foundation, either version 3 of the License, or
-  (at your option) any later version.
-
-  This program is distributed in the hope that it will be useful,
-  but WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU General Public License for more details.
-
-  You should have received a copy of the GNU General Public License
-  along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-***/
-
-#ifndef OAK_AUTOSCROLL_H
-#define OAK_AUTOSCROLL_H
-
-#include "common/define.h"
-
-namespace olive
-{
-
-class AutoScroll {
-public:
-	enum Method { k_none, k_page, k_smooth };
-};
-
-}
-
-#endif // OAK_AUTOSCROLL_H
+// Forwarding header - canonical content moved to shared/include/oakutil/autoscroll.h
+#include "oakutil/autoscroll.h"
@@ -1,41 +1,2 @@
-/***
-
-  Olive - Non-Linear Video Editor
-  Copyright (C) 2022 Olive Team
-  Modifications Copyright (C) 2025 mikesolar
-
-  This program is free software: you can redistribute it and/or modify
-  it under the terms of the GNU General Public License as published by
-  the Free Software Foundation, either version 3 of the License, or
-  (at your option) any later version.
-
-  This program is distributed in the hope that it will be useful,
-  but WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU General Public License for more details.
-
-  You should have received a copy of the GNU General Public License
-  along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-***/
-
-#ifndef OAK_CRASHPADUTILS_H
-#define OAK_CRASHPADUTILS_H
-
-#include <client/crashpad_client.h>
-
-// Copied from base::FilePath to match its macro
-#if BUILDFLAG(IS_POSIX)
-// On most platforms, native pathnames are char arrays, and the encoding
-// may or may not be specified.  On Mac OS X, native pathnames are encoded
-// in UTF-8.
-#define QSTRING_TO_BASE_STRING(x) x.toStdString()
-#define BASE_STRING_TO_QSTRING(x) QString::fromStdString(x)
-#elif BUILDFLAG(IS_WIN)
-// On Windows, for Unicode-aware applications, native pathnames are wchar_t
-// arrays encoded in UTF-16.
-#define QSTRING_TO_BASE_STRING(x) x.toStdWString()
-#define BASE_STRING_TO_QSTRING(x) QString::fromStdWString(x)
-#endif // BUILDFLAG(IS_WIN)
-
-#endif // OAK_CRASHPADUTILS_H
+// Forwarding header - canonical content moved to shared/include/oakutil/crashpadutils.h
+#include "oakutil/crashpadutils.h"
@@ -1,104 +1,2 @@
-/***
-
-  Olive - Non-Linear Video Editor
-  Copyright (C) 2022 Olive Team
-  Modifications Copyright (C) 2025 mikesolar
-
-  This program is free software: you can redistribute it and/or modify
-  it under the terms of the GNU General Public License as published by
-  the Free Software Foundation, either version 3 of the License, or
-  (at your option) any later version.
-
-  This program is distributed in the hope that it will be useful,
-  but WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU General Public License for more details.
-
-  You should have received a copy of the GNU General Public License
-  along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-***/
-
-#ifndef OAK_DECIBEL_H
-#define OAK_DECIBEL_H
-
-#include <QtGlobal>
-#include <cmath>
-
-//#define ALLOW_RETURNING_INFINITY
-
-namespace olive
-{
-
-class Decibel {
-public:
-	// In basically all circumstances, this should calculate to 0.0 linear
-	static constexpr double minimum = -200.0;
-
-	static double from_linear(double linear)
-	{
-		double v = double(20.0) * std::log10(linear);
-#ifndef ALLOW_RETURNING_INFINITY
-		if (std::isinf(v)) {
-			return minimum;
-		}
-#endif
-		return v;
-	}
-
-	static double to_linear(double decibel)
-	{
-		double to_linear = std::pow(double(10.0), decibel / double(20.0));
-
-		// Minimum threshold that we figure is close enough to 0 that we may as well just return 0
-		if (to_linear < 0.000001) {
-			return 0;
-		} else {
-			return to_linear;
-		}
-	}
-
-	static double from_logarithmic(double logarithmic)
-	{
-		if (logarithmic < 0.001)
-#ifdef ALLOW_RETURNING_INFINITY
-			return std::numeric_limits<double>::infinity();
-#else
-			return minimum;
-#endif
-		else if (logarithmic > 0.99)
-			return 0;
-		else
-			return 20.0 * std::log10(-std::log(1 - logarithmic) / lo_g100);
-	}
-
-	static double to_logarithmic(double decibel)
-	{
-		if (qFuzzyIsNull(decibel)) {
-			return 1;
-		} else {
-			return 1 - std::exp(-std::pow(10.0, decibel / 20.0) * lo_g100);
-		}
-	}
-
-	static double linear_to_logarithmic(double linear)
-	{
-		return 1 - std::exp(-linear * lo_g100);
-	}
-
-	static double logarithmic_to_linear(double logarithmic)
-	{
-		if (logarithmic > 0.99) {
-			return 1;
-		} else {
-			return -std::log(1 - logarithmic) / lo_g100;
-		}
-	}
-
-private:
-	static constexpr double lo_g100 = 4.60517018599;
-};
-
-}
-
-#endif // OAK_DECIBEL_H
+// Forwarding header - canonical content moved to shared/include/oakutil/decibel.h
+#include "oakutil/decibel.h"
@@ -1,68 +1,2 @@
-/***
-
-  Olive - Non-Linear Video Editor
-  Copyright (C) 2022 Olive Team
-  Modifications Copyright (C) 2025 mikesolar
-
-  This program is free software: you can redistribute it and/or modify
-  it under the terms of the GNU General Public License as published by
-  the Free Software Foundation, either version 3 of the License, or
-  (at your option) any later version.
-
-  This program is distributed in the hope that it will be useful,
-  but WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU General Public License for more details.
-
-  You should have received a copy of the GNU General Public License
-  along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-***/
-
-#ifndef OAK_OLIVECOMMONDEFINE_H
-#define OAK_OLIVECOMMONDEFINE_H
-
-namespace olive
-{
-
-/// The minimum size an icon in ProjectExplorer can be
-const int k_project_icon_size_minimum = 16;
-
-/// The maximum size an icon in ProjectExplorer can be
-const int k_project_icon_size_maximum = 256;
-
-/// The default size an icon in ProjectExplorer can be
-const int k_project_icon_size_default = 64;
-
-const int k_bytes_in_gigabyte = 1073741824;
-
-}
-
-#define MACRO_NAME_AS_STR(s) #s
-#define MACRO_VAL_AS_STR(s) MACRO_NAME_AS_STR(s)
-
-#define OLIVE_NS_CONST_ARG(x, y) \
-	QArgument<const olive::x>("const " MACRO_VAL_AS_STR(olive) "::" #x, y)
-#define OLIVE_NS_ARG(x, y) \
-	QArgument<olive::x>(MACRO_VAL_AS_STR(olive) "::" #x, y)
-#define OLIVE_NS_RETURN_ARG(x, y) \
-	QReturnArgument<olive::x>(MACRO_VAL_AS_STR(olive) "::" #x, y)
-
-/**
- * Copy/move deleters. Similar to Q_DISABLE_COPY_MOVE, et al. but those functions are not present in Qt < 5.13 so we
- * use our own functions for portability.
- */
-
-#define DISABLE_COPY(Class)        \
-	Class(const Class &) = delete; \
-	Class &operator=(const Class &) = delete;
-
-#define DISABLE_MOVE(Class)   \
-	Class(Class &&) = delete; \
-	Class &operator=(Class &&) = delete;
-
-#define DISABLE_COPY_MOVE(Class) \
-	DISABLE_COPY(Class)          \
-	DISABLE_MOVE(Class)
-
-#endif // OAK_OLIVECOMMONDEFINE_H
+// Forwarding header - canonical content moved to shared/include/oakutil/define.h
+#include "oakutil/define.h"
--- a/Show More
+++ b/Show More