core: 明确布局函数返回语义与 floating 布局约定

src/core/layout.h

@@ -0,0 +1,105 @@
+#pragma once
+
+#include <stddef.h>
+
+#include "core/types.h"
+
+typedef struct wm_layout_window_ref_t {
+  wm_window_id_t window_id;
+  wm_window_geometry_mode_t geometry_mode;
+} wm_layout_window_ref_t;
+
+typedef struct wm_layout_ctx_t {
+  wm_output_id_t output_id;
+  wm_workspace_id_t workspace_id;
+  wm_window_id_t focused_window_id;
+  wm_rect_t workarea;
+  const wm_layout_window_ref_t *windows;
+  size_t window_count;
+} wm_layout_ctx_t;
+
+typedef struct wm_layout_item_t {
+  wm_window_id_t window_id;
+  wm_rect_t rect; /* 平铺窗口的目标外框矩形（包含边框） */
+} wm_layout_item_t;
+
+typedef struct wm_layout_result_t {
+  wm_layout_item_t *items;
+  size_t item_count;
+  size_t item_capacity;
+} wm_layout_result_t;
+
+/*
+ * 返回 true 表示成功生成合法的布局结果。
+ * 返回 false 表示布局计算失败，调用方应丢弃本次结果。
+ *
+ * 该返回值不表示窗口最终几何是否发生变化；
+ * 是否有改动应由调用方在比较当前状态与布局结果后决定。
+ */
+typedef bool (*wm_layout_fn)(const wm_layout_ctx_t *ctx,
+                             wm_layout_result_t *out);
+
+typedef struct wm_layout_slot_t {
+  wm_layout_id_t id;
+  /*
+   * 布局名称，用于：
+   * - 配置引用
+   * - 日志输出
+   * - 调试展示
+   *
+   * 推荐使用稳定、可读的名称，如 "tile"、"monocle"、"floating"。
+   */
+  const char *name;
+  /*
+   * 面向用户的布局说明。
+   *
+   * 用于帮助信息、调试输出和交互式布局选择；可为空。
+   */
+  const char *description;
+  /*
+   * 布局符号，用于状态栏显示等紧凑场景。
+   *
+   * 推荐使用 1-2 个字符的简短标识符。
+   */
+  const char *symbol;
+  /*
+   * 布局执行函数。
+   *
+   * fn == NULL 表示 floating 布局，即该布局不参与平铺计算。
+   */
+  wm_layout_fn fn;
+} wm_layout_slot_t;
+
+typedef struct wm_layout_registry_t {
+  wm_layout_slot_t *slots;
+  size_t slot_count;
+  size_t slot_capacity;
+} wm_layout_registry_t;
+
+void wm_layout_result_init(wm_layout_result_t *result);
+void wm_layout_result_reset(wm_layout_result_t *result);
+void wm_layout_result_shutdown(wm_layout_result_t *result);
+
+bool wm_layout_result_push(wm_layout_result_t *result, wm_layout_item_t item);
+
+void wm_layout_registry_init(wm_layout_registry_t *registry);
+void wm_layout_registry_shutdown(wm_layout_registry_t *registry);
+size_t wm_layout_registry_count(const wm_layout_registry_t *registry);
+const wm_layout_slot_t *wm_layout_registry_at(
+  const wm_layout_registry_t *registry, size_t index);
+
+wm_layout_id_t wm_layout_register(wm_layout_registry_t *registry,
+                                  const char *name, const char *symbol,
+                                  const char *description, wm_layout_fn fn);
+/*
+ * 获取可执行的布局函数。
+ *
+ * 返回 NULL 的情况包括：
+ * - id 无效
+ * - id 对应的 slot 不存在
+ * - slot 存在，但 fn == NULL（表示 floating 布局）
+ */
+wm_layout_fn wm_layout_get(const wm_layout_registry_t *registry,
+                           wm_layout_id_t id);
+const wm_layout_slot_t *wm_layout_slot_get(const wm_layout_registry_t *registry,
+                                           wm_layout_id_t id);

src/core/runtime.h

@@ -0,0 +1,11 @@
+#include "core/state.h"
+
+typedef struct wm_runtime_t {
+  bool running;
+  bool will_restart;
+
+  wm_state_t state;
+} wm_runtime_t;
+
+bool wm_runtime_init(wm_runtime_t *runtime);
+void wm_runtime_shutdown(wm_runtime_t *runtime);

