KiriyamaCanvas的架构设计思考

// 文件：platform/web/CanvasHost.cc
void onFrame(App& app) override {
    // 【阶段 1】同步组件实例，并将 JS 暂存区的待处理数据灌入组件
    syncInstances(app);
    const auto ctx = frameContext(app); // 打包 dt 与 960x540 逻辑空间鼠标坐标
    for (const auto& [handle, instance] : instances_) {
        pumpOne(handle, *instance);
    }

    // 【阶段 2】树状交互步进：自顶向下执行命中检测、状态流转与按需 rebuild / 原地更新
    for (const auto& [handle, instance] : instances_) {
        if (instance->pie && instance->pie->visible())   instance->pie->tickTree(ctx);
        if (instance->spark && instance->spark->visible()) instance->spark->tickTree(ctx);
        if (instance->table && instance->table->visible()) instance->table->tickTree(ctx);
    }

    // 【阶段 3 & 4】按当前主题背景色清屏，并执行「先几何、后文本」的双通道渲染
    const core::ChartTheme& theme = kiriyama::web::currentTheme();
    app.painter().clear(theme.background);
    for (const auto& [handle, instance] : instances_) {
        if (instance->pie && instance->pie->visible()) {
            drawSceneGeometry(app.painter(), *instance->pie, theme); // 通道 A：几何图元
            app.text().drawScene(*instance->pie, theme);             // 通道 B：文字贴图
        }
        // ... spark 与 table 同理
    }

    // 【阶段 5】帧末顶层合成：更新鼠标手型光标，并在最顶层绘制全局唯一 Tooltip
    updateCursor(app);
    if (const int active = instanceUnderPointer(app); active != 0) {
        kiriyama::web::applyTooltip(active, *tooltip_);
    }
    tooltip_->update(*root_, ctx);
}

// 文件：platform/src/src/TableWidget.cc
void TableWidget::rebuild() {
    ensureColumnsMeasured(); // 仅在 fontDirty_ 时测量一次列宽

    // 1. 下沉到 core 层：计算虚拟滚动视口 [firstRow, lastRow] 并构建可见行描述树
    core::TableBuildResult built = core::buildTable(
        data_, state_, config_, style_, frame().size(), columnWidths_, scrollOffset_);
    layout_ = std::move(built.layout);

    // 2. 虚拟树对账：按 key ("row.3") 复用常驻节点，未变属性零标脏
    if (built.root) {
        core::reconcileScene(*inner_, *built.root);
    }
    collectRowNodes(); // 缓存当前可见行的背景节点指针与逻辑行号

    layoutDirty_ = false;
    lastSize_ = frame().size();
}

// 快路径示例 A（PieChart.cc）：60FPS 扇区外扩动画，直接改单个 Polygon 节点的顶点数组
void PieChart::applyExplode(std::size_t index, double radius) {
    core::SceneNode* node = sliceNodes_[index];
    PieLayout expanded = layout_;
    expanded.outerRadius += radius;
    node->setPoints(core::sectorPolygon(layout_.sectors[index], expanded, segments_));
}

// 快路径示例 B（SceneBuilder.cc）：表格悬停/选中行切换，O(可见行数) 原地刷写语义背景色
void updateTableHighlights(std::span<const std::pair<std::size_t, SceneNode*>> rowBgNodes,
                           std::optional<std::size_t> selectedRow,
                           std::optional<std::size_t> hoveredRow,
                           const TableStyle& style) {
    for (const auto& [rowIndex, bgNode] : rowBgNodes) {
        if (!bgNode) continue;
        SceneStyle bgStyle = bgNode->style();
        if (selectedRow && *selectedRow == rowIndex) {
            bgStyle.fill = style.rowSelectedFill; // ColorToken::TableRowSelected
        } else if (hoveredRow && *hoveredRow == rowIndex) {
            bgStyle.fill = style.rowHoverFill;    // ColorToken::TableRowHover
        } else {
            bgStyle.fill = (rowIndex % 2 == 1) ? style.rowAltFill : style.rowFill;
        }
        bgNode->setStyle(bgStyle); // SceneNode 内部相等短路，未变行不触发 markDirty()
    }
}

