docs(core/policy): 为函数 policy_apply_command 添加注释

policy_context_t 应该只包含所有 policy 相关接口都需要用到的参数，而
event 只是 policy_route_event 接口需要的参数，故应该将其从
policy_context_t 中剔除

src/core/plan.h

@@ -17,18 +17,56 @@ typedef enum effect_type_t {
   ZDWM_EFFECT_MAP_WINDOW,
   ZDWM_EFFECT_UNMAP_WINDOW,
   ZDWM_EFFECT_FOCUS_WINDOW,
+  ZDWM_EFFECT_MOVE_WINDOW,
+  ZDWM_EFFECT_RESIZE_WINDOW,
+  ZDWM_EFFECT_CHANGE_BORDER_COLOR,
+  ZDWM_EFFECT_CHANGE_BORDER_WIDTH,
+  ZDWM_EFFECT_CHANGE_WINDOW_LIST,
+  ZDWM_EFFECT_RESTACK_WINDOWS,
 } effect_type_t;
 
 typedef struct effect_only_window_id_t {
   window_id_t window;
 } effect_only_window_id_t;
 
+typedef struct effect_move_window_t {
+  window_id_t window;
+  point_t left_top_point;
+} effect_move_window_t;
+
+typedef struct effect_resize_window_t {
+  window_id_t window;
+  int32_t width;
+  int32_t height;
+} effect_resize_window_t;
+
+typedef struct effect_change_border_color_t {
+  window_id_t window;
+  const color_t *color;
+} effect_change_border_color_t;
+
+typedef struct effect_change_border_width_t {
+  window_id_t window;
+  uint32_t border_width;
+} effect_change_border_width_t;
+
+typedef struct effect_window_list_t {
+  const window_id_t *windows;
+  size_t count;
+} effect_window_list_t;
+
 typedef struct effect_t {
   effect_type_t type;
   union {
     effect_only_window_id_t map;
     effect_only_window_id_t unmap;
     effect_only_window_id_t focus;
+    effect_move_window_t move;
+    effect_resize_window_t resize;
+    effect_change_border_color_t change_border_color;
+    effect_change_border_width_t change_border_width;
+    effect_window_list_t change_window_list;
+    effect_window_list_t restack_windows;
   } as;
 } effect_t;
 

src/core/policy.c

@@ -93,13 +93,17 @@ static bool route_map_request(
   return true;
 }
 
-bool policy_route_event(const policy_context_t *ctx, command_buffer_t *out) {
-  switch (ctx->event->type) {
+bool policy_route_event(
+  const policy_context_t *ctx,
+  const event_t *event,
+  command_buffer_t *out
+) {
+  switch (event->type) {
   case ZDWM_EVENT_WINDOW_MAP_REQUEST:
     return route_map_request(
       ctx->state,
       ctx->rules,
-      &ctx->event->as.window_map_request,
+      &event->as.window_map_request,
       out
     );
   default:

src/core/policy.h

@@ -9,10 +9,34 @@
 typedef struct policy_context_t {
   const state_t *state;
   const rules_t *rules;
-  const event_t *event;
 } policy_context_t;
 
-bool policy_route_event(const policy_context_t *ctx, command_buffer_t *out);
+/**
+ * @brief 事件路由：将运行时事件翻译为语义命令
+ *
+ * @param ctx   策略上下文
+ * @param event 需要翻译的事件
+ * @param out   命令输出缓冲区，路由产生的命令追加到此处
+ *
+ * @return true     产生了至少一条需要执行的命令
+ * @return false    产生了至少一条需要执行的命令
+ */
+bool policy_route_event(
+  const policy_context_t *ctx,
+  const event_t *event,
+  command_buffer_t *out
+);
+
+/**
+ * @brief 将语义命令应用到状态，并累积后端副作用到 plan
+ *
+ * @param ctx               策略上下文
+ * @param command_buffer    待应用的命令序列
+ * @param plan              副作用累积器，记录后端需要执行的操作
+ *
+ * @return true     产生了至少一项后端副作用
+ * @return false    无副作用产生
+ */
 bool policy_apply_command(
   const policy_context_t *ctx,
   const command_buffer_t *command_buffer,

src/core/runtime.c

@@ -110,6 +110,11 @@ void runtime_run(runtime_t *runtime) {
   command_buffer_t *command_buffer = &runtime->command_buffer;
   plan_t *plan                     = &runtime->plan;
 
+  policy_context_t ctx = {
+    .state = &runtime->state,
+    .rules = &runtime->rules,
+  };
+
   while (runtime->running) {
     event_t event = {0};
     if (!backend_next_event(backend, &event)) break;
@@ -117,13 +122,7 @@ void runtime_run(runtime_t *runtime) {
     command_buffer_reset(command_buffer);
     plan_reset(plan);
 
-    policy_context_t ctx = {
-      .state = &runtime->state,
-      .rules = &runtime->rules,
-      .event = &event,
-    };
-
-    policy_route_event(&ctx, command_buffer);
+    policy_route_event(&ctx, &event, command_buffer);
     policy_apply_command(&ctx, command_buffer, plan);
     if (plan->count) backend_apply_effect(backend, plan->effects, plan->count);
 

src/core/types.h

@@ -24,6 +24,14 @@ typedef struct point_t {
   int32_t y;
 } point_t;
 
+typedef struct color_t {
+  uint32_t rgba;
+  uint32_t argb;
+
+  /* RGBA color channels for Cairo, each channel in the range [0, 1] */
+  double red, green, blue, alpha;
+} color_t;
+
 typedef enum window_geometry_mode_t {
   ZDWM_GEOMETRY_NORMAL,
   ZDWM_GEOMETRY_MAXIMIZED,