src/core/state.h

@@ -0,0 +1,72 @@
+#pragma once
+
+#include <stddef.h>
+
+#include "core/types.h"
+
+typedef struct wm_window_t {
+  wm_window_id_t id;
+  wm_workspace_id_t workspace_id;
+
+  wm_window_geometry_mode_t geometry_mode;
+  bool floating;
+  bool sticky;
+  bool urgent;
+  bool fixed_size;
+
+  /* 几何信息（均为包含边框后的外框矩形） */
+  wm_rect_t float_rect; /* floating 模式下记忆的外框矩形 */
+  wm_rect_t frame_rect; /* 当前外框矩形（由 layout 或 float_rect 解析） */
+
+  /* 元数据（核心算法不依赖，仅用于规则匹配和信息展示） */
+  char *title;
+  char *app_id;
+  char *class_name;
+  char *instance_name;
+
+  bool skip_taskbar;
+} wm_window_t;
+
+typedef struct wm_workspace_t {
+  wm_workspace_id_t id;
+  wm_output_id_t output_id; /* 固定归属某个输出 */
+  wm_layout_id_t layout_id; /* 当前活动布局（可用布局列表中的一个） */
+  wm_window_id_t focused_window_id;
+
+  /* 可用布局列表（启动时根据配置分配，运行时固定） */
+  wm_layout_id_t *available_layouts;
+  size_t layout_count;
+
+  /* 名称（核心算法不依赖，仅用于状态栏显示） */
+  char *name;
+} wm_workspace_t;
+
+typedef struct wm_output_t {
+  wm_output_id_t id;
+  bool enabled;
+  wm_rect_t geometry; /* 输出完整几何 */
+  wm_rect_t workarea; /* 可用区域（排除面板等） */
+  wm_workspace_id_t current_workspace_id;
+} wm_output_t;
+
+typedef struct wm_state_t {
+  /* 内部实现（不透明结构体，实现文件中定义） */
+  wm_workspace_t *workspaces;
+  size_t workspace_count;
+  size_t workspace_capacity;
+
+  wm_output_t *outputs;
+  size_t output_count;
+  size_t output_capacity;
+
+  wm_window_t *windows;
+  size_t window_count;
+  size_t window_capacity;
+
+  wm_window_id_t *stack_order;
+  size_t stack_count;
+  size_t stack_capacity;
+
+  uint64_t generation;
+  bool initialized;
+} wm_state_t;

src/core/types.h

@@ -0,0 +1,45 @@
+#pragma once
+
+#include <stdint.h>
+
+typedef uint32_t wm_window_id_t;
+typedef uint32_t wm_workspace_id_t;
+typedef uint32_t wm_output_id_t;
+typedef uint32_t wm_layout_id_t;
+
+/* clang-format off */
+/* 无效 ID 标记 */
+#define WM_WINDOW_ID_INVALID     ((wm_window_id_t)0)
+#define WM_WORKSPACE_ID_INVALID  ((wm_workspace_id_t)UINT32_MAX)
+#define WM_OUTPUT_ID_INVALID     ((wm_output_id_t)UINT32_MAX)
+#define WM_LAYOUT_ID_INVALID     ((wm_layout_id_t)UINT32_MAX)
+/* clang-format on */
+
+typedef struct wm_point_t {
+  int32_t x;
+  int32_t y;
+} wm_point_t;
+
+typedef struct wm_rect_t {
+  int32_t x;
+  int32_t y;
+  int32_t width;
+  int32_t height;
+} wm_rect_t;
+
+typedef enum wm_window_geometry_mode_t {
+  WM_GEOMETRY_NORMAL,
+  WM_GEOMETRY_MAXIMIZED,
+  WM_GEOMETRY_FULLSCREEN,
+  WM_GEOMETRY_MINIMIZED,
+} wm_window_geometry_mode_t;
+
+typedef enum wm_focus_direction_t {
+  WM_FOCUS_PREV,
+  WM_FOCUS_NEXT,
+} wm_focus_direction_t;
+
+typedef enum wm_cross_output_policy_t {
+  WM_CROSS_OUTPUT_KEEP_WORKSPACE,
+  WM_CROSS_OUTPUT_MOVE_TO_TARGET_WORKSPACE,
+} wm_cross_output_policy_t;