// 文件：platform/src/src/SceneDraw.cc
void drawNode(Painter& painter, const SceneNode& node, const Affine2D& parentWorld,
              double parentOpacity, const core::ChartTheme& theme,
              const std::vector<core::Color>* seriesPalette) {
    if (!node.visible()) return;

    // 1. 透明度累乘剪枝
    const core::SceneStyle& style = node.style();
    const double effective = parentOpacity * style.opacity;
    if (effective <= 0.0) return;

    // 2. 色板继承与 ColorToken 实时解析（切换深浅色主题时无需改动场景树任何节点）
    const auto* palette = style.seriesPalette ? style.seriesPalette.get() : seriesPalette;
    const core::Color fill = style.fill.resolve(theme, palette);
    const core::Color stroke = style.stroke.resolve(theme, palette);

    // 3. 世界矩阵合成：world = parentWorld * localTransform
    const Affine2D world = parentWorld * node.transform();

    // 4. 压入子树裁剪框（如表格滚动视口 clipRect）
    SDL_Rect savedClip{};
    const bool clipped = pushClip(painter, world, node.clipRect(), savedClip);

    // 5. 按图元类型（Rect / Ellipse / Polygon / Polyline / Line）调用 Painter 落笔
    // ...

    // 6. 递归绘制子节点并恢复裁剪栈
    for (const auto& child : node.children()) {
        if (child) drawNode(painter, *child, world, effective, theme, palette);
    }
    restoreClip(painter, clipped, savedClip);
}

// 文件：platform/src/src/Painter.cc
bool convex = true;
for (std::size_t k = 0; k < n; ++k) {
    // 检查相邻边转向叉积是否与多边形整体绕向 (orientation) 一致
    if (crossAt(clean[k], clean[(k + 1) % n], clean[(k + 2) % n]) * orientation < 0.0) {
        convex = false;
        break;
    }
}

if (convex) {
    // 【快路径】凸多边形（圆角矩形、椭圆、常规扇区）：O(n) 三角扇 (0, i, i+1)
    for (std::size_t i = 1; i + 1 < n; ++i) {
        indices.insert(indices.end(), {0, static_cast<int>(i), static_cast<int>(i + 1)});
    }
} else {
    // 【精确路径】凹多边形（>180° 甜甜圈扇环）：反射点耳切法 (Ear-Clipping)
    // 仅收集内角 >180° 的凹顶点 (reflex)，判断候选耳三角 (prev, here, next) 内是否包含反射点
    collectReflex();
    while (ring.size() > 3) { /* 剪除无反射点落入的凸耳并更新邻点凹凸性 */ }
}

// 文件：platform/src/include/kiriyama/scene/TableWidget.h & PieChart.cc
class TableWidget : public Widget {
private:
    core::TableData data_{};                  // 1. 组件通过 move 语义独占持有业务数据
    core::TableState state_{};                // 2. 排序与选中状态机（只排索引 order_，不搬移 rows）
    core::SceneNode* inner_{nullptr};         // 3. 内部对账根组 (key="table")
    std::vector<std::pair<std::size_t, core::SceneNode*>> rowBgNodes_; // 快路径指针缓存
};

// 文件：platform/src/src/TableWidget.cc
void TableWidget::onUpdate(const FrameContext& /*ctx*/) {
    // 将外部设置的 frame().origin() 转移到组件自身的仿射矩阵 transform_ 平移分量上，
    // 保持自身 frame_ 恒为 {0, 0, width, height}！
    if (frame().x != 0.0 || frame().y != 0.0) {
        setTranslation(frame().origin());
        setFrame({0.0, 0.0, frame().width, frame().height});
    }
    if (layoutDirty_ || !(frame().size() == lastSize_)) {
        rebuild(); // 仅尺寸或数据变化才重排；在画布上平移组件只改 transform_，零 rebuild！
    }
}

// 文件：core/src/SceneDiff.cc
void reconcileChildren(SceneNode& target, const SceneNode& source, SceneDiffResult& out) {
    // 1. O(1) 移出旧子节点数组，并建立 key -> 旧下标 哈希表（如 "row.5" -> 5）
    std::vector<std::unique_ptr<SceneNode>> oldChildren = target.takeChildren();
    std::unordered_map<std::string_view, std::size_t> keyIndex;
    for (std::size_t i = 0; i < oldChildren.size(); ++i) {
        if (oldChildren[i] && !oldChildren[i]->key().empty())
            keyIndex.emplace(oldChildren[i]->key(), i);
    }

    // 2. 遍历新树子节点：命中 key 且 NodeType 相同则 std::move 直接复用旧节点 unique_ptr
    for (std::size_t i = 0; i < source.childCount(); ++i) {
        const SceneNode* src = source.childAt(i);
        // ... 查找 match 下标 ...
        if (match != kNoMatch) {
            reconcileNode(*oldChildren[match], *src, out); // 仅当属性真变了才 markDirty()
            if (!src->key().empty()) matchedOldIndices.push_back(match);
            next.push_back(std::move(oldChildren[match])); // 保持原节点指针与唯一 id_ 不变
        } else {
            auto cloned = src->clone();
            cloned->markSubtreeDirty();
            next.push_back(std::move(cloned));
        }
    }

    // 3. 用 O(n log n) 最长递增子序列 (LIS) 判定兄弟节点顺序是否发生移动
    const std::size_t moves = minimumMoves(matchedOldIndices);
    const bool structuralChange = (insertedDelta > 0 || removedDelta > 0 || moves > 0);
    target.setChildren(std::move(next), structuralChange); // 结构未变则绝不污染父节点 dirty_
}

