docs(runtime): explain import scheduling and dependency selection

src/lib/canvas-runtime/import-budget.ts

@@ -13,7 +13,10 @@ export type ImportScheduling = {
 
 /** A soft time slice with a work threshold, even when the clock is coarse.
  * The caller bounds each indivisible parse/decode operation separately. */
-/** 默认6ms软目标；step 不一定产生 Promise，调用方须在返回等待值时真正 await/yield。 */
+/** 默认 6ms 软目标，闭包保存本时间片 started/work/unchecked 三个计数，不存任务或文档。
+ * step 可能同步返回 undefined；只有返回 Promise 且调用方 await 时才形成有效背压，应串行使用同一预算。
+ * 自定义 yieldTask 决定让出到微任务还是后续任务；预算不保证浏览器一定在该点完成一帧绘制。
+ * 构造只校验 frameBudgetMs，不预先检查 signal；units 应由调用者提供非负有限工作量。 */
 export function createImportBudget(signal: AbortSignal, options: ImportScheduling = {}) {
   const budget = options.frameBudgetMs ?? 6;
   if (!Number.isFinite(budget) || budget <= 0) throw fault('invalid_import_budget');
@@ -22,7 +25,10 @@ export function createImportBudget(signal: AbortSignal, options: ImportSchedulin
   // 每128工作单位才读一次时钟，减少高频开销；总量16384强制让出，不能因时间测不准而无限执行。
   let started = now(), work = 0, unchecked = 0;
   return {
-    /** 记工作量并按阈值检查取消/时间；达到预算或时间异常时让出，回来再验取消并重置时间片。 */
+    /** 累加 units；未满 128 个未检查单位且总量未满 16384 时直接返回，连 signal 也尚未检查。
+     * 阈值到达才读时钟；未超时保留 work 累计，超时/时间倒退或非有限值/工作量封顶则 await yieldTask。
+     * yield 后复查取消，成功才重设 started/work；读取时钟或 yield 抛错直接传播，不隐式重试。
+     * units 无运行时校验，负数/NaN 会破坏计数假设；本函数不测量单次实际 CPU 成本或字节数。 */
     step(units = 1): Promise<void> | undefined {
       work += units;
       unchecked += units;