// 文件：math/include/kiriyama/math/Transform2D.h
constexpr Affine2D inverse(double epsilon = kEpsilon) const noexcept {
    const double det = determinant(); // m00 * m11 - m01 * m10
    if (!std::isfinite(det) || std::abs(det) <= epsilon) {
        // ★ 防 NaN 保护：当组件处于缩放动画第 0 帧 (scale = 0) 时 det == 0，
        // 严禁除以 0 产生 NaN 污染后续所有几何比较，安全回退为单位矩阵 Identity()
        return Identity();
    }
    const double inv = 1.0 / det;
    return {
        m11 * inv,
        -m01 * inv,
        (m01 * m12 - m11 * m02) * inv,
        -m10 * inv,
        m00 * inv,
        (m10 * m02 - m00 * m12) * inv,
    };
}

// 文件：core/src/Geometry.cc
RectD transformedBounds(const RectD& rect, const Affine2D& transform) noexcept {
    if (rect.width < 0.0 || rect.height < 0.0 ||
        (rect.width == 0.0 && rect.height == 0.0)) {
        return {}; // 仅拒绝负尺寸或退化为单个点的空盒，保留 width==0 或 height==0 的线段！
    }
    const std::array<Vec2d, 4> corners = {
        transform.apply({rect.x, rect.y}),
        transform.apply({rect.right(), rect.y}),
        transform.apply({rect.right(), rect.bottom()}),
        transform.apply({rect.x, rect.bottom()}),
    };
    return boundsOfPoints(corners); // 取 4 个变换后角点的 [minX, minY, maxX - minX, maxY - minY]
}

// 文件：core/include/kiriyama/core/Geometry.h & core/src/HitTest.cc
inline Vec2d closestPointOnSegment(const Vec2d& point, const Vec2d& a, const Vec2d& b) noexcept {
    const Vec2d ab = b - a;
    const double lengthSquared = ab.lengthSquared();
    if (!(lengthSquared > 0.0)) return a;
    const double t = math::saturate((point - a).dot(ab) / lengthSquared);
    return a + ab * t;
}

std::size_t nearestEndpoint(const Vec2d& point, std::span<const Vec2d> points, std::size_t segIdx) noexcept {
    const double distA = (point - points[segIdx]).lengthSquared();
    const double distB = (point - points[segIdx + 1]).lengthSquared();
    return (distB < distA) ? (segIdx + 1) : segIdx;
}

// 文件：core/include/kiriyama/core/Geometry.h
inline double normalizeAnglePositive(double angle) noexcept {
    const double wrapped = std::fmod(angle, math::kTwoPi);
    return wrapped < 0.0 ? wrapped + math::kTwoPi : wrapped;
}

inline bool ArcD::contains(const Vec2d& point, double radiusTolerance = 0.0) const noexcept {
    if (empty()) return false;
    const Vec2d delta = point - center;
    const double distance = delta.length();
    // 1. 极径夹逼：剔除甜甜圈中心圆孔 (distance < innerRadius) 与外部空白
    if (distance > outerRadius + radiusTolerance ||
        distance < std::max(0.0, innerRadius - radiusTolerance)) {
        return false;
    }
    // 2. 极角模 2π 折回判定
    if (distance <= 1e-9) return innerRadius <= radiusTolerance;
    return containsAngle(std::atan2(delta.y, delta.x));
}

// 文件：platform/src/src/PieChart.cc
std::optional<std::size_t> PieChart::pickSector(const Vec2d& worldPoint) const noexcept {
    const Vec2d local = toLocal(worldPoint);
    if (hoveredIndex_ && *hoveredIndex_ < explodeProgress_.size() &&
        explodeProgress_[*hoveredIndex_] > 0.0) {
        PieLayout expanded = layout_;
        // ★ 动态叠加当前帧的外扩动画位移，使膨胀出去的扇区边缘依然保持稳定命中
        expanded.outerRadius += explodeDistance_ * explodeProgress_[*hoveredIndex_];
        if (const auto hit = core::hitTestPie(local, expanded); hit.hit && hit.index == *hoveredIndex_) {
            return hit.index;
        }
    }
    const core::HitResult hit = core::hitTestPie(local, layout_);
    return hit.hit ? std::optional<std::size_t>(hit.index) : std::nullopt;
}

// 文件：core/src/SceneQuery.cc
const SceneNode* hitNode(const SceneNode& node, const Vec2d& worldPoint, double tolerance) noexcept {
    if (!node.visible() || node.style().opacity <= 0.0) return nullptr;

    // 1. 先求逆变换转入当前节点局部坐标，并用膨胀了 tolerance 的局部 AABB 粗筛
    const Vec2d local = node.toLocal(worldPoint);
    if (!node.bounds().isEmpty() && !node.bounds().expanded(tolerance).contains(local)) {
        // 若当前节点无自定义 bounds（如 Group 容器），继续向下递归；否则直接剪枝
    }

    // 2. 逆序遍历子节点（后绘制的顶层图元最先被测试）
    for (std::size_t i = node.childCount(); i > 0; --i) {
        if (const SceneNode* hit = hitNode(*node.childAt(i - 1), worldPoint, tolerance)) {
            return hit;
        }
    }

    // 3. 纯容器 Group 自身不产生命中，图元节点调用 containsLocal 精确几何判定
    if (node.type() == NodeType::Group) return nullptr;
    return node.containsLocal(local, tolerance) ? &node : nullptr;
}

// 文件：core/src/TableLayout.cc
std::optional<std::size_t> TableLayout::rowAtY(double y, std::size_t totalRows) const noexcept {
    if (rowHeight <= 0.0 || y < bodyRect.y || y >= bodyRect.bottom()) return std::nullopt;
    const double contentY = (y - bodyRect.y) + scrollOffset;
    if (contentY < 0.0) return std::nullopt;
    const auto row = static_cast<std::size_t>( std::floor(contentY / rowHeight));
    return row < totalRows ? std::optional<std::size_t>(row) : std::nullopt;
}

// 文件：platform/src/src/Widget.cc
void Widget::tick(const FrameContext& ctx) {
    clicked_ = false; // 单帧脉冲复位
    const bool wasInside = inside_;
    inside_ = hitShape(ctx.pointer.position);

    const bool justPressed = ctx.pointer.down && !down_;
    const bool justReleased = !ctx.pointer.down && down_;
    down_ = ctx.pointer.down;

    if (inside_ && !wasInside) onPointerEnter();
    else if (!inside_ && wasInside) onPointerLeave();

    if (justPressed && inside_) {
        pressed_ = true;
        onPress();
    }
    if (justReleased && pressed_) {
        const bool releasedInside = inside_;
        pressed_ = false;
        clicked_ = releasedInside;
        onRelease(releasedInside);
        if (clicked_) {
            for (const auto& cb : clickBindings_) if (cb) cb();
        }
    }
    // ★ 捕获保持：按住左键拖拽滑出组件边界时，hovered_ 保持为 true，防止拖拽中途断触
    hovered_ = inside_ || (pressed_ && ctx.pointer.down);
    onUpdate(ctx);
}

// 文件：platform/src/src/InputController.cc
bool dispatchWheelToTree(core::SceneNode& node, const WheelEvent& event) {
    if (!node.visible()) return false;
    for (std::size_t i = node.childCount(); i > 0; --i) {
        if (dispatchWheelToTree(*node.childAt(i - 1), event)) return true; // 子节点已消费则短路
    }
    if (auto* widget = dynamic_cast<Widget*>(&node)) {
        if (widget->interactive() && widget->containsPoint(event.position)) {
            return widget->dispatchWheel(event);
        }
    }
    return false;
}

// 文件：platform/src/src/Interaction.cc
core::Color blendOver(const core::Color& base, const core::Color& top) noexcept {
    const double aTop = static_cast<double>(top.a) / 255.0;
    const double aBase = static_cast<double>(base.a) / 255.0;
    const double outA = aTop + aBase * (1.0 - aTop);
    if (outA <= 1e-9) return core::Color::Transparent();
    const auto mixChannel = [&](std::uint8_t b, std::uint8_t t) -> std::uint8_t {
        const double v = (static_cast<double>(t) * aTop +
                          static_cast<double>(b) * aBase * (1.0 - aTop)) / outA;
        return static_cast<std::uint8_t>(std::clamp(std::round(v), 0.0, 255.0));
    };
    return {mixChannel(base.r, top.r), mixChannel(base.g, top.g), mixChannel(base.b, top.b),
            static_cast<std::uint8_t>(std::clamp(std::round(outA * 255.0), 0.0, 255.0))};
}

// 文件：platform/src/src/Interaction.cc
math::Affine2D interactionTransform(const core::SceneNode& node, const math::Affine2D& base,
                                    double scale, const core::Vec2d& offset) noexcept {
    const core::RectD b = node.bounds();
    const core::Vec2d center = b.isEmpty()
                                   ? core::Vec2d{0.0, 0.0}
                                   : core::Vec2d{b.x + b.width * 0.5, b.y + b.height * 0.5};
    return base * math::Affine2D::Translate(center + offset) *
           math::Affine2D::Scale(scale, scale) *
           math::Affine2D::Translate({-center.x, -center.y});
}