@podto/zi-core 0.1.0-rc.1 → 0.1.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,2826 @@
1
+ // tools/types/zi.d.ts — global type declarations for the zi runtime API.
2
+ //
3
+ // Consumers:
4
+ // 1. User .tsx code — via `tsconfig.json` `include` or `/// <reference>`.
5
+ // Unlocks `zi.h`, `zi.signal`, `zi.createRoot` etc. autocomplete +
6
+ // `tsc --noEmit` type checking.
7
+ // 2. Framework internal `src/runtime/*.ts` — declares
8
+ // `var zi: ZiGlobal` so framework code can assign to `zi.*`
9
+ // without `as any` cast.
10
+ //
11
+ // Maintenance: edit when adding a new top-level zi.* API surface. Engine
12
+ // tags are real functions on the `zi` global; `src/jsx-tags.ts` re-exports
13
+ // them (e.g. `export const Text = zi.Text`) — update both when adding a
14
+ // new typed engine tag.
15
+
16
+ export {}; // make this a module
17
+
18
+ export interface Signal<T> {
19
+ (): T;
20
+ set(value: T): void;
21
+ /** Read the current value WITHOUT subscribing the running effect. */
22
+ peek(): T;
23
+ }
24
+
25
+ /** A derived/computed value from `createMemo`. Read-only signal. */
26
+ export interface Memo<T> {
27
+ (): T;
28
+ /** Read without subscribing the running effect. */
29
+ peek(): T;
30
+ }
31
+
32
+ /** Per-field accessor on a store: tracked getter + `.set` / `.peek` escape hatches. */
33
+ export type StoreField<T> = (() => T) & { set(value: T): void; peek(): T };
34
+
35
+ /** State half of a store: each field becomes a `StoreField`. */
36
+ export type StoreFields<S> = { [K in keyof S]: StoreField<S[K]> };
37
+
38
+ /** An action: receives the mutable state proxy first, then caller args. */
39
+ export type StoreAction<S> = (state: S, ...args: any[]) => any;
40
+
41
+ /** Bound actions: the state-proxy argument is dropped from the public call. */
42
+ export type StoreActions<A> = {
43
+ [K in keyof A]: A[K] extends (state: any, ...args: infer P) => infer R ? (...args: P) => R : never;
44
+ };
45
+
46
+ export interface StoreDef<S, A> {
47
+ state: S;
48
+ actions?: A;
49
+ }
50
+
51
+ // ── Animation / declarative transition ──────────────────────────────────
52
+ // Design: docs/superpowers/specs/2026-06-14-declarative-transition-component-design.md.
53
+ // Keyframe model; fast
54
+ // channels (opacity/transform) run on the compositor fast path, slow
55
+ // channels (color/box-shadow) are opt-in and re-record per frame.
56
+
57
+ export type EasingName = "linear" | "ease-in" | "ease-out" | "ease-in-out" | "ease-out-cubic";
58
+
59
+ /** A keyframe stop key: a percent string ("0%".."100%"), or "from"/"to". */
60
+ export type FramePct = `${number}%` | "from" | "to";
61
+
62
+ /** Properties animatable at a keyframe. Flat keys (no CSS `transform` string). */
63
+ export interface AnimFrame {
64
+ // fast channels — compositor fast path: zero DL rebuild / zero relayout.
65
+ opacity?: number;
66
+ translateX?: number; // px
67
+ translateY?: number; // px
68
+ scale?: number;
69
+ scaleX?: number;
70
+ scaleY?: number;
71
+ rotate?: number; // degrees
72
+ originX?: number; // 0..1, scale/rotate pivot
73
+ originY?: number; // 0..1
74
+ // slow channels — `markDirty` re-record; opt-in, small/isolated widgets
75
+ // only (dev build warns ≥16 descendants). See design §3.5.
76
+ color?: string; // "#rrggbb" / "rgba(...)"
77
+ background?: string;
78
+ boxShadow?: string; // CSS box-shadow string
79
+ }
80
+
81
+ /** `stiffness`/`damping`/`mass` — critically damped (no overshoot) by
82
+ * default when `damping` is omitted. See `AnimSpec.spring`. */
83
+ export interface SpringPhysics {
84
+ stiffness?: number;
85
+ damping?: number;
86
+ mass?: number;
87
+ }
88
+
89
+ export interface AnimSpec {
90
+ /** At least `from`/`to` (or `0%`/`100%`). Only the LAST stop (`100%`/`to`)
91
+ * is used in spring mode — a spring has no timeline to play through
92
+ * intermediate stops, only a target it's pulled toward (#0037). */
93
+ keyframes: Partial<Record<FramePct, AnimFrame>>;
94
+ /** ms. Required UNLESS `spring` is set — a spring has no fixed duration,
95
+ * it just integrates until it settles near its target. */
96
+ duration?: number;
97
+ /** Per-segment easing. Default "ease-out". Ignored when `spring` is set. */
98
+ easing?: EasingName;
99
+ /** ms. Default 0. Ignored when `spring` is set. */
100
+ delay?: number;
101
+ /** Default 1. "infinite" never resolves `finished`. Ignored when `spring` is set. */
102
+ iteration?: number | "infinite";
103
+ /** Default "normal". Ignored when `spring` is set. */
104
+ direction?: "normal" | "reverse" | "alternate" | "alternate-reverse";
105
+ // NOTE: v1 always holds the final frame on completion (CSS `fill: forwards`
106
+ // semantics). A `fill: "none"` revert-to-initial mode is not implemented, so
107
+ // the field is intentionally absent rather than advertised-but-ignored.
108
+ /** Velocity-carrying alternative time source (#0037) — set this INSTEAD OF
109
+ * `duration`/`easing`/`iteration`/`direction` (they're ignored when this
110
+ * is present). Retargeting an in-flight spring (calling `zi.animate`/
111
+ * `<Show>` again on the same target while it's still settling) keeps its
112
+ * current value AND velocity and just changes where it's headed — no
113
+ * snap back to `0%`. Only FAST channels (opacity/translate/scale/
114
+ * rotate/origin) are spring-driven; color/boxShadow stops in
115
+ * `keyframes` are ignored in spring mode. */
116
+ spring?: SpringPhysics;
117
+ }
118
+
119
+ /** Built-in transition preset (fast-channel only). */
120
+ export type PresetName = "fade" | "scale" | "slideUp" | "slideDown" | "slideLeft" | "slideRight";
121
+
122
+ /**
123
+ * enter/exit transition for `<Show>` / `<For>`. A bare preset name means
124
+ * enter uses it and exit plays its reverse.
125
+ */
126
+ export type TransitionSpec =
127
+ | PresetName
128
+ | {
129
+ enter?: AnimSpec | PresetName;
130
+ exit?: AnimSpec | PresetName;
131
+ /** `<For>` only: per-index stagger in ms. */
132
+ stagger?: number;
133
+ };
134
+
135
+ /**
136
+ * `<Transition>` exit/enter coordination when its content swaps:
137
+ * • "parallel" (default) — old child exits WHILE the new one enters.
138
+ * • "out-in" — old child fully exits, THEN the new one mounts + enters.
139
+ * • "in-out" — new child enters first (both visible), THEN the old exits.
140
+ */
141
+ export type TransitionMode = "parallel" | "out-in" | "in-out";
142
+
143
+ /**
144
+ * `<Transition>` — animated swap between DIFFERENT children. The single child
145
+ * is a reactive thunk returning an element (or null = empty); when its result
146
+ * changes, the old plays `exit` and the new plays `enter`, coordinated by
147
+ * `mode`. Unlike the `transition` PROP on `<Show>`/`<For>` (which animates one
148
+ * cached child's show/hide), this coordinates the exit of A with the enter of B.
149
+ */
150
+ export interface TransitionProps {
151
+ /** Enter animation for the incoming child. Preset name or full spec. */
152
+ enter?: AnimSpec | PresetName;
153
+ /** Exit animation for the outgoing child. Preset name or full spec. */
154
+ exit?: AnimSpec | PresetName;
155
+ /** Swap coordination. Default "parallel". */
156
+ mode?: TransitionMode;
157
+ /** Also play `enter` on the very first mount. Default false. */
158
+ appear?: boolean;
159
+ /** A single reactive thunk: `() => element | null`. */
160
+ children?: any;
161
+ }
162
+
163
+ /** Control handle returned by `zi.animate`. */
164
+ export interface AnimHandle {
165
+ /** Stable player id (≥1), or -1 if creation failed (then it's settled `false`). */
166
+ readonly id: number;
167
+ play(): void;
168
+ pause(): void;
169
+ reverse(): void;
170
+ cancel(): void;
171
+ /**
172
+ * Register a settle listener. Fires exactly once with `completed`
173
+ * (`true` = finished naturally, `false` = cancelled / create-failed).
174
+ * Fires immediately if the animation has already settled.
175
+ */
176
+ onSettled(fn: (completed: boolean) => void): void;
177
+ /**
178
+ * Present UNLESS created with `{ fireAndForget: true }`. Resolves on natural
179
+ * completion; **rejects** (`zi:anim-cancelled`) on any cancel (explicit /
180
+ * preempted / scope cleanup / page switch / target lost). An
181
+ * `iteration:"infinite"` animation never resolves — only rejects on cancel.
182
+ */
183
+ readonly finished?: Promise<void>;
184
+ }
185
+
186
+ export interface AnimateOpts {
187
+ /**
188
+ * Don't allocate the `finished` promise — for internal fire-and-forget
189
+ * (enter) so a teardown `cancelAll` doesn't reject an unhandled promise.
190
+ */
191
+ fireAndForget?: boolean;
192
+ }
193
+
194
+ /** Options for the time-driven scalar `zi.tween` (signal-shaped). */
195
+ export interface TweenOpts {
196
+ from?: number; // default 0
197
+ to?: number; // default 1
198
+ duration?: number; // ms, default 200
199
+ easing?: EasingName; // default "ease-out"
200
+ delay?: number; // ms, default 0
201
+ autoplay?: boolean; // default true
202
+ repeat?: number; // -1 infinite, 0 once, N → N+1 iterations
203
+ yoyo?: boolean; // ping-pong on iteration
204
+ }
205
+
206
+ /** A tween reads as a signal getter, plus playback controls. */
207
+ export interface TweenSignal {
208
+ (): number;
209
+ readonly id: number;
210
+ play(): void;
211
+ pause(): void;
212
+ reverse(): void;
213
+ cancel(): void;
214
+ seek(t01: number): void;
215
+ onComplete(fn: () => void): void;
216
+ }
217
+
218
+ export interface SpringOpts extends SpringPhysics {
219
+ from?: number; // default 0
220
+ to?: number; // default 1
221
+ autoplay?: boolean; // default true
222
+ }
223
+
224
+ /** Velocity-carrying sibling of `TweenSignal` (#0037) — reads as a signal
225
+ * getter, same shape, minus `reverse`/`seek`: neither is meaningful for a
226
+ * spring (no fixed start/end to seek between, no natural "playhead"). */
227
+ export interface SpringSignal {
228
+ (): number;
229
+ readonly id: number;
230
+ play(): void;
231
+ pause(): void;
232
+ cancel(): void;
233
+ onComplete(fn: () => void): void;
234
+ }
235
+
236
+ /**
237
+ * **widget 句柄** —— `zi.h(...)` / `<Tag/>` 的返回值,`setChildren` 这些 API 收的东西。
238
+ *
239
+ * 运行期它是裸数字(引擎的 slot id),但**普通数字不是句柄**:判据 `zi.isWidget`
240
+ * 问的是「registry 里有没有这个活槽」—— 光看数值区间不够,句柄区间里还有 unix
241
+ * 秒级时间戳、≥1GB 的字节数这类真会被写出来的值(#136)。
242
+ *
243
+ * 这个品牌是同一条契约的编译期半边:句柄可以当 number 用,反过来不行 —— 于是
244
+ * `zi.setChildren(cell, [Math.round(v)])` 在 tsc 就红,不用等 UI 上出现一格整数。
245
+ */
246
+ export type ZiWidget = number & { readonly __zi_widget: unique symbol };
247
+
248
+ /** JSX 表达式 / 引擎 widget 工厂的结果 —— 就是一个 widget 句柄。 */
249
+ export type ZiJsxNode = ZiWidget;
250
+ /** 运行时 `Dim.parse` 收 `"50%"` / `"16px"` / `"auto"`;只有 px 和 % 两种单位。 */
251
+ export type ZiDim = number | { px: number } | { pct: number } | "auto" | `${number}%` | `${number}px`;
252
+ export type ZiEdges = number | {
253
+ top?: number;
254
+ right?: number;
255
+ bottom?: number;
256
+ left?: number;
257
+ };
258
+ export type ZiAlign = "start" | "center" | "end" | "stretch" | string;
259
+ export type ZiJustify = "start" | "center" | "end" | "between" | "around" | "evenly" | string;
260
+
261
+ /** 样式:对象或一整份 CSS 声明字符串。数值只认 px / %,且量级有闸:长度
262
+ * ±1e7 px、百分比 ±1e4 %、opacity 0..1。`Infinity`/`NaN` 当未设丢弃,
263
+ * `1e30` 这类合法的有限巨值夹到上限(#133)。
264
+ *
265
+ * 每个 widget kind 实际吃哪些键**不一样**(#0038)——`ZiStyle`(下方生成块)
266
+ * 是 Box/Column/Row/Flex 那一档的全量集合;其余 kind 各有更窄的生成类型
267
+ * (`TextStyle`/`ImageStyle`/…),下面各 `XxxProps.style` 字段引用对应的那个。
268
+ * 拼错的键或传给不支持它的 kind,`zi dev` 下会打一行带 widget id 的警告
269
+ * (release 无成本)。真源是 `src/reactive/style_keys.zig`,改类型内容前改
270
+ * 那张表,再 `zig build dump-style-keys && node tools/gen-style-types.mjs`
271
+ * 重新生成 —— 不要手改下面两条标记之间的内容。 */
272
+ // GENERATED:style-keys BEGIN — 由 tools/gen-style-types.mjs 从 src/reactive/style_keys.zig 生成,不要手改
273
+ export type CheckmarkStyle = {
274
+ flexGrow?: number;
275
+ flex_grow?: number;
276
+ flex?: number;
277
+ flexShrink?: number;
278
+ flex_shrink?: number;
279
+ flexBasis?: ZiDim;
280
+ flex_basis?: ZiDim;
281
+ color?: string;
282
+ text_color?: string;
283
+ } | string;
284
+
285
+ export type CodeEditorStyle = {
286
+ flexGrow?: number;
287
+ flex_grow?: number;
288
+ flex?: number;
289
+ flexShrink?: number;
290
+ flex_shrink?: number;
291
+ flexBasis?: ZiDim;
292
+ flex_basis?: ZiDim;
293
+ padding?: ZiEdges;
294
+ radius?: number;
295
+ background?: string;
296
+ border?: any;
297
+ border_top?: any;
298
+ borderTop?: any;
299
+ border_right?: any;
300
+ borderRight?: any;
301
+ border_bottom?: any;
302
+ borderBottom?: any;
303
+ border_left?: any;
304
+ borderLeft?: any;
305
+ border_style?: any;
306
+ borderStyle?: any;
307
+ opacity?: number;
308
+ boxShadow?: any;
309
+ box_shadow?: any;
310
+ color?: string;
311
+ text_color?: string;
312
+ font_size?: number;
313
+ fontSize?: number;
314
+ font_family?: "sans-serif" | "monospace";
315
+ fontFamily?: "sans-serif" | "monospace";
316
+ lineHeight?: number;
317
+ line_height?: number;
318
+ } | string;
319
+
320
+ export type ControlStyle = {
321
+ flexGrow?: number;
322
+ flex_grow?: number;
323
+ flex?: number;
324
+ flexShrink?: number;
325
+ flex_shrink?: number;
326
+ flexBasis?: ZiDim;
327
+ flex_basis?: ZiDim;
328
+ display?: "flex" | "none";
329
+ padding?: ZiEdges;
330
+ radius?: number;
331
+ width?: ZiDim;
332
+ height?: ZiDim;
333
+ min_width?: ZiDim;
334
+ background?: string;
335
+ border?: any;
336
+ border_top?: any;
337
+ borderTop?: any;
338
+ border_right?: any;
339
+ borderRight?: any;
340
+ border_bottom?: any;
341
+ borderBottom?: any;
342
+ border_left?: any;
343
+ borderLeft?: any;
344
+ border_style?: any;
345
+ borderStyle?: any;
346
+ opacity?: number;
347
+ boxShadow?: any;
348
+ box_shadow?: any;
349
+ overflow?: "visible" | "hidden" | "scroll";
350
+ translate_y?: number;
351
+ translateY?: number;
352
+ cursor?: string;
353
+ alignItems?: ZiAlign;
354
+ align_items?: ZiAlign;
355
+ justifyContent?: ZiJustify;
356
+ justify_content?: ZiJustify;
357
+ transition?: ("background" | "opacity" | "translateY")[] | boolean;
358
+ } | string;
359
+
360
+ export type ImageStyle = {
361
+ flexGrow?: number;
362
+ flex_grow?: number;
363
+ flex?: number;
364
+ flexShrink?: number;
365
+ flex_shrink?: number;
366
+ flexBasis?: ZiDim;
367
+ flex_basis?: ZiDim;
368
+ width?: ZiDim;
369
+ height?: ZiDim;
370
+ color?: string;
371
+ text_color?: string;
372
+ } | string;
373
+
374
+ export type InputStyle = {
375
+ flexGrow?: number;
376
+ flex_grow?: number;
377
+ flex?: number;
378
+ flexShrink?: number;
379
+ flex_shrink?: number;
380
+ flexBasis?: ZiDim;
381
+ flex_basis?: ZiDim;
382
+ padding?: ZiEdges;
383
+ radius?: number;
384
+ width?: ZiDim;
385
+ height?: ZiDim;
386
+ background?: string;
387
+ border?: any;
388
+ border_top?: any;
389
+ borderTop?: any;
390
+ border_right?: any;
391
+ borderRight?: any;
392
+ border_bottom?: any;
393
+ borderBottom?: any;
394
+ border_left?: any;
395
+ borderLeft?: any;
396
+ border_style?: any;
397
+ borderStyle?: any;
398
+ opacity?: number;
399
+ boxShadow?: any;
400
+ box_shadow?: any;
401
+ cursor?: string;
402
+ color?: string;
403
+ text_color?: string;
404
+ placeholder_color?: string;
405
+ font_size?: number;
406
+ fontSize?: number;
407
+ font_weight?: string | number;
408
+ fontWeight?: string | number;
409
+ font_family?: "sans-serif" | "monospace";
410
+ fontFamily?: "sans-serif" | "monospace";
411
+ lineHeight?: number;
412
+ line_height?: number;
413
+ } | string;
414
+
415
+ export type ScrollableStyle = {
416
+ flexGrow?: number;
417
+ flex_grow?: number;
418
+ flex?: number;
419
+ flexShrink?: number;
420
+ flex_shrink?: number;
421
+ flexBasis?: ZiDim;
422
+ flex_basis?: ZiDim;
423
+ display?: "flex" | "none";
424
+ } | string;
425
+
426
+ export type TextStyle = {
427
+ flexGrow?: number;
428
+ flex_grow?: number;
429
+ flex?: number;
430
+ flexShrink?: number;
431
+ flex_shrink?: number;
432
+ flexBasis?: ZiDim;
433
+ flex_basis?: ZiDim;
434
+ color?: string;
435
+ text_color?: string;
436
+ font_size?: number;
437
+ fontSize?: number;
438
+ font_weight?: string | number;
439
+ fontWeight?: string | number;
440
+ font_family?: "sans-serif" | "monospace";
441
+ fontFamily?: "sans-serif" | "monospace";
442
+ lineHeight?: number;
443
+ line_height?: number;
444
+ textAlign?: "left" | "right" | "center" | "justify" | "start" | "end";
445
+ text_align?: "left" | "right" | "center" | "justify" | "start" | "end";
446
+ maxLines?: number;
447
+ max_lines?: number;
448
+ textOverflow?: "ellipsis";
449
+ text_overflow?: "ellipsis";
450
+ ellipsis?: boolean;
451
+ textDecoration?: "none" | "underline" | "overline" | "line-through";
452
+ text_decoration?: "none" | "underline" | "overline" | "line-through";
453
+ locale?: "en" | "en-US" | "zh-CN" | "zh-TW" | "ja" | "und";
454
+ } | string;
455
+
456
+ export type TextareaStyle = {
457
+ flexGrow?: number;
458
+ flex_grow?: number;
459
+ flex?: number;
460
+ flexShrink?: number;
461
+ flex_shrink?: number;
462
+ flexBasis?: ZiDim;
463
+ flex_basis?: ZiDim;
464
+ padding?: ZiEdges;
465
+ radius?: number;
466
+ height?: ZiDim;
467
+ background?: string;
468
+ border?: any;
469
+ border_top?: any;
470
+ borderTop?: any;
471
+ border_right?: any;
472
+ borderRight?: any;
473
+ border_bottom?: any;
474
+ borderBottom?: any;
475
+ border_left?: any;
476
+ borderLeft?: any;
477
+ border_style?: any;
478
+ borderStyle?: any;
479
+ opacity?: number;
480
+ boxShadow?: any;
481
+ box_shadow?: any;
482
+ cursor?: string;
483
+ color?: string;
484
+ text_color?: string;
485
+ placeholder_color?: string;
486
+ font_size?: number;
487
+ fontSize?: number;
488
+ font_weight?: string | number;
489
+ fontWeight?: string | number;
490
+ font_family?: "sans-serif" | "monospace";
491
+ fontFamily?: "sans-serif" | "monospace";
492
+ lineHeight?: number;
493
+ line_height?: number;
494
+ } | string;
495
+
496
+ export type ZiMinimalStyle = {
497
+ flexGrow?: number;
498
+ flex_grow?: number;
499
+ flex?: number;
500
+ flexShrink?: number;
501
+ flex_shrink?: number;
502
+ flexBasis?: ZiDim;
503
+ flex_basis?: ZiDim;
504
+ } | string;
505
+
506
+ export type ZiSizeOnlyStyle = {
507
+ flexGrow?: number;
508
+ flex_grow?: number;
509
+ flex?: number;
510
+ flexShrink?: number;
511
+ flex_shrink?: number;
512
+ flexBasis?: ZiDim;
513
+ flex_basis?: ZiDim;
514
+ display?: "flex" | "none";
515
+ width?: ZiDim;
516
+ height?: ZiDim;
517
+ } | string;
518
+
519
+ export type ZiStyle = {
520
+ flexGrow?: number;
521
+ flex_grow?: number;
522
+ flex?: number;
523
+ flexShrink?: number;
524
+ flex_shrink?: number;
525
+ flexBasis?: ZiDim;
526
+ flex_basis?: ZiDim;
527
+ display?: "flex" | "none";
528
+ padding?: ZiEdges;
529
+ margin?: ZiEdges;
530
+ radius?: number;
531
+ width?: ZiDim;
532
+ height?: ZiDim;
533
+ min_width?: ZiDim;
534
+ max_width?: ZiDim;
535
+ min_height?: ZiDim;
536
+ max_height?: ZiDim;
537
+ box_sizing?: "border-box" | "content-box";
538
+ boxSizing?: "border-box" | "content-box";
539
+ background?: string;
540
+ border?: any;
541
+ border_top?: any;
542
+ borderTop?: any;
543
+ border_right?: any;
544
+ borderRight?: any;
545
+ border_bottom?: any;
546
+ borderBottom?: any;
547
+ border_left?: any;
548
+ borderLeft?: any;
549
+ border_style?: any;
550
+ borderStyle?: any;
551
+ opacity?: number;
552
+ boxShadow?: any;
553
+ box_shadow?: any;
554
+ overflow?: "visible" | "hidden" | "scroll";
555
+ alignItems?: ZiAlign;
556
+ align_items?: ZiAlign;
557
+ justifyContent?: ZiJustify;
558
+ justify_content?: ZiJustify;
559
+ flexDirection?: "row" | "column" | "row-reverse" | "column-reverse";
560
+ flex_direction?: "row" | "column" | "row-reverse" | "column-reverse";
561
+ flexWrap?: "wrap" | "nowrap";
562
+ flex_wrap?: "wrap" | "nowrap";
563
+ alignContent?: string;
564
+ align_content?: string;
565
+ gap?: number | string;
566
+ rowGap?: number;
567
+ row_gap?: number;
568
+ columnGap?: number;
569
+ column_gap?: number;
570
+ } | string;
571
+ // GENERATED:style-keys END
572
+
573
+ export interface ChartPrimitiveProps {
574
+ style?: ZiSizeOnlyStyle;
575
+ flex?: any;
576
+ position?: "absolute" | "relative";
577
+ top?: number;
578
+ right?: number;
579
+ bottom?: number;
580
+ left?: number;
581
+ }
582
+
583
+ export interface ZiBaseProps {
584
+ style?: ZiStyle;
585
+ flex?: boolean;
586
+ position?: "absolute" | "relative";
587
+ top?: number;
588
+ right?: number;
589
+ bottom?: number;
590
+ left?: number;
591
+ width?: ZiDim;
592
+ height?: ZiDim;
593
+ padding?: ZiEdges;
594
+ margin?: ZiEdges;
595
+ /** 任何句柄 / 句柄数组;JSX 的 children 也走这里。 */
596
+ children?: any;
597
+ // CSS pointer-events: "none" drops the widget + subtree out of
598
+ // hit-testing (decorative overlays — e.g. a splitter handle's grip).
599
+ pointerEvents?: "none" | "auto";
600
+ alignSelf?: ZiAlign;
601
+ /** Callback invoked with the widget's element id immediately after mount. */
602
+ ref?: (id: number) => void;
603
+ }
604
+
605
+ export interface BoxProps extends ZiBaseProps {
606
+ /**
607
+ * **交叉轴**对齐。`Box` 与 `Column` 是 **column** 方向,交叉轴 = **横向** ——
608
+ * 所以在它们身上 `align` 管的是左右,不是上下。要竖向居中用 `justify`(主轴),
609
+ * 或者直接用 `center`(两轴一起,不必先答对是哪个轴)。
610
+ *
611
+ * 这条已经绊倒过 Dialog 的头、Badge 的 pill 与 TitleBar:给容器定了高、写
612
+ * `align="center"` 指望内容居中 —— **无效,内容贴顶,且不报错**。
613
+ * 回归测试见 `src/ui/vertical_center_test.zig`。
614
+ */
615
+ align?: ZiAlign;
616
+ /** **主轴**对齐。`Box` / `Column` 的主轴是**竖向**。 */
617
+ justify?: ZiJustify;
618
+ /** 两轴一起居中,与 flex-direction 无关。显式的 `align` / `justify` 仍压过它。 */
619
+ center?: boolean;
620
+ gap?: number;
621
+ }
622
+
623
+ export interface RowProps extends ZiBaseProps {
624
+ gap?: number;
625
+ /** **交叉轴**对齐。`Row` 是 row 方向,交叉轴 = **竖向** —— 这里的 `align` 才是上下。 */
626
+ align?: ZiAlign;
627
+ /** **主轴**对齐。`Row` 的主轴是**横向**。 */
628
+ justify?: ZiJustify;
629
+ /** 两轴一起居中,与 flex-direction 无关。显式的 `align` / `justify` 仍压过它。 */
630
+ center?: boolean;
631
+ }
632
+
633
+ export interface ColumnProps extends ZiBaseProps {
634
+ gap?: number;
635
+ /** **交叉轴**对齐 = **横向**(Column 是 column 方向)。竖向请用 `justify` 或 `center`。 */
636
+ align?: ZiAlign;
637
+ /** **主轴**对齐 = **竖向**。 */
638
+ justify?: ZiJustify;
639
+ /** 两轴一起居中,与 flex-direction 无关。显式的 `align` / `justify` 仍压过它。 */
640
+ center?: boolean;
641
+ }
642
+
643
+ export interface StackProps extends ZiBaseProps {
644
+ /** `DynamicStack` 没有 `apply_style` 钩子 —— 除 flex-item 外,`style` 对它没有效果(#0038)。 */
645
+ style?: ZiMinimalStyle;
646
+ align?: ZiAlign;
647
+ justify?: ZiJustify;
648
+ center?: boolean;
649
+ }
650
+
651
+ export interface ScrollableProps extends ZiBaseProps {
652
+ /** `Scrollable` 的 `apply_style` 只读 `display`,宽高走 `max_height`/`max_width` 这两个专用 prop(#0038)。 */
653
+ style?: ScrollableStyle;
654
+ direction?: "x" | "y" | "both";
655
+ max_height?: number;
656
+ max_width?: number;
657
+ horizontal?: boolean;
658
+ align?: ZiAlign;
659
+ scrollbar?: { thumb?: string; thumbHover?: string; thumbActive?: string; track?: string };
660
+ hideScrollbars?: boolean;
661
+ hideHorizontalScrollbar?: boolean;
662
+ hideVerticalScrollbar?: boolean;
663
+ }
664
+
665
+ export interface ListViewProps extends ZiBaseProps {
666
+ /** 只吃 `{display, width, height}`,不吃 padding/background/border 等(#0038)。 */
667
+ style?: ZiSizeOnlyStyle;
668
+ itemCount: number | (() => number);
669
+ rowHeight?: number;
670
+ /** Slot-capacity hint only. Viewport height follows `style.height` / parent constraints. */
671
+ viewportHeight?: number;
672
+ getText: (index: number) => string;
673
+ selectedIndex?: number | (() => number);
674
+ onSelect?: (index: number) => void;
675
+ /** Tree-style decoration seam (optional). Meta is fetched on assign /
676
+ * invalidate only — never during paint. */
677
+ getRowMeta?: (index: number) => ListViewRowMeta;
678
+ onToggle?: (index: number) => void;
679
+ onCheck?: (index: number) => void;
680
+ onRetry?: (index: number) => void;
681
+ }
682
+
683
+ export interface ListViewRowMeta {
684
+ indent?: number;
685
+ /** 0 none (column still reserved), 1 collapsed, 2 expanded. */
686
+ expander?: 0 | 1 | 2;
687
+ /** 0 none, 1 off, 2 indeterminate, 3 on. */
688
+ check?: 0 | 1 | 2 | 3;
689
+ /** 0 normal, 1 loading, 2 error (whole-row hit = retry, never selects). */
690
+ rowState?: 0 | 1 | 2;
691
+ }
692
+
693
+ export interface TreeNode {
694
+ id: string;
695
+ label: string;
696
+ /** Async (Promise-returning) nodes MUST set this; sync paths may probe. */
697
+ hasChildren?: boolean;
698
+ /** 图标列的 16 占位字形:"folder" | "file" | true(按有无子节点选)。 */
699
+ icon?: "folder" | "file" | boolean;
700
+ /** 同行次要文字(Int Hint,13/16 灰)。 */
701
+ hint?: string;
702
+ }
703
+
704
+ export interface TreeInstance {
705
+ visible: () => TreeRow[];
706
+ expand(id: string): void;
707
+ collapse(id: string): void;
708
+ toggle(id: string): void;
709
+ expandAll(): void;
710
+ collapseAll(): void;
711
+ /** Display tri-state: "on" | "off" | "indeterminate". */
712
+ isChecked(id: string): "on" | "off" | "indeterminate";
713
+ toggleCheck(id: string): void;
714
+ uncheck(id: string): void;
715
+ retry(id: string): void;
716
+ handleKey(key: number, mods: number): boolean;
717
+ selectId(id: string): void;
718
+ selected: { (): string | null; set(v: string | null): void };
719
+ rowText(index: number): string;
720
+ rowMeta(index: number): ListViewRowMeta;
721
+ }
722
+
723
+ export interface TreeRow {
724
+ id: string;
725
+ parentId: string | null;
726
+ depth: number;
727
+ label: string;
728
+ hasChildren: boolean;
729
+ expanded: boolean;
730
+ checkState: "on" | "off" | "indeterminate";
731
+ rowState: 0 | 1 | 2;
732
+ node: TreeNode | null;
733
+ }
734
+
735
+ export interface TabBarItem {
736
+ id: string;
737
+ label: string;
738
+ /** Default true. UI hides ×; single close(id) still removes it. */
739
+ closable?: boolean;
740
+ /** Shows a dot instead of × (unless hovered). */
741
+ dirty?: boolean;
742
+ /** Leading vector icon (same source convention as menu-item `icon`:
743
+ * a data-URL / path SVG, tinted to the theme's `TabBar.icon` colour).
744
+ * Live-updates on `items.set()` without rebuilding the row. */
745
+ icon?: string;
746
+ }
747
+
748
+ export interface TabBarInstance {
749
+ items(): TabBarItem[];
750
+ value: { (): string | null; set(v: string | null): void };
751
+ get(): string | null;
752
+ /** No-op when the id is absent. */
753
+ set(id: string): void;
754
+ isActive(id: string): () => boolean;
755
+ /** On id collision: replace-in-place (no onClose) and HONOR `activate`
756
+ * (defaults true). activate defaults true for new items too. */
757
+ add(item: TabBarItem, opts?: { activate?: boolean }): void;
758
+ /** Always removes (even closable:false — programmatic). */
759
+ close(id: string): void;
760
+ /** Batch ops SKIP closable===false entries. */
761
+ closeOthers(id: string): void;
762
+ closeRight(id: string): void;
763
+ closeAll(): void;
764
+ handleKey(key: number, mods: number): boolean;
765
+ }
766
+
767
+ export interface ComboboxInstance {
768
+ value: { (): string; set(v: string): void };
769
+ get(): string;
770
+ /** Silent set: no onChange, does not open the popup. */
771
+ set(v: string): void;
772
+ isOpen(): boolean;
773
+ /** Truncated to maxVisible; empty query = full list (≤ maxVisible). */
774
+ filtered(): string[];
775
+ /** Match count BEFORE the maxVisible slice. */
776
+ totalMatches(): number;
777
+ highlight(): number;
778
+ handleKey(key: number, mods: number): boolean;
779
+ Trigger(props?: { style?: any; disabled?: any; placeholder?: string }): any;
780
+ Content(props?: { style?: any; itemStyle?: any; maxHeight?: number; footerText?: (n: number) => string }): any;
781
+ }
782
+
783
+ export interface ComboboxProps {
784
+ value?: { (): string; set(v: string): void };
785
+ /** Reactive source; duplicate strings allowed (committed by index). */
786
+ options: () => string[];
787
+ /** Default: case-insensitive substring, input order preserved. */
788
+ filterFn?(text: string, options: string[]): string[];
789
+ maxVisible?: number;
790
+ /** Fires only when the value differs from the last COMMIT (Enter / row
791
+ * click while open; blur never commits; cb.set is silent). */
792
+ onChange?(v: string): void;
793
+ /** `zi/ui` preset:Int 结构 [输入 | 分隔 | 箭头按钮];箭头打开全量列表。 */
794
+ placeholder?: string | (() => string);
795
+ disabled?: boolean | (() => boolean);
796
+ /** 两档红边;非空字符串时聚焦期间弹校验气泡。 */
797
+ error?: ZiErrorProp;
798
+ style?: any;
799
+ panelStyle?: any;
800
+ itemStyle?: any;
801
+ maxHeight?: number;
802
+ footerText?: (n: number) => string;
803
+ }
804
+
805
+ export interface TreeProps {
806
+ /** 创建期交回 headless 实例(expand/collapse/toggle/expandAll/…)。 */
807
+ handle?: (tree: any) => void;
808
+ roots: () => TreeNode[];
809
+ getChildren: (id: string) => TreeNode[] | Promise<TreeNode[]>;
810
+ selectedId?: { (): string | null; set(v: string | null): void };
811
+ /** Fact-set semantics: an id in the set = its whole (incl. unloaded)
812
+ * subtree is selected. Update immutably: set(new Set(prev)). */
813
+ checked?: { (): Set<string>; set(v: Set<string>): void };
814
+ onSelect?: (node: TreeNode) => void;
815
+ onCheckedChange?: (checked: Set<string>) => void;
816
+ /** 所在区域是否持有焦点(默认 true);false 时选中块转灰(Int selected-inactive)。 */
817
+ active?: boolean | (() => boolean);
818
+ /** 图标列开关;不给则看根节点里有没有带 `icon` 的。 */
819
+ icons?: boolean;
820
+ }
821
+
822
+ export interface DropEntry { path: string; name: string; isDir: boolean }
823
+
824
+ /** Shape returned by `form.field(name)` — bind to Input/Textarea/Switch/Checkbox via the `field` prop. */
825
+ export interface FormField {
826
+ name: string;
827
+ value: () => any;
828
+ set: (v: any) => void;
829
+ error: () => any;
830
+ touched: () => boolean;
831
+ markTouched: () => void;
832
+ }
833
+
834
+ export interface ControlProps extends ZiBaseProps {
835
+ /** 叶子 widget,不布局 flex 子树 —— 不吃 flex 容器字段(align/justify/gap/…)或 margin(#0038)。 */
836
+ style?: ControlStyle;
837
+ disabled?: boolean;
838
+ cursor?: string;
839
+ onClick?: () => void;
840
+ onPress?: (...args: any[]) => void;
841
+ onRelease?: (...args: any[]) => void;
842
+ onLongPress?: (x: number, y: number) => void;
843
+ onHover?: (hovered: boolean) => void;
844
+ onPressChange?: (pressed: boolean) => void;
845
+ onFocusChange?: (focused: boolean) => void;
846
+ onContextMenu?: (x: number, y: number) => void;
847
+ /** Middle click — DEEPEST Control only (no bubble); disabled targets
848
+ * consume silently. Browser-tab middle-click-to-close semantics. */
849
+ onMiddlePress?: (x: number, y: number) => void;
850
+ onDragMove?: (dx: number, dy: number) => void;
851
+ onDragOver?: (isOver: boolean) => void;
852
+ onDrop?: (entries: DropEntry[], x: number, y: number) => void;
853
+ /** Tab-order sort key (#0039). `< 0` removes it from Tab entirely (still
854
+ * focusable by click/`zi.focus.set`); `0` (default) = tree order;
855
+ * `> 0` sorts ahead of every `<= 0` element, ascending — HTML `tabindex`
856
+ * semantics. */
857
+ tabIndex?: number;
858
+ /** Claim focus once, at mount (#0039). Last-constructed wins if more
859
+ * than one element in the same render pass sets this. */
860
+ autofocus?: boolean;
861
+ }
862
+
863
+ export interface TextProps extends ZiBaseProps {
864
+ /** 纯文本,不参与布局 —— 不吃 `width`/`height`/padding/background 等 box model 键(#0038)。 */
865
+ style?: TextStyle;
866
+ text?: string;
867
+ }
868
+
869
+ export interface ImageProps extends ZiBaseProps {
870
+ /** 不走 `apply_style` 钩子,`width`/`height`/`color` 走专用桥接;不吃 `radius`(只认下面的顶层 `radius` prop)(#0038)。 */
871
+ style?: ImageStyle;
872
+ src?: string;
873
+ vector?: boolean;
874
+ radius?: number;
875
+ fit?: "contain" | "cover" | "fill";
876
+ /** 单色着色(SVG `currentColor`);raster 忽略。 */
877
+ color?: string;
878
+ /** 渲染宽/高(px)。亦可写在 `style`(对等);两者皆可。 */
879
+ width?: number;
880
+ height?: number;
881
+ }
882
+
883
+ export interface InputProps extends ZiBaseProps {
884
+ /** 叶子 widget —— 不吃 flex 容器字段、margin、overflow/cursor/translate_y(#0038)。 */
885
+ style?: InputStyle;
886
+ /**
887
+ * 初值。传 accessor(signal / thunk)时**只在创建期 untrack 读一次** —— 不订阅,
888
+ * 用户打字也不写回那个 signal。之后改值走 `zi.setInputValue(el, s)`。
889
+ * 要双向绑定用 `zi/ui` 的 `<Input>`(headless core 在 onChange 里 `value.set`)。
890
+ */
891
+ value?: string | (() => string);
892
+ placeholder?: string;
893
+ disabled?: boolean;
894
+ readonly?: boolean;
895
+ password?: boolean;
896
+ maxLength?: number;
897
+ field?: FormField;
898
+ onInput?: (value: string) => void;
899
+ onChange?: (value: string) => void;
900
+ /** See `ControlProps.tabIndex` (#0039). */
901
+ tabIndex?: number;
902
+ /** See `ControlProps.autofocus` (#0039). */
903
+ autofocus?: boolean;
904
+ /** `zi/ui`:前 / 后槽位 —— 图标 URL(16px,跟主题着色)或任意 widget。 */
905
+ prefix?: string | number;
906
+ suffix?: string | number;
907
+ /** `zi/ui`:Int 两档红边(未聚焦浅红 / 聚焦实红);非空字符串时聚焦期间弹校验气泡。 */
908
+ error?: ZiErrorProp;
909
+ }
910
+
911
+ /** 输入类的 error:布尔只画红边,字符串还会在聚焦时弹校验气泡。 */
912
+ export type ZiErrorProp = boolean | string | (() => boolean | string);
913
+
914
+ export interface TextareaProps extends ZiBaseProps {
915
+ /** 不吃 `width`/`height`(靠 `rows` 定尺,不是 style)、flex 容器字段、margin(#0038)。 */
916
+ style?: TextareaStyle;
917
+ /** 同 `InputProps.value`:accessor 只在创建期读一次,之后走 `zi.setTextareaValue`。 */
918
+ value?: string | (() => string);
919
+ placeholder?: string;
920
+ disabled?: boolean;
921
+ readonly?: boolean;
922
+ rows?: number;
923
+ field?: FormField;
924
+ /** `zi/ui`:同 `InputProps.error`。 */
925
+ error?: ZiErrorProp;
926
+ onInput?: (value: string) => void;
927
+ onChange?: (value: string) => void;
928
+ /** See `ControlProps.tabIndex` (#0039). */
929
+ tabIndex?: number;
930
+ /** See `ControlProps.autofocus` (#0039). */
931
+ autofocus?: boolean;
932
+ }
933
+
934
+ export type EditorDocument = number;
935
+
936
+ export interface CodeEditorProps extends ZiBaseProps {
937
+ /** 吃 font_family/line_height,明确不吃 font_weight/text_align/width/height(#0038)。 */
938
+ style?: CodeEditorStyle;
939
+ /** Controlled text when `document` is absent; ignored while a document is bound. */
940
+ text?: string;
941
+ /** Persistent text/history/folds/selection/scroll/language state. */
942
+ document?: EditorDocument;
943
+ editable?: boolean;
944
+ /** CSS `disabled` overlay and no keyboard input. The engine default style fades to opacity 0.5; a later `setStyle` replaces that unless `style.disabled` sets opacity. */
945
+ disabled?: boolean;
946
+ tabSize?: number;
947
+ rows?: number;
948
+ startLine?: number;
949
+ autoHeight?: boolean;
950
+ lineNumbers?: boolean;
951
+ /** See `ControlProps.tabIndex` (#0039). */
952
+ tabIndex?: number;
953
+ /** See `ControlProps.autofocus` (#0039). */
954
+ autofocus?: boolean;
955
+ }
956
+
957
+ export interface EditorAPI {
958
+ createDocument(opts?: { text?: string; language?: any }): EditorDocument;
959
+ /** Replace document text and clear its undo/fold/selection state. */
960
+ setText(document: EditorDocument, text: string): void;
961
+ setLanguage(document: EditorDocument, language: any): void;
962
+ /** Detaches a live viewport before releasing the document. */
963
+ destroyDocument(document: EditorDocument): void;
964
+ }
965
+
966
+ export interface ModalProps extends ZiBaseProps {
967
+ /** `Modal` 没有 `apply_style` 钩子 —— 除 flex-item 外,`style` 对它没有效果;弹层外观走主题,不走这个 prop(#0038)。 */
968
+ style?: ZiMinimalStyle;
969
+ open?: boolean | Signal<boolean>;
970
+ align?: string;
971
+ backdropColor?: string;
972
+ onBackdropClick?: () => void;
973
+ }
974
+
975
+ export interface CheckmarkProps extends ZiBaseProps {
976
+ /** 只吃 `color`/`text_color`(勾的描边色),其余键无效(#0038)。 */
977
+ style?: CheckmarkStyle;
978
+ checked?: boolean;
979
+ }
980
+
981
+ export /** `__zi_chart_set_options` 的旋钮表。全部可选;`null` = 关掉,`undefined` = 不动。 */
982
+ interface ZiChartOptions {
983
+ // 通用
984
+ color?: any;
985
+ track?: any | null;
986
+ // LineChart
987
+ lineWidth?: number;
988
+ smooth?: boolean;
989
+ area?: number | null;
990
+ threshold?: number | null;
991
+ thresholdColor?: any;
992
+ grid?: any | null;
993
+ gridDivisions?: number;
994
+ yMin?: number | null;
995
+ yMax?: number | null;
996
+ // BarChart
997
+ horizontal?: boolean;
998
+ maxValue?: number | null;
999
+ warnAt?: number | null;
1000
+ critAt?: number | null;
1001
+ warnColor?: any;
1002
+ critColor?: any;
1003
+ gap?: number;
1004
+ radius?: number;
1005
+ // PieChart
1006
+ innerRatio?: number;
1007
+ gapDeg?: number;
1008
+ startDeg?: number;
1009
+ depth?: number;
1010
+ shadow?: number;
1011
+ shadowOffset?: number;
1012
+ // Ring
1013
+ gauge?: boolean;
1014
+ thickness?: number | null;
1015
+ canvas?: any | null;
1016
+ }
1017
+
1018
+ export interface DividerProps extends ZiBaseProps {
1019
+ /** `Divider` 没有 `apply_style` 钩子 —— 颜色/粗细/inset 走上面这几个顶层 prop,不走 `style`(#0038)。 */
1020
+ style?: ZiMinimalStyle;
1021
+ vertical?: boolean;
1022
+ direction?: string;
1023
+ inset?: number;
1024
+ color?: string;
1025
+ highlight?: string;
1026
+ }
1027
+
1028
+ /** `<Alert>`(`zi/ui`)—— 内联警示条。画廊的 `.alert` 与 `.note-banner` 共用一块
1029
+ * CSS,这里也是一个组件:给 `title` 就是「标题在上、正文在下」,不给就是单行。 */
1030
+ export interface AlertProps extends ZiBaseProps {
1031
+ kind?: "info" | "success" | "warning" | "danger";
1032
+ /** "inline"(默认,两行卡片 r8)| "banner"(全宽 40 高、直角、只画底边) */
1033
+ variant?: "inline" | "banner";
1034
+ /** 正文前加粗的一段(与正文同一段落)。`lead` 是旧名。 */
1035
+ title?: string;
1036
+ lead?: string;
1037
+ /** 链接动作 */
1038
+ actions?: { text: string; onClick?: () => void }[];
1039
+ more?: { text?: string; items: any[]; onSelect?: (value: any, item: any) => void };
1040
+ /** ⋮ 下拉工具钮(items/onSelect 同 Menu)—— settings 钮之后、close 之前 */
1041
+ menu?: { items: any[]; onSelect?: (value: any, item: any) => void };
1042
+ onSettings?: () => void;
1043
+ onClose?: () => void;
1044
+ /** false 时不画状态图标 */
1045
+ icon?: boolean;
1046
+ style?: any;
1047
+ }
1048
+
1049
+ type ZiBool = boolean | (() => boolean);
1050
+ type ZiCheckedSource = boolean | { (): boolean; set?(v: boolean): void } | (() => boolean);
1051
+
1052
+ /** `<Checkbox>`(`zi/ui`)—— Int checkbox:32px 行、16 框、两类焦点、error、hint。 */
1053
+ export interface CheckboxProps extends ZiBaseProps {
1054
+ label?: string | (() => string);
1055
+ checked?: ZiCheckedSource;
1056
+ disabled?: ZiBool;
1057
+ /** 未选中时画半选横条;点击仍切 checked。 */
1058
+ indeterminate?: ZiBool;
1059
+ error?: ZiBool;
1060
+ hint?: string | (() => string);
1061
+ hintPosition?: "inline" | "below";
1062
+ field?: FormField;
1063
+ onChange?: (checked: boolean) => void;
1064
+ partStyles?: { root?: any; box?: any; indicator?: any; label?: any };
1065
+ }
1066
+ export interface CheckboxGroupProps extends ZiBaseProps {
1067
+ options: { label: string; value: any; disabled?: boolean; hint?: string }[];
1068
+ value?: { (): any[]; set(v: any[]): void };
1069
+ field?: FormField;
1070
+ disabled?: ZiBool;
1071
+ direction?: "x" | "y";
1072
+ onChange?: (values: any[], opt: any) => void;
1073
+ }
1074
+ /** `<Radio>`(`zi/ui`)—— Int radio,与 Checkbox 同构。 */
1075
+ export interface RadioProps extends ZiBaseProps {
1076
+ label?: string | (() => string);
1077
+ checked?: ZiCheckedSource;
1078
+ disabled?: ZiBool;
1079
+ error?: ZiBool;
1080
+ hint?: string | (() => string);
1081
+ hintPosition?: "inline" | "below";
1082
+ onChange?: () => void;
1083
+ partStyles?: { root?: any; ring?: any; dot?: any; label?: any };
1084
+ }
1085
+ /** `<RadioGroup>`:整组一个 tab stop,方向键 / Home / End 移动并选中。 */
1086
+ export interface RadioGroupProps extends ZiBaseProps {
1087
+ options: { label: string; value: any; disabled?: boolean; hint?: string }[];
1088
+ value?: { (): any; set(v: any): void };
1089
+ field?: FormField;
1090
+ disabled?: ZiBool;
1091
+ direction?: "x" | "y";
1092
+ onChange?: (value: any, opt: any) => void;
1093
+ }
1094
+ /** `<Switch>`(`zi/ui`)—— Int OnOffButton:53×20,带 ON / OFF 字的填充块平移。 */
1095
+ export interface SwitchProps extends ZiBaseProps {
1096
+ /** zi 扩展:开关右侧的标签(Int 的开关无标签)。 */
1097
+ label?: string | (() => string);
1098
+ checked?: ZiCheckedSource;
1099
+ disabled?: ZiBool;
1100
+ field?: FormField;
1101
+ onChange?: (checked: boolean) => void;
1102
+ partStyles?: { root?: any; track?: any; fill?: any; text?: any; label?: any };
1103
+ }
1104
+ /** `<Select>`(`zi/ui`)—— Int Dropdown。`variant="toolbar"` 是 `Label: Value ⌄` 形态。 */
1105
+ export interface SelectProps extends ZiBaseProps {
1106
+ options: (string | { label: string | (() => string); value: any; disabled?: boolean;
1107
+ icon?: string; secondary?: string | (() => string) })[];
1108
+ value?: { (): any; set(v: any): void };
1109
+ defaultValue?: any;
1110
+ placeholder?: string | (() => string);
1111
+ onChange?: (value: any, opt: any) => void;
1112
+ placement?: "bottom" | "top";
1113
+ gap?: number;
1114
+ disabled?: ZiBool;
1115
+ field?: FormField;
1116
+ variant?: "default" | "toolbar";
1117
+ /** toolbar 形态的前缀(自动补冒号)。 */
1118
+ label?: string | (() => string);
1119
+ error?: ZiErrorProp;
1120
+ }
1121
+ /** `<Search>`(`zi/ui`)—— Int 搜索框:放大镜 · 输入 · 清除 × · 选项切换(22×22)。 */
1122
+ export interface SearchProps extends ZiBaseProps {
1123
+ value?: { (): string; set(v: string): void } | string;
1124
+ placeholder?: string | (() => string);
1125
+ onChange?: (value: string) => void;
1126
+ onInput?: (value: string) => void;
1127
+ onSubmit?: (value: string) => void;
1128
+ disabled?: ZiBool;
1129
+ error?: ZiErrorProp;
1130
+ options?: { icon: string; label?: string; checked: ZiCheckedSource }[];
1131
+ style?: any;
1132
+ }
1133
+ /** `<Field>`(`zi/ui`)—— Int 带标签的表单行:`Label:` 在左、提示在框下。 */
1134
+ export interface FieldProps extends ZiBaseProps {
1135
+ label?: string | (() => string);
1136
+ hint?: string | (() => string);
1137
+ /** zi 扩展:取代 hint 的红字(Int 的错误走控件自己的校验气泡)。 */
1138
+ error?: string | (() => string);
1139
+ /** "horizontal"(默认,Int)| "vertical"(zi 扩展:标签在上)。 */
1140
+ layout?: "horizontal" | "vertical";
1141
+ /** 横排标签列宽 —— 同组字段的框左缘对齐。 */
1142
+ labelWidth?: number;
1143
+ style?: any;
1144
+ }
1145
+ /** `<Kbd>`(`zi/ui`)—— Int 快捷键键帽;`keys` 是字符串时按 "+" 拆成多帽。 */
1146
+ export interface KbdProps extends ZiBaseProps {
1147
+ keys?: string | string[];
1148
+ style?: any;
1149
+ }
1150
+ /** `<PaneHead>`(`zi/ui`)—— Int tool window header:40 + 1px 槽,标题 semibold,children = 右侧动作。 */
1151
+ export interface PaneHeadProps extends ZiBaseProps {
1152
+ title?: string | (() => string);
1153
+ /** 标题后内联的 widget(TabBar、「+」按钮…)。 */
1154
+ tabs?: any | any[];
1155
+ /** 画底分隔线(默认不画,槽透明)。 */
1156
+ divider?: boolean;
1157
+ /** 中段分节头:加顶线。 */
1158
+ sep?: boolean;
1159
+ style?: any;
1160
+ }
1161
+ /** `<StatusBar>` 一段:字符串 / thunk(静态)、`{ text, onClick }`(可点 widget)或 widget。 */
1162
+ export type StatusBarItem = string | (() => string) | { text: string | (() => string); onClick?: () => void } | any;
1163
+ export interface StatusBarProps extends ZiBaseProps {
1164
+ left?: StatusBarItem[];
1165
+ right?: StatusBarItem[];
1166
+ style?: any;
1167
+ }
1168
+ /** `<ToolWindowStripe>`(`zi/ui`)—— 40 + 1px 的工具窗按钮条。 */
1169
+ export interface ToolWindowStripeProps extends ZiBaseProps {
1170
+ side?: "left" | "right";
1171
+ top?: any[];
1172
+ bottom?: any[];
1173
+ style?: any;
1174
+ }
1175
+ /** `<StripeButton>` —— 30×30 r6、20 图标;`selected` = 工具窗已打开(accent 实底白图标)。 */
1176
+ export interface StripeButtonProps {
1177
+ icon: string | (() => string);
1178
+ selected?: boolean | (() => boolean);
1179
+ onClick?: () => void;
1180
+ }
1181
+ /** `<EditorHint>`(`zi/ui`)—— Int 编辑器内提示气泡;children = 自定义内容。 */
1182
+ export interface EditorHintProps extends ZiBaseProps {
1183
+ status?: "default" | "success" | "warning" | "error";
1184
+ header?: string | (() => string);
1185
+ text?: string | (() => string);
1186
+ hint?: string | (() => string);
1187
+ onMore?: () => void;
1188
+ /** 给了就浮在该 widget 上方(`placement="bottom"` 则下方),由 `open` 控制。 */
1189
+ anchor?: any;
1190
+ open?: { (): boolean; set?(v: boolean): void };
1191
+ placement?: "top" | "bottom";
1192
+ onClose?: () => void;
1193
+ style?: any;
1194
+ }
1195
+ /** `<GotIt>`(`zi/ui`)—— Int「Got It」引导气泡,宽 280。 */
1196
+ export interface GotItProps extends ZiBaseProps {
1197
+ header?: string | (() => string);
1198
+ text?: string | (() => string);
1199
+ link?: { text: string; onClick?: () => void };
1200
+ /** 左列步骤号(如 "01")/ 右上步骤号(如 "01/03")。 */
1201
+ step?: string;
1202
+ stepRight?: string;
1203
+ media?: any;
1204
+ buttonText?: string;
1205
+ onGotIt?: () => void;
1206
+ skipText?: string;
1207
+ onSkip?: () => void;
1208
+ anchor?: any;
1209
+ open?: { (): boolean; set?(v: boolean): void };
1210
+ onClose?: () => void;
1211
+ style?: any;
1212
+ }
1213
+ /** `<TitleBar>`(`zi/window`)—— Int Main Toolbar 40。 */
1214
+ export interface TitleBarProps extends ZiBaseProps {
1215
+ title?: string;
1216
+ icon?: any;
1217
+ left?: any[];
1218
+ right?: any[];
1219
+ /** `right` 的旧名。 */
1220
+ headerLeft?: any;
1221
+ header?: "light" | "dark";
1222
+ platform?: "win" | "mac";
1223
+ onClose?: () => void;
1224
+ onMinimize?: () => void;
1225
+ onMaximize?: () => void;
1226
+ maximized?: boolean | (() => boolean);
1227
+ style?: any;
1228
+ }
1229
+ /** `<MainToolbarWidget>`(`zi/window`)—— 项目 / 分支 / 运行配置那种 30 高下拉 widget。 */
1230
+ export interface MainToolbarWidgetProps {
1231
+ text?: string | (() => string);
1232
+ /** 项目徽章字(20×20 r4);与 `icon` 二选一。 */
1233
+ badge?: string;
1234
+ badgeColor?: string | (() => string);
1235
+ icon?: string | (() => string);
1236
+ iconColor?: string | (() => string);
1237
+ chevron?: boolean;
1238
+ onClick?: () => void;
1239
+ }
1240
+ /** `<MainToolbarButton>`(`zi/window`)—— 30×30 r6、20 图标;`color="run"` 取运行绿。 */
1241
+ export interface MainToolbarButtonProps {
1242
+ icon: string | (() => string);
1243
+ color?: "run" | string | (() => string);
1244
+ onClick?: () => void;
1245
+ }
1246
+ /** `<Toolbar>`(`zi/ui`)—— Int ActionToolbar:高 34、无底无边,22 r4 图标按钮节距 26。 */
1247
+ export interface ToolbarProps extends ZiBaseProps {
1248
+ /** "plain"(默认;旧名 "panel" 同义)| "floating"(r8 + 描边 + 面)| "pane"(zi 窗格工具栏)。 */
1249
+ variant?: "plain" | "panel" | "floating" | "pane";
1250
+ orientation?: "horizontal" | "vertical";
1251
+ items?: any[];
1252
+ style?: any;
1253
+ }
1254
+ /** `<ToolbarSep>` —— 1×20 竖分隔;竖向工具栏里自动横置;`full` 满高(内嵌搜索框后那条)。 */
1255
+ export interface ToolbarSepProps { full?: boolean }
1256
+ /** `<ToolbarButton>` —— 22×22 r4 的 16 图标动作按钮,hover / 按下半透明叠加。 */
1257
+ export interface ToolbarButtonProps {
1258
+ icon: string | (() => string);
1259
+ onClick?: () => void;
1260
+ /** 图标右下叠 4×4 下拉角标。 */
1261
+ dropdown?: boolean;
1262
+ /** 切换按钮的按下态。 */
1263
+ checked?: boolean | (() => boolean);
1264
+ disabled?: boolean | (() => boolean);
1265
+ /** 覆盖图标色(如「有待处理」的 accent)。 */
1266
+ color?: string | (() => string);
1267
+ }
1268
+ /** `<GroupHeader>`(`zi/ui`)—— Int 分组标题:[箭头] 标题 · 1px 线撑满 · [children = 右侧动作]。 */
1269
+ export interface GroupHeaderProps extends ZiBaseProps {
1270
+ title?: string | (() => string);
1271
+ collapsible?: boolean;
1272
+ open?: { (): boolean; set?(v: boolean): void };
1273
+ onToggle?: (open: boolean) => void;
1274
+ actions?: any[];
1275
+ style?: any;
1276
+ }
1277
+ /** `<Progress>`(`zi/ui`)—— Int 进度条:条高 4;给 label / hint / onCancel 时是复合布局。 */
1278
+ export interface ProgressProps extends ZiBaseProps {
1279
+ value?: number | (() => number);
1280
+ indeterminate?: boolean | (() => boolean);
1281
+ label?: string | (() => string);
1282
+ labelPosition?: "inline" | "top";
1283
+ hint?: string | (() => string);
1284
+ onCancel?: () => void;
1285
+ height?: number;
1286
+ tone?: "primary" | "success" | "warning" | "danger";
1287
+ color?: string | (() => string);
1288
+ ring?: boolean;
1289
+ trackColor?: string | (() => string);
1290
+ }
1291
+ /** `<Spinner>`(`zi/ui`,Int Loader)—— 8 辐条中性灰风车,8 帧步进。 */
1292
+ export interface SpinnerProps {
1293
+ size?: "sm" | "md" | "lg" | number;
1294
+ color?: string | (() => string);
1295
+ }
1296
+ /** `<FindBar>`(`zi/ui`)—— Int 编辑器查找条:展开格 | 搜索格(历史 · 输入 · 选项)| 结果格(计数 · ↑↓ · ×)。 */
1297
+ export interface FindBarProps extends ZiBaseProps {
1298
+ value?: { (): string; set(v: string): void };
1299
+ placeholder?: string;
1300
+ /** 结果计数文字,如 `() => "1 / 10"`。 */
1301
+ count?: string | (() => string);
1302
+ matchCase?: { (): boolean; set(v: boolean): void };
1303
+ words?: { (): boolean; set(v: boolean): void };
1304
+ regex?: { (): boolean; set(v: boolean): void };
1305
+ expanded?: { (): boolean; set(v: boolean): void };
1306
+ onToggleReplace?: (expanded: boolean) => void;
1307
+ onChange?: (v: string) => void;
1308
+ onNext?: () => void;
1309
+ onPrev?: () => void;
1310
+ onClose?: () => void;
1311
+ style?: any;
1312
+ }
1313
+ /** `<InlineCode>`(`zi/ui`)—— Int 行内代码样例:1px 边、透明底、mono。 */
1314
+ export interface InlineCodeProps extends ZiBaseProps {
1315
+ text?: string | (() => string);
1316
+ style?: any;
1317
+ }
1318
+
1319
+ /** Popup 行(`<Menu>` / `<ContextMenu>` 的 `items`)。`children` = 子菜单(点击展开)。 */
1320
+ export interface MenuItemSpec {
1321
+ label?: string | (() => string);
1322
+ value?: any;
1323
+ shortcut?: string;
1324
+ icon?: string;
1325
+ checked?: ZiCheckedSource;
1326
+ color?: string;
1327
+ danger?: boolean;
1328
+ disabled?: ZiBool;
1329
+ children?: MenuItemSpec[];
1330
+ separator?: boolean;
1331
+ sectionLabel?: string | (() => string);
1332
+ }
1333
+ /** `<Menu>` / `<ContextMenu>`(`zi/ui`)—— Int Popup:行 24、内缩浅蓝选中块、菜单级图标列。 */
1334
+ export interface MenuProps extends ZiBaseProps {
1335
+ items: MenuItemSpec[] | (() => MenuItemSpec[]);
1336
+ onSelect?: (value: any, item: MenuItemSpec) => void;
1337
+ /** 可选标题头 */
1338
+ title?: string | (() => string);
1339
+ /** 可选搜索头:占位符(或 true),按标签过滤数组 items */
1340
+ search?: string | boolean;
1341
+ /** 可选底部提示条 */
1342
+ advertiser?: string | (() => string);
1343
+ placement?: "bottom" | "top" | "left" | "right";
1344
+ gap?: number;
1345
+ panelStyle?: any;
1346
+ itemStyle?: any;
1347
+ }
1348
+ /** `<Tooltip>`(`zi/ui`)—— Int 反相气泡;给 `description` 即富提示(宽 ≤251)。 */
1349
+ export interface TooltipProps extends ZiBaseProps {
1350
+ tip: string | (() => string);
1351
+ shortcut?: string | (() => string);
1352
+ description?: string | (() => string);
1353
+ link?: { text: string | (() => string); onClick?: () => void };
1354
+ placement?: "top" | "bottom" | "left" | "right";
1355
+ delay?: number;
1356
+ gap?: number;
1357
+ trigger?: "hover" | "click";
1358
+ }
1359
+ type ZiButtonSpec = { text?: string; variant?: string; onClick?: () => void; disabled?: ZiBool; [k: string]: any };
1360
+ /** `<Dialog>`(`zi/ui`)—— Int 窗口式对话框:标题栏居中、无 ×;底栏 help + 复选框 + 按钮组。 */
1361
+ export interface DialogProps extends ZiBaseProps {
1362
+ open: { (): boolean; set(v: boolean): void };
1363
+ title?: string | (() => string);
1364
+ /** 旧名,等同 title */
1365
+ head?: string | (() => string);
1366
+ description?: string | (() => string);
1367
+ /** 按钮 props 数组(右对齐 gap 12,按给的顺序)或任意 widget */
1368
+ actions?: ZiButtonSpec[] | number;
1369
+ help?: () => void;
1370
+ checkbox?: { label: string; checked?: ZiCheckedSource; hint?: string } | (() => boolean);
1371
+ /** 头 / 底 1px 分隔线 */
1372
+ separators?: boolean;
1373
+ /** zi 扩展:半透明遮罩(Int 无,默认关) */
1374
+ backdrop?: boolean;
1375
+ onClose?: () => void;
1376
+ }
1377
+ /** `<MessageDialog>`(`zi/ui`)—— Int alert:28 状态图标 + 16/20 标题 + 正文 + 可选「Do not ask again」。 */
1378
+ export interface MessageDialogProps extends ZiBaseProps {
1379
+ open: { (): boolean; set(v: boolean): void };
1380
+ kind?: "question" | "warning" | "error";
1381
+ title: string | (() => string);
1382
+ message?: string | (() => string);
1383
+ doNotAsk?: { (): boolean; set(v: boolean): void } | { label: string; checked?: ZiCheckedSource };
1384
+ actions?: ZiButtonSpec[] | number;
1385
+ help?: () => void;
1386
+ backdrop?: boolean;
1387
+ onClose?: () => void;
1388
+ }
1389
+
1390
+ /** `<Link>`(`zi/ui`)—— Int ActionLink:28px 行里的蓝色文字,hover 加下划线、不换色。 */
1391
+ export interface LinkProps extends ZiBaseProps {
1392
+ text?: string;
1393
+ onClick?: () => void;
1394
+ disabled?: boolean | (() => boolean);
1395
+ /** `external` = 右上箭头(打开外部);`dropdown` = 下拉三角(点开弹菜单)。 */
1396
+ icon?: "external" | "dropdown";
1397
+ /** 覆盖链接字色 / 图标色(深色气泡或语义底上) */
1398
+ color?: string;
1399
+ iconColor?: string;
1400
+ style?: ZiStyle;
1401
+ }
1402
+
1403
+
1404
+ export interface Library {
1405
+ [method: string]: (...args: any[]) => Promise<any>;
1406
+ }
1407
+
1408
+ export type FfiArgKind =
1409
+ | "void"
1410
+ | "i32"
1411
+ | "i64"
1412
+ | "f32"
1413
+ | "f64"
1414
+ | "bool"
1415
+ | "string"
1416
+ | "buffer";
1417
+
1418
+ export interface FfiDecl {
1419
+ args: FfiArgKind[];
1420
+ returns?: FfiArgKind;
1421
+ free?: string;
1422
+ }
1423
+
1424
+ export interface FfiAPI {
1425
+ load(path: string, decls: Record<string, FfiDecl>): Promise<Library>;
1426
+ }
1427
+
1428
+ export type ResizeEdge = "n" | "s" | "e" | "w" | "ne" | "nw" | "se" | "sw";
1429
+
1430
+ export interface PlatformAPI {
1431
+ getWindowPos(): { x: number; y: number };
1432
+ getWindowSize(): { w: number; h: number };
1433
+ setWindowPos(x: number, y: number): void;
1434
+ setWindowSize(w: number, h: number): void;
1435
+ /**
1436
+ * Set the window's minimum size, enforced by the platform/compositor.
1437
+ *
1438
+ * Required alongside `startWindowResize`: once the compositor drives the
1439
+ * resize it computes the geometry itself and never sees an app-side clamp.
1440
+ */
1441
+ setMinWindowSize(w: number, h: number): void;
1442
+ /**
1443
+ * Declare the INVISIBLE margin around the window — the transparent gutter a
1444
+ * self-drawn shadow bleeds into.
1445
+ *
1446
+ * Without it the window manager only knows the window rect, so snapping,
1447
+ * tiling and maximise align the *gutter* to the screen edge and the visible
1448
+ * frame ends up a gutter-width short. Pass all zeros to clear.
1449
+ *
1450
+ * X11 only today (`_GTK_FRAME_EXTENTS`); no-op elsewhere.
1451
+ */
1452
+ setFrameExtents(l: number, r: number, t: number, b: number): void;
1453
+ /**
1454
+ * Hand the in-flight drag to the compositor / window manager.
1455
+ *
1456
+ * Returns `true` when it took over: the compositor now owns the pointer,
1457
+ * moves the window itself, and your handler will receive no further motion
1458
+ * for this gesture — stop doing `setWindowPos` math. Returns `false` where
1459
+ * unsupported (mobile, macOS, a WM without `_NET_WM_MOVERESIZE`), in which
1460
+ * case fall back to the manual path.
1461
+ *
1462
+ * Call it on the FIRST drag-move, not on press — that keeps the drag
1463
+ * threshold, and on Wayland the input serial is still the button's.
1464
+ */
1465
+ startWindowDrag(): boolean;
1466
+ /** Interactive resize from `edge`. Same contract as `startWindowDrag`. */
1467
+ startWindowResize(edge: ResizeEdge): boolean;
1468
+ maximize(): void;
1469
+ minimize(): void;
1470
+ restore(): void;
1471
+ maximized: () => boolean;
1472
+ /** Show the soft keyboard / IME (mobile); no-op on desktop. */
1473
+ imeShow(...args: any[]): void;
1474
+ /**
1475
+ * 主动丢掉所有可重建的缓存(DisplayList + 未被引用的纹理 + JS 堆 GC)。
1476
+ * 画面不变 —— 下一帧按需重录 / 重新上传。移动端系统内存告急时由平台调用;
1477
+ * 桌面上可以手动调(刚干完一件吃内存的事之后)。
1478
+ */
1479
+ memoryPressure(): void;
1480
+ /** Hide the soft keyboard / IME. */
1481
+ imeHide(...args: any[]): void;
1482
+ /**
1483
+ * This build's "primary" chord modifier bit — Cmd on macOS, Ctrl
1484
+ * elsewhere. Compare against it directly, or prefer
1485
+ * `zi.keymap.bind({ key, primary: true }, fn)`, instead of hand-
1486
+ * rolling an OS check for shortcuts / hint text (#0039).
1487
+ */
1488
+ primaryMod: number;
1489
+ /** Named chord-modifier bits (#0039) — compare `primaryMod` against
1490
+ * these instead of a bare number. Same layout `zi.keymap.bind`'s
1491
+ * `mods` uses. */
1492
+ MOD_SHIFT: number;
1493
+ MOD_CONTROL: number;
1494
+ MOD_ALT: number;
1495
+ MOD_SUPER: number;
1496
+ }
1497
+
1498
+ /** `zi.toast.push` 的入参。`msg` 是 `title` 的别名(v1 的调用方式,仍受支持)。
1499
+ * `time` 与 `closable` 决定右上角放什么,**二选一**:closable 优先。 */
1500
+ export interface ToastOptions {
1501
+ title?: string;
1502
+ /** @deprecated 用 `title`。留着是因为 v1 的调用方式仍在用。 */
1503
+ msg?: string;
1504
+ desc?: string;
1505
+ kind?: "info" | "success" | "warning" | "danger";
1506
+ /** ms;默认 4000,传 0 关掉自动消失。 */
1507
+ ttl?: number;
1508
+ /** @deprecated Int 通知没有时间戳,`zi/ui` 的 Toaster 不渲染它;仍随 item 保存,自绘 toast 可读。 */
1509
+ time?: string;
1510
+ /** 默认 true:右上角 × 在 hover 时出现;false 去掉。 */
1511
+ closable?: boolean;
1512
+ /** 动作行首的 secondary 按钮 */
1513
+ action?: { text: string; onClick?: () => void };
1514
+ /** 动作行里的链接 */
1515
+ links?: { text: string; onClick?: () => void }[];
1516
+ /** 动作行尾的「More ▾」下拉 */
1517
+ more?: { text?: string; items: any[]; onSelect?: (value: any, item: any) => void };
1518
+ /** 右上角 ⋮ 菜单(hover 出现) */
1519
+ menu?: { items: any[]; onSelect?: (value: any, item: any) => void };
1520
+ }
1521
+
1522
+ export interface ToastAPI {
1523
+ push(opts?: ToastOptions): number;
1524
+ dismiss(...args: any[]): any;
1525
+ clear(...args: any[]): any;
1526
+ list(...args: any[]): any;
1527
+ [k: string]: any;
1528
+ }
1529
+
1530
+ export interface PortalAPI {
1531
+ append(...args: any[]): any;
1532
+ remove(...args: any[]): any;
1533
+ has(...args: any[]): any;
1534
+ /** Push an ESC handler onto the stack; returns a token for `clearEsc`. ESC
1535
+ * invokes the topmost handler (innermost overlay first). */
1536
+ onEsc(fn: () => void): number;
1537
+ /** Remove the ESC handler registered under `token` (from `onEsc`). */
1538
+ clearEsc(token: number): void;
1539
+ setChildren(...args: any[]): any;
1540
+ clear(...args: any[]): any;
1541
+ [k: string]: any;
1542
+ }
1543
+
1544
+ export interface FocusAPI {
1545
+ newGroup(...args: any[]): any;
1546
+ current(...args: any[]): any;
1547
+ set(...args: any[]): any;
1548
+ setKey(...args: any[]): any;
1549
+ setTrap(...args: any[]): any;
1550
+ clearTrap(...args: any[]): any;
1551
+ clear(...args: any[]): any;
1552
+ next(...args: any[]): any;
1553
+ register(...args: any[]): any;
1554
+ unregister(...args: any[]): any;
1555
+ [k: string]: any;
1556
+ }
1557
+
1558
+ export interface KeymapChord {
1559
+ /** Letter/digit or named key (`"Enter"`). A single uppercase letter implies Shift. */
1560
+ key: string;
1561
+ ctrl?: boolean;
1562
+ shift?: boolean;
1563
+ alt?: boolean;
1564
+ super?: boolean;
1565
+ /**
1566
+ * The OS's "primary" chord modifier — Cmd on macOS, Ctrl elsewhere
1567
+ * (`zi.platform.primaryMod`). Prefer this over `ctrl`/`super`
1568
+ * individually for app shortcuts that should work on every platform
1569
+ * without an OS check (#0039).
1570
+ */
1571
+ primary?: boolean;
1572
+ /** Defaults to `"before-widget"`. */
1573
+ when?: "before-widget" | "after-widget";
1574
+ }
1575
+
1576
+ export interface KeymapAPI {
1577
+ /**
1578
+ * Bind an application chord and return an idempotent unbind function.
1579
+ * The binding is also removed with its owner scope.
1580
+ *
1581
+ * **Input/Textarea Ctrl+Enter requires the default `"before-widget"`**
1582
+ * because those widgets consume Enter. Tab and Escape are reserved and
1583
+ * cannot be bound.
1584
+ */
1585
+ bind(chord: KeymapChord, fn: () => void): () => void;
1586
+ }
1587
+
1588
+ /** Options for `zi.window.create`. */
1589
+ export interface WindowOpts {
1590
+ /** OS title-bar text. Defaults to the window `label`. */
1591
+ title?: string;
1592
+ /** Logical width in px (clamped to >0; default 800). */
1593
+ width?: number;
1594
+ /** Logical height in px (clamped to >0; default 600). */
1595
+ height?: number;
1596
+ }
1597
+
1598
+ /** Event passed to an `onCloseRequested` handler; call `preventDefault` to keep the window open. */
1599
+ export interface WindowCloseRequestEvent {
1600
+ preventDefault(): void;
1601
+ }
1602
+
1603
+ /** Handle to a window opened via `zi.window.create` / returned by `get`/`getAll`. */
1604
+ export interface WindowHandle {
1605
+ /** The identifier this window was created with. */
1606
+ readonly label: string;
1607
+ /** Dispose the component's reactive scope, then tear down the backend window. */
1608
+ close(): void;
1609
+ /**
1610
+ * Intercept the OS close request (title-bar X). Call `e.preventDefault()` to
1611
+ * stay open; otherwise the window closes. Only one handler (last set wins).
1612
+ */
1613
+ onCloseRequested(fn: (e: WindowCloseRequestEvent) => void): void;
1614
+ }
1615
+
1616
+ /**
1617
+ * Multi-window API (Tauri-style). All windows share the one QuickJS runtime, so
1618
+ * signals/stores are shared across windows. Each window renders its component in
1619
+ * its own reactive owner scope, disposed on close. On backends without
1620
+ * multi-window support (mobile), `create` returns `null`.
1621
+ */
1622
+ export interface WindowAPI {
1623
+ /**
1624
+ * Open a new window rendering `render()`. `label` is an identifier: creating
1625
+ * with an existing label returns that window's handle (idempotent). Returns
1626
+ * `null` if the backend can't create windows.
1627
+ */
1628
+ create(label: string, opts: WindowOpts | undefined, render: () => ZiJsxNode): WindowHandle | null;
1629
+ /** Look up an open window by label; `null` if none. */
1630
+ get(label: string): WindowHandle | null;
1631
+ /** Handles for every open `zi.window`. */
1632
+ getAll(): WindowHandle[];
1633
+ }
1634
+
1635
+ export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT";
1636
+
1637
+ export interface HttpRequestOptions {
1638
+ method?: HttpMethod;
1639
+ /** Request headers as a plain object. */
1640
+ headers?: Record<string, string>;
1641
+ /** Request body. Strings and ArrayBuffer/TypedArray pass through; other objects are JSON.stringify'd. */
1642
+ body?: string | object | ArrayBuffer | ArrayBufferView;
1643
+ /** Per-request timeout in ms; 0 disables. Defaults to `defaultTimeoutMs`. */
1644
+ timeout?: number;
1645
+ /**
1646
+ * From `zi.http.controller()`. Abort rejects with AbortError; the worker
1647
+ * may still occupy a pool thread until the in-flight read returns.
1648
+ */
1649
+ signal?: HttpAbortController;
1650
+ /** `"text"` (default) | `"bytes"` (ArrayBuffer) | `"preview"` (capped read) | `"file"` (requires `savePath`). */
1651
+ responseType?: "text" | "bytes" | "preview" | "file";
1652
+ /** Worker reads this path as the request body. Mutually exclusive with `body`. */
1653
+ bodyFile?: string;
1654
+ /** Destination path when `responseType` is `"file"`. Written via `{path}.part` then rename. */
1655
+ savePath?: string;
1656
+ /** Max bytes kept when `responseType` is `"preview"`. Default 64KiB. */
1657
+ previewLimit?: number;
1658
+ /** `"auto"` (default) attaches matching cookies; `"omit"` skips the Cookie header. Set-Cookie still applies. */
1659
+ cookies?: "auto" | "omit";
1660
+ /**
1661
+ * Hard cap for `text`/`bytes`/`file` bodies. Default 8MiB; `0` disables.
1662
+ * `text`/`bytes` keep a truncated prefix; `file` rejects `StreamTooLong` and does not rename.
1663
+ * Ignored when `responseType` is `"preview"` (uses `previewLimit`).
1664
+ */
1665
+ maxBodyBytes?: number;
1666
+ /** `"follow"` (default, today's redirect rules) or `"manual"` (never follow). */
1667
+ redirect?: "follow" | "manual";
1668
+ }
1669
+
1670
+ export interface HttpEncodedBody {
1671
+ body: string | Uint8Array;
1672
+ contentType: string;
1673
+ }
1674
+
1675
+ export interface HttpMultipartPart {
1676
+ name: string;
1677
+ value: string | ArrayBuffer | ArrayBufferView;
1678
+ filename?: string;
1679
+ type?: string;
1680
+ }
1681
+
1682
+ export interface HttpAbortController {
1683
+ readonly aborted: boolean;
1684
+ abort(): void;
1685
+ }
1686
+
1687
+ export interface HttpResponse {
1688
+ status: number;
1689
+ /** True when status is in the 2xx range. */
1690
+ ok: boolean;
1691
+ headers: Record<string, string>;
1692
+ /** True when a preview cap stopped the read before EOF. */
1693
+ truncated: boolean;
1694
+ /** Bytes retained (after a preview cap this is the prefix length). */
1695
+ bodyBytes: number;
1696
+ /** Set when `responseType` was `"file"`; `text`/`json`/`arrayBuffer` then reject. */
1697
+ savePath?: string;
1698
+ text(): Promise<string>;
1699
+ json(): Promise<any>;
1700
+ arrayBuffer(): Promise<ArrayBuffer>;
1701
+ }
1702
+
1703
+ export interface HttpCookie {
1704
+ name: string;
1705
+ value: string;
1706
+ domain: string;
1707
+ path: string;
1708
+ secure: boolean;
1709
+ /** Unix seconds; 0 = session. */
1710
+ expires: number;
1711
+ hostOnly: boolean;
1712
+ }
1713
+
1714
+ export interface HttpCookiesAPI {
1715
+ list(): HttpCookie[];
1716
+ /** Privileged write — does not simulate browser Domain guards. */
1717
+ set(c: Partial<HttpCookie> & Pick<HttpCookie, "name" | "domain">): void;
1718
+ delete(name: string, domain: string, path: string): void;
1719
+ clear(): void;
1720
+ }
1721
+
1722
+ /**
1723
+ * Fetch over the network from `.tsx`. Runs on a background worker thread;
1724
+ * every call returns a Promise resolved on the next frame. `fetch` is the
1725
+ * primitive; get/post/put/del are sugar over it.
1726
+ */
1727
+ export interface HttpAPI {
1728
+ /** Default per-request timeout in ms applied when `opts.timeout` is unset; 0 disables. */
1729
+ defaultTimeoutMs: number;
1730
+ fetch(url: string, opts?: HttpRequestOptions): Promise<HttpResponse>;
1731
+ get(url: string, opts?: HttpRequestOptions): Promise<HttpResponse>;
1732
+ post(url: string, body?: string | object, opts?: HttpRequestOptions): Promise<HttpResponse>;
1733
+ put(url: string, body?: string | object, opts?: HttpRequestOptions): Promise<HttpResponse>;
1734
+ del(url: string, opts?: HttpRequestOptions): Promise<HttpResponse>;
1735
+ /** Empty the automatic cookie jar (Set-Cookie is stored + re-sent by default). */
1736
+ clearCookies(): void;
1737
+ cookies: HttpCookiesAPI;
1738
+ controller(): HttpAbortController;
1739
+ encodeForm(fields: Record<string, string | number | boolean>): HttpEncodedBody;
1740
+ encodeMultipart(parts: HttpMultipartPart[]): HttpEncodedBody;
1741
+ }
1742
+
1743
+ /** A value SQLite can store. BLOBs come back as `ArrayBuffer`; INTEGERs
1744
+ * outside ±2^53 come back as `bigint` (a `number` would round them). */
1745
+ export type DbValue = null | number | bigint | string | ArrayBuffer;
1746
+
1747
+ export interface DbStatement {
1748
+ sql: string;
1749
+ params?: (DbValue | boolean | ArrayBufferView)[];
1750
+ }
1751
+
1752
+ export interface DbExecResult {
1753
+ changes: number;
1754
+ /** `bigint` past ±2^53, same rule as any INTEGER column. */
1755
+ lastInsertRowid: number | bigint;
1756
+ }
1757
+
1758
+ export interface DbTxResult<T = any> extends DbExecResult {
1759
+ rows: T[];
1760
+ }
1761
+
1762
+ /** One statement's raw reply: column-parallel arrays, not row objects. */
1763
+ export interface DbStmtResult extends DbExecResult {
1764
+ columns: string[];
1765
+ rows: DbValue[][];
1766
+ }
1767
+
1768
+ /** Raw reply from `zi.db.run`, including the table access the engine
1769
+ * observed. `zi/data` builds automatic invalidation on this. */
1770
+ export interface DbRunResult {
1771
+ results: DbStmtResult[];
1772
+ /** Tables the statements read (from sqlite's authorizer). */
1773
+ tablesRead: string[];
1774
+ /** Tables the statements wrote. Reports INTENT, so an UPDATE matching no
1775
+ * rows still appears — over-invalidating, never under-invalidating. */
1776
+ tablesWritten: string[];
1777
+ /** `tablesRead` is incomplete (allocation failure): treat the query as
1778
+ * depending on every table. */
1779
+ tablesReadPartial: boolean;
1780
+ /** `tablesWritten` is incomplete (allocation failure): the only safe
1781
+ * response is refetching every query, not the listed subset. */
1782
+ tablesWrittenPartial: boolean;
1783
+ }
1784
+
1785
+ /**
1786
+ * `zi.db` — embedded SQLite on a worker thread. Every call returns a Promise
1787
+ * settled on the main thread by the per-frame drain.
1788
+ *
1789
+ * Statements are parameterised only (`?` placeholders + a params array);
1790
+ * there is no string-concatenation entry point. One statement per call —
1791
+ * `"select 1; drop table t"` is rejected as `MultipleStatements`.
1792
+ *
1793
+ * Rejections are `Error`s carrying sqlite's own message, with `name` set to
1794
+ * the failure kind (`SqlError`, `ParameterCountMismatch`, `ResultTooLarge`,
1795
+ * `MultipleStatements`, `DatabaseClosed`, …) and, inside `tx`, `step` set to
1796
+ * the index of the statement that failed.
1797
+ */
1798
+ export interface DbAPI {
1799
+ /**
1800
+ * Open a database. Called automatically on first use with the default
1801
+ * `<app-data-dir>/data.db`; call it explicitly for a different file.
1802
+ * A bare name (no separator) is placed in the app data dir; a path with a
1803
+ * separator is used verbatim; `":memory:"` is in-memory.
1804
+ */
1805
+ open(path?: string): Promise<void>;
1806
+ /** Close the connection. The next query re-opens the default database. */
1807
+ close(): Promise<void>;
1808
+ /** SELECT → row objects keyed by column name. */
1809
+ query<T = any>(sql: string, params?: DbStatement["params"]): Promise<T[]>;
1810
+ /** INSERT/UPDATE/DELETE/DDL → affected-row info. */
1811
+ exec(sql: string, params?: DbStatement["params"]): Promise<DbExecResult>;
1812
+ /**
1813
+ * All-or-nothing batch (`BEGIN IMMEDIATE` … `COMMIT`), submitted as ONE
1814
+ * queue entry so nothing interleaves. Takes the statements up front rather
1815
+ * than a callback: an interactive transaction would hold the single worker
1816
+ * connection across awaits.
1817
+ */
1818
+ tx<T = any>(statements: (string | DbStatement)[]): Promise<DbTxResult<T>[]>;
1819
+ /** Low-level: raw results plus the tables read/written. Prefer
1820
+ * query/exec/tx; `zi/data` uses this one. */
1821
+ run(statements: (string | DbStatement)[], atomic?: boolean): Promise<DbRunResult>;
1822
+ /** Fires after any statement that wrote, with the table names. `partial`
1823
+ * means the engine couldn't name them all, so `tables` is a subset and the
1824
+ * only safe response is a full refresh. Returns an unsubscribe function. */
1825
+ onTablesChanged(cb: (tables: string[], partial: boolean) => void): () => void;
1826
+ /** Zip a raw `DbStmtResult` into row objects — what `query` does
1827
+ * internally, exposed for callers of `run`. */
1828
+ rowsToObjects<T = any>(result: DbStmtResult): T[];
1829
+ }
1830
+
1831
+ /**
1832
+ * Persistent string→string config store (localStorage semantics). Memory
1833
+ * mirror + atomic JSON file (0600). NON-SENSITIVE config only — never a token.
1834
+ * zi ships no keychain bridge on purpose (see the backend-integration design
1835
+ * §6 for what to do with credentials). Reads are synchronous; writes flush.
1836
+ */
1837
+ export interface StorageAPI {
1838
+ get(key: string): string | null;
1839
+ set(key: string, value: string): void;
1840
+ remove(key: string): void;
1841
+ clear(): void;
1842
+ /** Store any JSON-serializable value (JSON.stringify on write). */
1843
+ setJSON(key: string, value: any): void;
1844
+ /** Read + JSON.parse; null if absent or unparseable. */
1845
+ getJSON<T = any>(key: string): T | null;
1846
+ }
1847
+
1848
+ /** `zi.clipboard` — 系统剪贴板纯文本读写。 */
1849
+ export interface ClipboardAPI {
1850
+ /** 写系统剪贴板(纯文本,>1MiB 丢弃)。 */
1851
+ writeText(text: string): void;
1852
+ /** 读系统剪贴板文本;空/不可用返回 ""。 */
1853
+ readText(): string;
1854
+ }
1855
+
1856
+ /**
1857
+ * `zi.fs` — filesystem bridge for TRUSTED app code (no sandbox / path
1858
+ * allow-list). Paths are cwd-relative or absolute.
1859
+ */
1860
+ export interface FsAPI {
1861
+ /** Read a file as text; null if missing/unreadable. */
1862
+ readText(path: string): string | null;
1863
+ /** Write text, creating/truncating the file (parent dir must exist). Throws on error. */
1864
+ writeText(path: string, content: string): void;
1865
+ /** Read a file as bytes; null if missing/unreadable/oversize. */
1866
+ readBytes(path: string): ArrayBuffer | null;
1867
+ /** Write bytes (ArrayBuffer/TypedArray). Throws on error. */
1868
+ writeBytes(path: string, data: ArrayBuffer | ArrayBufferView): void;
1869
+ /** True iff the path exists and is accessible. */
1870
+ exists(path: string): boolean;
1871
+ /** Entry names directly under a directory; null if not a readable dir. */
1872
+ list(path: string): string[] | null;
1873
+ /** Create a directory recursively (mkdir -p). Throws on error. */
1874
+ mkdir(path: string): void;
1875
+ /** Delete a file (not directories). Throws on error. */
1876
+ remove(path: string): void;
1877
+ /** Atomic replace. Parent of `to` must exist. Throws on error. */
1878
+ rename(from: string, to: string): void;
1879
+ /** `{ kind, size, mtimeMs }`, or null if missing/unreadable. `mtimeMs` is milliseconds since the Unix epoch. */
1880
+ stat(path: string): { kind: string; size: number; mtimeMs: number } | null;
1881
+ /** Delete an empty directory. Throws if it still has entries. */
1882
+ removeDir(path: string): void;
1883
+ /** Write a JSON-serializable value; `undefined` is a no-op. Throws on error. */
1884
+ writeJSON(path: string, value: any): void;
1885
+ /** Read + JSON.parse; null if absent or unparseable. */
1886
+ readJSON<T = any>(path: string): T | null;
1887
+ }
1888
+
1889
+ export interface RealtimeEvent {
1890
+ /** Event name; `"message"` when the server didn't name it. */
1891
+ event: string;
1892
+ data: string;
1893
+ }
1894
+
1895
+ export interface RealtimeHandle {
1896
+ readonly id: number;
1897
+ close(): void;
1898
+ }
1899
+
1900
+ export interface RealtimeConnectOptions {
1901
+ /** Re-evaluated before EVERY (re)connect. A captured object would replay an
1902
+ * expired token hours later and loop on 401. */
1903
+ headers?: () => Record<string, string>;
1904
+ onEvent?: (e: RealtimeEvent) => void;
1905
+ /** `"connecting" | "open" | "reconnecting" | "closed"`. */
1906
+ onState?: (state: "connecting" | "open" | "reconnecting" | "closed") => void;
1907
+ /** Back-pressure evicted `n` events. The overflow ring is shared by every
1908
+ * stream, so a loss can't be attributed to one — every stream is told, and
1909
+ * the only correct response is a full refresh. */
1910
+ onDropped?: (n: number) => void;
1911
+ }
1912
+
1913
+ /**
1914
+ * `zi.realtime` — Server-Sent Events on their own worker threads (never the
1915
+ * HTTP pool: one stream would occupy a quarter of it forever). Reconnection,
1916
+ * exponential backoff with jitter and `Last-Event-ID` are handled inside; the
1917
+ * app watches `onState`.
1918
+ *
1919
+ * The engine records an owner for every connection (`asyncOwnerScopeId` layer
1920
+ * ①: `owningScopeId()` skips each effect's `effect_run` scope, so the owner is
1921
+ * the enclosing component body or `createRoot`, not the transient runtime
1922
+ * scope). Unmounting that component closes the stream.
1923
+ *
1924
+ * From an event handler, the owner is whoever registered the handler (#135);
1925
+ * continuations after `await` use layer ④ (#195).
1926
+ *
1927
+ * Inside `createEffect`, the engine owner is still that outer component — not
1928
+ * "no owner". `onCleanup` inside `connect` closes the stream when the effect
1929
+ * **re-runs** (deps changed) while the component is still mounted; it does not
1930
+ * replace engine teardown on unmount (both paths are idempotent).
1931
+ *
1932
+ * For a stream that must outlive the component, connect at the top level or in
1933
+ * a long-lived `zi.createRoot` and `close()` the handle yourself.
1934
+ *
1935
+ * Absent when built with `-Drealtime=false`.
1936
+ */
1937
+ export interface RealtimeAPI {
1938
+ connect(url: string, opts?: RealtimeConnectOptions): RealtimeHandle;
1939
+ }
1940
+
1941
+ /**
1942
+ * 子进程 —— `zi/service` 的 `processBoot` 就建在它上面。
1943
+ *
1944
+ * **桌面专属。** 移动端后端只能与 UI 同进程(见 `zi/service` 的 `ffiBoot`),
1945
+ * 所以这个命名空间在 iOS / Android 上是 undefined —— 用之前先判在不在。
1946
+ */
1947
+ export interface ComputeAbortController {
1948
+ readonly aborted: boolean;
1949
+ abort(): void;
1950
+ }
1951
+
1952
+ export type ComputePromise<T> = Promise<T> & {
1953
+ /** Monotonic worker job ID that can be passed to `zi.compute.cancel(jobId)`. */
1954
+ readonly jobId: number;
1955
+ };
1956
+
1957
+ export type ComputeColumnData =
1958
+ | number[]
1959
+ | Float64Array
1960
+ | Float32Array
1961
+ | Int32Array
1962
+ | Uint32Array
1963
+ | (string | null | undefined)[]
1964
+ | (boolean | null | undefined)[];
1965
+
1966
+ export type ComputeFilterOp =
1967
+ | "contains"
1968
+ | "startsWith"
1969
+ | "endsWith"
1970
+ | "eq"
1971
+ | "neq"
1972
+ | "gt"
1973
+ | "gte"
1974
+ | "lt"
1975
+ | "lte";
1976
+
1977
+ export interface ComputeFilterSpec {
1978
+ col: string | number;
1979
+ op: ComputeFilterOp;
1980
+ value: string | number | boolean | null;
1981
+ /** Default `false`. Applies to string comparisons. */
1982
+ caseSensitive?: boolean;
1983
+ }
1984
+
1985
+ export interface ComputeSortSpec {
1986
+ col: string | number;
1987
+ /** Default `"asc"`. */
1988
+ dir?: "asc" | "desc";
1989
+ /** Default `false`. Applies to string columns. */
1990
+ caseSensitive?: boolean;
1991
+ /** Default `true`. Places null / NaN values after non-null values regardless of `dir`. */
1992
+ nullsLast?: boolean;
1993
+ }
1994
+
1995
+ export interface ComputeFilterSortOpts {
1996
+ /** Columnar table data: named map or positional array of column arrays / TypedArrays. */
1997
+ columns: Record<string, ComputeColumnData> | ComputeColumnData[];
1998
+ /** Explicit row count (optional; inferred from the first column when omitted). */
1999
+ rowCount?: number;
2000
+ filters?: ComputeFilterSpec[];
2001
+ sort?: ComputeSortSpec[];
2002
+ offset?: number;
2003
+ limit?: number;
2004
+ signal?: ComputeAbortController;
2005
+ }
2006
+
2007
+ export interface ComputeSearchMatch {
2008
+ /** 0-based line index. */
2009
+ line: number;
2010
+ /** UTF-8 byte offset within the line. */
2011
+ col: number;
2012
+ /** UTF-8 byte length of the match. */
2013
+ len: number;
2014
+ }
2015
+
2016
+ export interface ComputeSearchTextOpts {
2017
+ /** Multiline document text (provide either `text` or `lines`). */
2018
+ text?: string;
2019
+ /** Pre-split line array (provide either `text` or `lines`). */
2020
+ lines?: string[];
2021
+ query: string;
2022
+ /** Default `false`. ASCII case folding is UTF-8 safe. */
2023
+ caseSensitive?: boolean;
2024
+ /** Default `false`. Matches only on UTF-8 word boundaries. */
2025
+ wholeWord?: boolean;
2026
+ /** Maximum match count to return. Default `10000`. */
2027
+ maxResults?: number;
2028
+ signal?: ComputeAbortController;
2029
+ }
2030
+
2031
+ export type ComputeAggregateOp = "count" | "sum" | "avg" | "min" | "max";
2032
+
2033
+ export interface ComputeAggregateStats {
2034
+ count: number;
2035
+ sum: number;
2036
+ avg: number | null;
2037
+ min: number | null;
2038
+ max: number | null;
2039
+ }
2040
+
2041
+ export interface ComputePartialAggregateStats {
2042
+ count?: number;
2043
+ sum?: number;
2044
+ avg?: number | null;
2045
+ min?: number | null;
2046
+ max?: number | null;
2047
+ }
2048
+
2049
+ export interface ComputeAggregateResult extends ComputeAggregateStats {
2050
+ groups?: Record<string, ComputeAggregateStats>;
2051
+ }
2052
+
2053
+ export interface ComputePartialAggregateResult extends ComputePartialAggregateStats {
2054
+ groups?: Record<string, ComputePartialAggregateStats>;
2055
+ }
2056
+
2057
+ export interface ComputeAggregateOpts {
2058
+ values: number[] | Float64Array | Float32Array | Int32Array | Uint32Array;
2059
+ /** Optional parallel group key array (same length as `values`). */
2060
+ groupKeys?: (string | null | undefined)[];
2061
+ /** Subset of summary stats to compute; defaults to all five when omitted. */
2062
+ ops?: ComputeAggregateOp[];
2063
+ /** Default `true`. Skips `NaN` entries from count/sum/avg/min/max. */
2064
+ skipNaN?: boolean;
2065
+ signal?: ComputeAbortController;
2066
+ }
2067
+
2068
+ /**
2069
+ * Native off-main-thread compute worker (`zi.compute`).
2070
+ *
2071
+ * Lazily spawns a single background thread on first use (0 threads and 0
2072
+ * allocations if never called). Jobs owned by a reactive scope are
2073
+ * automatically cancelled on scope disposal (`ScopeDisposed`).
2074
+ */
2075
+ export interface ComputeAPI {
2076
+ filterSort(opts: ComputeFilterSortOpts): ComputePromise<number[]>;
2077
+ searchText(opts: ComputeSearchTextOpts): ComputePromise<ComputeSearchMatch[]>;
2078
+ aggregate(opts: ComputeAggregateOpts & { ops: ComputeAggregateOp[] }): ComputePromise<ComputePartialAggregateResult>;
2079
+ aggregate(opts: ComputeAggregateOpts): ComputePromise<ComputeAggregateResult>;
2080
+ /** Cancel an in-flight or queued job by `jobId`; returns `true` if cancelled. */
2081
+ cancel(jobId: number): boolean;
2082
+ /** Create an abort controller usable as `opts.signal` across multiple jobs. */
2083
+ controller(): ComputeAbortController;
2084
+ }
2085
+
2086
+ export interface ProcessAPI {
2087
+ /**
2088
+ * 起一个子进程。`argv[0]` 含 `/` 时按路径解析,否则查 PATH。
2089
+ *
2090
+ * 引擎会记属主(`asyncOwnerScopeId` 第 ① 层:`owningScopeId()` 跳过 effect
2091
+ * 运行期 scope),所以组件卸载会收掉子进程。组件体、事件 handler(#135)、
2092
+ * `await` 延续(#195)各走对应层;**effect 体里 spawn** 的引擎属主仍是外层
2093
+ * 组件,不是「无主」。`onCleanup` 管 effect **重跑**之间的代际清理(与
2094
+ * `zi.realtime.connect` 相同分工)。
2095
+ *
2096
+ * 要活得比组件久的 sidecar,就在顶层或长命的 `zi.createRoot` 里 spawn,
2097
+ * 并自己留住句柄调 `kill()`。
2098
+ */
2099
+ spawn(argv: string[] | string, opts?: ProcessSpawnOptions): ChildProcess;
2100
+ }
2101
+
2102
+ export interface ProcessSpawnOptions {
2103
+ cwd?: string;
2104
+ /** 子进程的 stderr:直通宿主(默认)或丢弃。**不捕获**。 */
2105
+ stderr?: "inherit" | "ignore";
2106
+ /**
2107
+ * 子进程的 stdin。缺省 `"lifeline"`:父进程持着一根管道的写端,不写也不关 ——
2108
+ * 父进程一死(**含 SIGKILL 与硬崩溃**)内核关掉它所有 fd,子进程的 stdin 随之
2109
+ * 读到 EOF。**子进程据此自退,是它退出的唯一可靠触发**:zi 的信号处理器覆盖
2110
+ * TERM/INT/HUP,但 SIGKILL 与崩溃时连处理器都不跑,那时只剩这条线。
2111
+ *
2112
+ * 所以写后端时留一句:
2113
+ * ```go
2114
+ * go func() { io.Copy(io.Discard, os.Stdin); os.Exit(0) }()
2115
+ * ```
2116
+ *
2117
+ * **代价:子进程不能拿 stdin 读别的东西。** 需要「读 stdin 且立刻拿到 EOF」的
2118
+ * 程序(`grep pattern` 这类)传 `"ignore"` 换回 `/dev/null` —— 否则它会一直
2119
+ * 阻塞,而那是一次静默挂起,不是错误。
2120
+ */
2121
+ stdin?: "lifeline" | "ignore";
2122
+ }
2123
+
2124
+ export interface ChildProcess {
2125
+ id: number;
2126
+ /**
2127
+ * 下一行 stdout(不含换行);EOF 之后是 `null`。
2128
+ *
2129
+ * 背压丢过行时会 reject —— 少几行日志无所谓,但少的若是握手行,
2130
+ * 一直挂着的 `readLine()` 看起来和「后端没启动」一模一样。
2131
+ */
2132
+ readLine(): Promise<string | null>;
2133
+ /**
2134
+ * 请求终止。`force` 用 SIGKILL,否则 SIGTERM。**信号发给整个进程组**,
2135
+ * 所以后端自己 fork 的 helper 也会被收掉。
2136
+ *
2137
+ * 只是请求 —— 最终状态仍从 `wait()` 出来。返回 false 表示进程已经回收过了。
2138
+ */
2139
+ kill(force?: boolean): boolean;
2140
+ /** 进程的最终状态。已经退了就立即 resolve。 */
2141
+ wait(): Promise<ProcessExit>;
2142
+ /** 已退出则是最终状态,否则 null。 */
2143
+ exited(): ProcessExit | null;
2144
+ }
2145
+
2146
+ export interface ProcessExit {
2147
+ /** 正常退出的返回码;被信号打断时是 -1。 */
2148
+ code: number;
2149
+ /** 打断它的信号,没有则 0。 */
2150
+ signal: number;
2151
+ }
2152
+
2153
+ export interface ZiGlobal {
2154
+ h: <P = any>(tag: (props: P, children?: any) => any, props?: P, ...children: any[]) => ZiWidget;
2155
+ /** Core layout primitives — presets over the `Flex` engine widget.
2156
+ * Importable from "zi": `import { Column, Row, Box } from "zi"`. */
2157
+ Flex: (props?: BoxProps, children?: any) => ZiJsxNode;
2158
+ Column: (props?: ColumnProps, children?: any) => ZiJsxNode;
2159
+ Row: (props?: RowProps, children?: any) => ZiJsxNode;
2160
+ Box: (props?: BoxProps, children?: any) => ZiJsxNode;
2161
+ Text: (props?: TextProps, children?: any) => ZiJsxNode;
2162
+ Stack: (props?: StackProps, children?: any) => ZiJsxNode;
2163
+ Scrollable: (props?: ScrollableProps, children?: any) => ZiJsxNode;
2164
+ ListView: (props: ListViewProps) => ZiJsxNode;
2165
+ Control: (props?: ControlProps, children?: any) => ZiJsxNode;
2166
+ Image: (props?: ImageProps, children?: any) => ZiJsxNode;
2167
+ Checkmark: (props?: CheckmarkProps, children?: any) => ZiJsxNode;
2168
+ Divider: (props?: DividerProps, children?: any) => ZiJsxNode;
2169
+ // 图表原语 —— 不带主题、数据走 __zi_chart_*。主题化的组件版在 "zi/ui"。
2170
+ // 尺寸走 style 的 width/height(它们是一等 widget,没有图表专属的 setViewport)。
2171
+ LineChart: (props?: ChartPrimitiveProps, children?: any) => ZiJsxNode;
2172
+ BarChart: (props?: ChartPrimitiveProps, children?: any) => ZiJsxNode;
2173
+ PieChart: (props?: ChartPrimitiveProps, children?: any) => ZiJsxNode;
2174
+ Ring: (props?: ChartPrimitiveProps, children?: any) => ZiJsxNode;
2175
+ Input: (props?: InputProps, children?: any) => ZiJsxNode;
2176
+ Textarea: (props?: TextareaProps, children?: any) => ZiJsxNode;
2177
+ Modal: (props?: ModalProps, children?: any) => ZiJsxNode;
2178
+ // `when`/`each` 必须是 thunk(函数),不能传值:引擎按 `when()`/`each()` 当函数
2179
+ // 调,且自动包 thunk 在运行时做不到(值在进 zi.h 前已求值)。类型按函数收紧,
2180
+ // 让 `when={cond()}` / `each={list()}` 在 tsc 即报错;运行时另有显式守卫兜底。
2181
+ Show: (props?: { when?: () => any; children?: any; fallback?: any; transition?: TransitionSpec; style?: ZiStyle }, children?: any) => ZiJsxNode;
2182
+ For: (props?: { each?: () => any[]; keyFn?: (item: any, i: number) => any; children?: any; transition?: TransitionSpec; style?: ZiStyle }, children?: any) => ZiJsxNode;
2183
+ /**
2184
+ * 多分支:第一个 `when` 为真的 `<Match>` 胜出,都不真时挂 `fallback`。
2185
+ *
2186
+ * children **只能是 `<Match>`**(运行时守卫会拦住别的);类型上 `<Match>` 报成
2187
+ * `ZiJsxNode` 是一层善意的谎(跟 SolidJS 一样),因为 JSX.Element 就是那个类型。
2188
+ *
2189
+ * **分支子树不缓存**:切走再切回会重建,分支内的滚动位置 / 未提交输入 / 动画态会丢
2190
+ * —— 要保住就把它提到 `<Switch>` 外面的 signal 里。
2191
+ */
2192
+ Switch: (props?: { fallback?: any; children?: any; style?: ZiStyle }, children?: any) => ZiJsxNode;
2193
+ /** `<Switch>` 的一个分支。`when` 同样必须是 thunk。 */
2194
+ Match: (props?: { when?: () => any; children?: any }, children?: any) => ZiJsxNode;
2195
+ /**
2196
+ * 按组件身份换子树:`component` 的 thunk 返回哪个组件函数就挂哪个,返回 `null` 挂空。
2197
+ *
2198
+ * thunk 要返回组件函数**本身**:组件存在 signal 里写 `component={() => comp()}`,
2199
+ * 静态组件写 `component={() => Comp}`。**别写 `component={Comp}`** —— 组件本身就是
2200
+ * 函数,入口分不出两者,它会被当 thunk 调掉(运行时有显式报错兜底)。
2201
+ *
2202
+ * props 是**捕获**的,不是反应式的:组件函数只跑一次,要反应式就传 signal getter,
2203
+ * 由组件内部的 effect 去读。v1 不接 children。
2204
+ */
2205
+ Dynamic: (props?: { component?: () => any; style?: ZiStyle; [prop: string]: any }, children?: any) => ZiJsxNode;
2206
+ Transition: (props?: TransitionProps, children?: any) => ZiJsxNode;
2207
+ /**
2208
+ * 错误边界。子树里的 effect(以及 children 渲染函数里的同步 throw)抛出时,
2209
+ * 把半建的内容摘掉、换上 `fallback`,而不是让界面停在半旧状态、错误只打到
2210
+ * stderr。`reset()` 重跑一次 children。
2211
+ *
2212
+ * 边界**只接自己子树**里的抛出 —— 沿 scope 父链找最近的一个。
2213
+ */
2214
+ ErrorBoundary: (
2215
+ props?: { fallback?: (err: any, reset: () => void) => any; children?: any; style?: ZiStyle },
2216
+ children?: any,
2217
+ ) => ZiJsxNode;
2218
+ signal: <T>(init: T) => Signal<T>;
2219
+ createEffect: (fn: () => void) => void;
2220
+ /** Derived value: recomputes when its tracked deps change; change-gated. */
2221
+ createMemo: <T>(fn: () => T) => Memo<T>;
2222
+ /** Run `fn` with reactive tracking disabled; returns `fn`'s value. */
2223
+ untrack: <T>(fn: () => T) => T;
2224
+ /** Coalesce many `set()`s inside `fn` into one effect flush; returns `fn`'s value. */
2225
+ batch: <T>(fn: () => T) => T;
2226
+ /** Register a teardown on the running effect (LIFO before re-exec / on dispose). */
2227
+ onCleanup: (fn: () => void) => void;
2228
+ /**
2229
+ * 底层错误边界原语(`<ErrorBoundary>` 就建在它上面)。在一个新 scope 里跑 `fn`,
2230
+ * 该 scope **子树里**的 effect 抛出时交给 `handler`;`fn` 自己同步抛也走 `handler`。
2231
+ * 返回 `{ value, scope, dispose }`。
2232
+ */
2233
+ catchError: <T>(fn: () => T, handler: (err: any) => void) => { value: T | undefined; scope: number; dispose: () => void };
2234
+ /** Run `fn` after the first layout (post-mount), when widget geometry exists. */
2235
+ onMount: (fn: () => void) => void;
2236
+ /** Effect-callback helper: `dep()` tracked, `fn(value)` untracked; `{ defer }` skips the initial run. */
2237
+ on: <T>(dep: () => T, fn: (value: T) => void, opts?: { defer?: boolean }) => (() => void);
2238
+ /**
2239
+ * Official global-state pattern: per-field signals + batched actions.
2240
+ * Replaces ad-hoc `globalThis`.
2241
+ *
2242
+ * SHALLOW reactive — each field is one signal. Update fields immutably
2243
+ * (replace the value); in-place mutation of a nested object/array
2244
+ * (`s.items.push(x)`) bypasses the setter and won't notify. A name shared
2245
+ * by a state field and an action throws at creation.
2246
+ */
2247
+ createStore: <S extends Record<string, any>, A extends Record<string, StoreAction<S>>>(
2248
+ def: StoreDef<S, A>,
2249
+ ) => StoreFields<S> & StoreActions<A>;
2250
+ /** Reactive window size in logical px. Reading it in an effect subscribes; re-runs on resize. */
2251
+ viewport: () => { w: number; h: number };
2252
+ /** 反应式修饰键状态。引擎在**事件阶段**推,变了才通知 —— 读它做 Alt 呼出
2253
+ * 菜单栏之类的手势(`<MenuBar autoHide>` 就是这么实现的)。 */
2254
+ modifiers: () => { shift: boolean; ctrl: boolean; alt: boolean; super: boolean };
2255
+
2256
+ // ── Animation / transition (design: docs/superpowers/specs/2026-06-14-declarative-transition-component-design.md) ──
2257
+ /** 按名字求缓动值(`t` 夹在 0..1)。打断动画、要估「现在走到哪」时用 ——
2258
+ * 引擎不暴露 player 的当前值。与引擎内部用的是同一份曲线实现。 */
2259
+ easing: (name: EasingName, t: number) => number;
2260
+ /** Time-driven scalar tween, shaped as a signal getter. Read it in an effect to bind. */
2261
+ tween: (opts: TweenOpts) => TweenSignal;
2262
+ /** Velocity-carrying scalar spring (#0037), same signal-getter shape as
2263
+ * `tween`. Unlike `tween`, this one has no `id`-based retarget helper of
2264
+ * its own to call again — it's the standalone-signal sibling of the
2265
+ * `(target, channel)`-keyed retarget that `<Show>`'s `spring` transitions
2266
+ * and `zi.animate`'s `spring` option use internally. */
2267
+ spring: (opts: SpringOpts) => SpringSignal;
2268
+ /**
2269
+ * Cancel & dispose EVERY registered animation — both `tween()` signals AND
2270
+ * `animate()`/`transition()` keyframe players (cancelled handles reject
2271
+ * `finished` / settle `false`). Use on page switch / subtree teardown.
2272
+ */
2273
+ cancelAllAnimations: () => void;
2274
+ /** @deprecated Alias of `cancelAllAnimations` — despite the name it also
2275
+ * cancels keyframe players, not just tweens. Prefer `cancelAllAnimations`. */
2276
+ cancelAllTweens: () => void;
2277
+ /** Play a keyframe animation on an element (continuous/controlled). Returns a control handle. */
2278
+ animate: (id: any, spec: AnimSpec, opts?: AnimateOpts) => AnimHandle;
2279
+ /** One-shot enter: play `spec`, hold the final frame on completion. Returns
2280
+ * the (fire-and-forget) handle — `finished` is absent on it. */
2281
+ transition: (id: any, spec: AnimSpec | PresetName) => AnimHandle;
2282
+ /**
2283
+ * One-shot exit. Resolves `true` if it played to completion (caller should
2284
+ * unmount), `false` if cancelled mid-way (caller should keep). Never rejects,
2285
+ * never hangs.
2286
+ */
2287
+ transitionOut: (id: any, spec: AnimSpec | PresetName) => Promise<boolean>;
2288
+ /** Built-in transition presets (fast-channel only). */
2289
+ transitions: Record<PresetName, AnimSpec>;
2290
+ mount: (root: any) => void;
2291
+ /**
2292
+ * 给一个 `<Text>` 落字。**收字符串或 thunk** —— 传 thunk 会建一个 effect,
2293
+ * 它读到的 signal 变了就重写(文案走词表之后这是常态)。
2294
+ *
2295
+ * 静态值不建 effect(空 effect 也要进依赖图、也要在 scope 里回收)。
2296
+ */
2297
+ setText: (handle: any, text: string | (() => any)) => void;
2298
+ /** 更新绝对定位子节点的 `top` 偏移(进入 `batchOps` 指令缓冲)。 */
2299
+ setTop: (id: any, v: number) => void;
2300
+ /** 更新绝对定位子节点的 `left` 偏移(进入 `batchOps` 指令缓冲)。 */
2301
+ setLeft: (id: any, v: number) => void;
2302
+ /** 更新绝对定位子节点的 `right` 偏移(进入 `batchOps` 指令缓冲)。 */
2303
+ setRight: (id: any, v: number) => void;
2304
+ /**
2305
+ * 批量提交属性更新指令缓冲(#327):将回调内的 `setText`/`setTop`/`setLeft`/
2306
+ * `patchStyle`/`setStyle` 合并为一个紧凑平面缓冲,在最外层退出时单次过界提交。
2307
+ */
2308
+ batchOps: <T>(fn: () => T) => T;
2309
+ /** 底层指令缓冲直接提交(stride-3 平面数组 `[op, slotId, payload, ...]`),返回执行条数。 */
2310
+ commitOps: (ops: any[]) => number;
2311
+ /** @internal `setText` 用它决定「建绑定」还是「就地取值」。 */
2312
+ __zi_in_effect?: () => boolean;
2313
+ /**
2314
+ * 值或 thunk → 字符串。给「要先变换再显示」的调用点用
2315
+ * (`zi.textOf(x).toUpperCase()`),以及**已经在 effect 里**时的就地取值。
2316
+ *
2317
+ * 不叫 `valueOf` —— 那会盖掉 `zi` 自己的 `Object.prototype.valueOf`。
2318
+ */
2319
+ textOf: (x: any) => string;
2320
+ /** 同 `textOf` 再大写。静态值直接给字符串,thunk 才返回 thunk。 */
2321
+ upperOf: (x: any) => string | (() => string);
2322
+ /**
2323
+ * Replace a container's children. Any old child that is NOT in `children`
2324
+ * and NOT in `retain` is permanently detached: its control-flow instances
2325
+ * are disposed and its widget slots reclaimed.
2326
+ *
2327
+ * `retain` is for children you keep OUT of the tree but intend to mount
2328
+ * again later (a hidden tab panel, `Show`'s cached fallback). Re-mounting a
2329
+ * child that was disposed is a use-after-free — the engine walks a freed
2330
+ * widget during the next layout.
2331
+ */
2332
+ setChildren: (
2333
+ container: ZiWidget,
2334
+ // `{cond && <X/>}` 的 `false` / `null` 是条件渲染的正常产物 —— 运行期静默跳过,
2335
+ // 类型上也别拦(拦了调用方只会去写 `as any`)。
2336
+ children: (ZiWidget | false | null | undefined)[],
2337
+ retain?: ZiWidget[],
2338
+ ) => void;
2339
+ /** 这个值是不是一个**活**的 widget 句柄(见 `ZiWidget`)?别的一律是「值」。 */
2340
+ isWidget: (v: any) => boolean;
2341
+ /**
2342
+ * Free a detached subtree you're done with (route swap, closed view):
2343
+ * disposes its control-flow instances + scoped effects AND releases its
2344
+ * engine display-list cache. `setChildren` only detaches — without this the
2345
+ * removed subtree's display-lists leak until exit. Call after detaching.
2346
+ */
2347
+ disposeSubtree: (id: any) => void;
2348
+ /**
2349
+ * Snapshot every retained-graph counter for empirical leak hunting — live
2350
+ * widget `slots` (+ per-type `byKind`), `effects`/`signals`/`scopes`,
2351
+ * `stateIndex`/`baseIndex`/`pendingFree`, `cf` (Show/For/Transition
2352
+ * instances), `dlLive`, `jsHeapKB`, `rssKB`. Snapshot, repeat an action N
2353
+ * times, snapshot again: a counter climbing without bound (after the UI
2354
+ * settles) is a real leak. Pass `true` to also console.log it.
2355
+ */
2356
+ debugStats: (log?: boolean) => Record<string, any>;
2357
+ /** Deltas of the scalar counters vs a prior `debugStats()` snapshot. */
2358
+ debugDiff: (prev: Record<string, any>) => Record<string, any>;
2359
+ /** Programmatically set an `<Input>` widget's value (does NOT fire onChange). */
2360
+ setInputValue: (id: any, value: string) => void;
2361
+ /** Read an `<Input>` widget's current text. */
2362
+ getInputValue: (id: any) => string;
2363
+ /** Programmatically set a `<Textarea>` widget's value (does NOT fire onChange). */
2364
+ setTextareaValue: (id: any, value: string) => void;
2365
+ /** Read a `<Textarea>` widget's current text. */
2366
+ getTextareaValue: (id: any) => string;
2367
+ ffi: FfiAPI;
2368
+ platform: PlatformAPI;
2369
+ /**
2370
+ * 当前 UI 缩放(= `contentScale`,HiDPI 上通常 1.5 / 2)。
2371
+ *
2372
+ * style 里的 px 是**逻辑** px,引擎按这个系数放大;而 `zi.platform` 的窗口
2373
+ * 几何 API(`setWindowPos/Size`、`setFrameExtents`)是 **device** px。跨这两个
2374
+ * 空间时必须自己换算 —— 见 `zi/window` 的 `setFrameGutter`。
2375
+ */
2376
+ getUiScale: () => number;
2377
+ /**
2378
+ * 声明窗口**面**与**可见客户区**之间的四边内缩(逻辑 px)。
2379
+ *
2380
+ * overlay 层(对话框遮罩 / toast)铺满整个窗口面,而自绘窗口的客户区比那一面小:
2381
+ * 四周一圈给投影留白的**透明**外环,顶上一条标题栏。不声明的话遮罩会涂到窗口
2382
+ * 外面的桌面上,`topRight` 的 toast 会落在窗口按钮上。
2383
+ *
2384
+ * 自动 chrome(`window.decorations: false`)自己调它,应用不用管;**手绘 chrome
2385
+ * 的应用要自己调**。不调 = 全 0 = 与从前逐字相同的行为。
2386
+ */
2387
+ setOverlayInset: (inset: { top?: number; right?: number; bottom?: number; left?: number }) => void;
2388
+ /**
2389
+ * 注册自绘窗口 chrome 的工厂 —— 由 `zi/window` 的 `chrome.tsx` 在构建期经
2390
+ * esbuild `--inject` 装上。清单声明了 `window.chrome` 时,`zi.mount` 用
2391
+ * `factory(root, cfg)` 的结果代替 root。
2392
+ *
2393
+ * **应用不该直接调它**:自动 chrome 是清单里的声明,不是 app 的 import 顺序。
2394
+ * 想整包替换 chrome 的第三方才用得上。
2395
+ */
2396
+ __registerWindowChrome: (
2397
+ factory: (root: any, cfg: { enabled: boolean; title: string; buttons: string[] }) => any,
2398
+ ) => void;
2399
+ /** Multi-window: open/lookup OS windows sharing this runtime's signals. */
2400
+ window: WindowAPI;
2401
+ /**
2402
+ * Subscribe to soft-keyboard (IME) visibility changes. `cb(shown, heightPx)`
2403
+ * fires after the widget tree has reflowed for the new keyboard rect.
2404
+ * Subscribers stack; registrations live for the lifetime of the Root (no `off`).
2405
+ * No-op on desktop where there's no soft keyboard.
2406
+ */
2407
+ onImeChange: (cb: (shown: boolean, heightPx: number) => void) => void;
2408
+ http: HttpAPI;
2409
+ /** Plain TCP. One thread per connection; `read` above 1MiB throws before any allocation. */
2410
+ net: {
2411
+ tcp: {
2412
+ connect(host: string, port: number, opts?: { timeout?: number }): Promise<{
2413
+ write(bytes: ArrayBuffer | ArrayBufferView): Promise<void>;
2414
+ /** EOF resolves `null`. */
2415
+ read(maxBytes: number): Promise<ArrayBuffer | null>;
2416
+ close(): boolean;
2417
+ }>;
2418
+ };
2419
+ };
2420
+ db: DbAPI;
2421
+ /** Native off-main-thread compute worker (lazy-spawned on first call). */
2422
+ compute: ComputeAPI;
2423
+ /** Absent under `-Drealtime=false`. */
2424
+ realtime?: RealtimeAPI;
2425
+ /**
2426
+ * 子进程。**桌面专属** —— 移动端根本没有这个属性:iOS 沙箱禁止 fork/exec,
2427
+ * Android 10+ 不允许执行私有目录里的二进制。也可用 `-Dprocess=false` 关掉。
2428
+ */
2429
+ process?: ProcessAPI;
2430
+ /**
2431
+ * 清单(`zi.yaml` 的 `sidecars:`)里声明的那个子进程二进制在**这次运行**中的
2432
+ * 绝对路径。
2433
+ *
2434
+ * **只回答「它在哪」** —— 起它、握手、重启、收摊仍归 `zi/service` 的
2435
+ * `processBoot`。两种形态由 host 抹平:`zi run` 按**项目根**解析(不是 cwd ——
2436
+ * `zi run` 不 chdir),打包产物按 **exe 同目录**解析,所以 app 不必知道自己跑在
2437
+ * 哪一种里。
2438
+ *
2439
+ * **名字不在清单里、或那个文件不存在,都返回 null** —— host 播种时 stat 过,
2440
+ * 交一条死路径出来只会让下面那句回退永远走不到。
2441
+ *
2442
+ * **所以 null 是正常状态**,不是错误:装机形态下 sidecar 来自系统 PATH。调用方
2443
+ * 该有回退(`zi.sidecar(n) ?? n`,把名字交给 spawn 去查 PATH),而不是 try/catch。
2444
+ */
2445
+ sidecar(name: string): string | null;
2446
+ /**
2447
+ * 随 app 打包的资源文件在**这次运行**中的绝对路径。`rel` 相对
2448
+ * `zi.yaml` 里那个 `asset_dir`(缺省 `assets`)。
2449
+ *
2450
+ * ```ts
2451
+ * const p = zi.asset("icons/tray.png"); // → /…/Contents/Resources/assets/icons/tray.png
2452
+ * ```
2453
+ *
2454
+ * **为什么不能自己拼。** 三种形态下 assets 压根不在同一处:`zi run` 时在
2455
+ * 项目树里、`dir` 产物里在 exe 旁边、而 macOS 的 `.app` 把它放进
2456
+ * `Contents/Resources/`(与 exe 隔着一层)。更要命的是**双击启动时 cwd 是
2457
+ * 任意的**(macOS 下常是 `/`)—— 任何 `"./assets/x.png"` 都必然落空,而症状
2458
+ * 是「开发时好好的,打包后图全没了」。
2459
+ *
2460
+ * **null 的两种情况**:这次运行没有 assets 目录;或 `rel` 不安全(绝对路径、
2461
+ * 含 `..` 段)——后者在三种形态下会指向三个不同的地方,给 null 比给一条随形态
2462
+ * 漂移的路径诚实。
2463
+ */
2464
+ asset(rel: string): string | null;
2465
+ /**
2466
+ * 这个 app 的数据目录(`zi.storage` / `zi.db` 落盘的那一个),绝对路径。
2467
+ * 目录**不保证已存在** —— 要写就先 `zi.fs.mkdir()`。
2468
+ *
2469
+ * 名字取自 `zi.yaml` 的 `app.name`(`ZI_APP` 环境变量可覆盖,便于并排跑多份
2470
+ * 开发版)。**在这之前所有 zi app 共用一个 `zi-app` 目录** —— 同一台机器上
2471
+ * 两个 zi app 会撞 `zi.storage` 的 key、共用同一个 `zi.db` 文件。
2472
+ *
2473
+ * 主要用途是**与 sidecar 约定一个落点**:后端(另一个进程、另一套语言)往
2474
+ * 那儿写 endpoint / 状态文件,UI 从那儿读。让两边各自按平台拼一遍那条路径,
2475
+ * 就是第二份会漂移的规则。
2476
+ */
2477
+ appDir(): string | null;
2478
+
2479
+ /**
2480
+ * 系统界面语言的 BCP-47 tag(`"zh-Hans-CN"` / `"en-US"`);取不到给 `null`。
2481
+ *
2482
+ * **只是提示,不自动生效。** 引擎不会拿它去 `setLocale` —— 跟随系统是 app 的
2483
+ * 决定:`import { setLocale } from "zi/i18n"; setLocale(zi.systemLocale() ?? "zh-CN")`。
2484
+ * 默认跟随会让现有 app 升级引擎后界面**静默变成英文**(自带组件的文案在这之前
2485
+ * 一律是中文),那是破坏性变更且不报错。
2486
+ *
2487
+ * 来源按可靠性排:Apple 上是 `NSLocale.preferredLanguages`(**GUI 启动的 macOS
2488
+ * app 通常没有 `LANG`**,只认环境变量的话双击 .app 就拿不到),其余平台是
2489
+ * `LC_ALL` / `LC_CTYPE` / `LANG`。
2490
+ */
2491
+ systemLocale(): string | null;
2492
+ editor: EditorAPI;
2493
+ storage: StorageAPI;
2494
+ clipboard: ClipboardAPI;
2495
+ fs: FsAPI;
2496
+ // NOTE: no `zi.ui` — the theme runtime moved to the `zi/ui` authoring layer.
2497
+ // `import { setTheme, useStyles, icons } from "zi/ui"` (types from the .ts
2498
+ // modules); `import defaultTheme from "zi/ui/themes/default"`.
2499
+ /** 请求退出:帧循环在本帧末尾停下,引擎按正常路径拆干净再退。
2500
+ * **不是 `never`** —— 调用后同一段 JS 仍会跑完(要立刻停下就自己 `return`)。 */
2501
+ exit: (code?: number) => void;
2502
+ createRoot<T>(fn: () => T, owner?: number): { value: T; scope?: number; dispose: () => void };
2503
+ toChildren(children: any): any[];
2504
+ __styleLayerKeys: string[];
2505
+
2506
+ // ── Component-authoring surface ──────────────────────────────────────
2507
+ // Components are now plain exported functions, imported from `zi/ui`
2508
+ // (or `zi/headless`) and called directly by `zi.h`; the engine no longer
2509
+ // hosts a component registry. This `components` map is retained only for
2510
+ // legacy callers; its optional headless state factory lives in
2511
+ // `zi.headless.<Name>`.
2512
+ components: Record<string, (props: any, children?: any[]) => any>;
2513
+ // Mixed registry: `create()` factories (Tabs/Splitter/…) AND shared util
2514
+ // helpers (hostChild, resolveStyle) — hence `any` values.
2515
+ headless: Record<string, any>;
2516
+ // Widget's absolute screen rect (post-layout) — drag math reference.
2517
+ absRect: (id: any) => { x: number; y: number; w: number; h: number } | null;
2518
+ // One-shot "call me once the next layout pass has run" (#0032). `id` is the
2519
+ // OWNER: destroyed before the callback lands → no callback. Inside the
2520
+ // callback `zi.absRect` returns THIS frame's geometry, which an effect (which
2521
+ // runs BEFORE layout) cannot see. Re-arm from inside to keep observing; the
2522
+ // re-arm lands on the next frame, never re-entrantly on this one.
2523
+ afterLayout: (id: any, fn: () => void) => void;
2524
+ // ── Style plumbing (engine core, theme-independent) ──
2525
+ // Precompile a static style object or CSS string into a Zig-side integer handle
2526
+ // (`StyleId`, #329) to avoid repeated QuickJS property walks on hot paths.
2527
+ compileStyle: (style: Style | string | number) => number;
2528
+ // Compose multiple precompiled `StyleId`s directly in Zig into a new `StyleId`.
2529
+ composeStyles: (...ids: number[]) => number;
2530
+ // Deep-merge StyleProps; later args overlay earlier, recursing into state
2531
+ // overlay keys (hover/pressed/…). `undefined` skipped at every level.
2532
+ mergeStyles: (...styles: any[]) => any;
2533
+ // Per-widget style accumulator (deep-merges across effects); preferred over
2534
+ // the raw native setter for component styling.
2535
+ patchStyle: (id: any, partial: any) => void;
2536
+ // Full replace + cache reset (variant swap / re-init).
2537
+ setStyle: (id: any, style: any) => void;
2538
+ // Drop a freed widget's cache entry. Safe no-op for unpatched ids.
2539
+ clearStyleCache: (id: any) => void;
2540
+ // Engine-neutral tag theme hook: the `zi/ui` theme runtime registers its
2541
+ // `resolveStyle` here on import so imported `<Input>`/`<Textarea>` functions
2542
+ // auto-theme. Internal — apps use the `zi/ui` presets or `setTheme`.
2543
+ __registerTagStyler: (fn: (prim: string, part: string, ctx: any, callStyle: any) => any) => void;
2544
+
2545
+ // ── Imperative control-flow (positional; engine-internal callers use these) ──
2546
+ __forCF: (container: any, each: () => any, mapFn: (item: any, index: any) => any, keyFn?: (item: any, index: any) => any, transition?: TransitionSpec) => any;
2547
+ __showCF: (container: any, when: () => any, child: any, transition?: TransitionSpec, fallback?: any) => any;
2548
+ __switchCF: (container: any, branches: Array<{ when: () => any; thenFn: () => any }>, fallback?: any) => any;
2549
+ __dynamicCF: (container: any, component: () => any, props?: any) => any;
2550
+ __transitionCF: (container: any, childThunk: () => any, spec: TransitionProps) => any;
2551
+
2552
+ // ── Timers (QuickJS host timers; not the DOM lib) ──
2553
+ setTimeout: (fn: () => void, ms: number) => any;
2554
+ clearTimeout: (id: any) => void;
2555
+
2556
+ // ── Overlay anchoring / scrolling (engine-internal) ──
2557
+ anchorTo: (...args: any[]) => any;
2558
+ setAnchor: (...args: any[]) => any;
2559
+ scrollTo: (...args: any[]) => any;
2560
+ scrollToWidget: (...args: any[]) => any;
2561
+ scrollableY: (id: any) => number;
2562
+ scrollableX: (id: any) => number;
2563
+ pushScrollRoot: (...args: any[]) => any;
2564
+ popScrollRoot: (...args: any[]) => any;
2565
+ onScrollableScroll: (...args: any[]) => any;
2566
+ onScrollableViewport: (...args: any[]) => any;
2567
+
2568
+ // Key-code table (e.g. zi.Key.Enter).
2569
+ Key: Record<string, number>;
2570
+
2571
+ // Overlay / notification / focus sub-APIs.
2572
+ toast: ToastAPI;
2573
+ portal: PortalAPI;
2574
+ focus: FocusAPI;
2575
+ keymap: KeymapAPI;
2576
+ }
2577
+
2578
+ declare global {
2579
+ // ---- 语言底座(引擎内建,顶标准全局名)------------------------------------
2580
+ // 只实现忠实的那一部分:`TextDecoder` 仅 utf-8;`btoa`/`atob` 按规范收发 latin1
2581
+ // 二进制串。字节 ↔ base64 走 `Uint8Array.prototype.toBase64`(TC39)—— 那条不经
2582
+ // 二进制串,大数据快一个数量级。
2583
+ // 解码按 WHATWG **forgiving-base64**:`=` 可省、ASCII 空白自动剔除(PEM 换行体、
2584
+ // 省 padding 的 JWT 片段都能直接喂)。只认标准字母表 —— base64url 的 `-_` 要自己
2585
+ // 先换成 `+/`。
2586
+ class TextEncoder {
2587
+ readonly encoding: "utf-8";
2588
+ encode(input?: string): Uint8Array;
2589
+ }
2590
+ class TextDecoder {
2591
+ constructor(label?: string);
2592
+ readonly encoding: "utf-8";
2593
+ decode(input?: ArrayBuffer | ArrayBufferView): string;
2594
+ }
2595
+ function btoa(binary: string): string;
2596
+ function atob(base64: string): string;
2597
+ interface Uint8Array { toBase64(): string; }
2598
+ /** WHATWG `URL` 的**务实子集**:无 IDNA/punycode(非 ASCII 主机名原样带过),
2599
+ * 不做完整状态机。相对解析、`..` 规范化、默认端口省略、searchParams 联动都在。
2600
+ *
2601
+ * 除 `search` 外的字段一律 **readonly** —— 它们是解析产物(纯数据属性),赋值
2602
+ * 既不触发重组、也会被下一次 `toString()` 静默盖掉。要改就重新构造一个 `URL`,
2603
+ * 或走 `searchParams` / `search`(这两条会回写 `href`)。 */
2604
+ class URL {
2605
+ constructor(input: string, base?: string | URL);
2606
+ readonly protocol: string;
2607
+ readonly username: string;
2608
+ readonly password: string;
2609
+ readonly hostname: string;
2610
+ readonly port: string;
2611
+ readonly pathname: string;
2612
+ readonly hash: string;
2613
+ readonly href: string;
2614
+ readonly host: string;
2615
+ readonly origin: string;
2616
+ search: string;
2617
+ searchParams: URLSearchParams;
2618
+ toString(): string;
2619
+ toJSON(): string;
2620
+ }
2621
+ /** 编码按 application/x-www-form-urlencoded 序列化器(只有 `[A-Za-z0-9*-._]`
2622
+ * 保持字面,空格 → `+`)—— 与 `encodeURIComponent` 不同。
2623
+ *
2624
+ * 注意 `zi.http` 的 `form` 选项出的是 `%20` 而不是 `+`,**有意不统一**:`+` 是
2625
+ * 本序列化器的规范要求,`%20` 是签名场景(AWS SigV4 规范查询串)的规范要求。
2626
+ * 要对查询串签名就别用这里的 `toString()`。 */
2627
+ class URLSearchParams {
2628
+ constructor(init?: string | Record<string, string> | string[][] | URLSearchParams);
2629
+ readonly size: number;
2630
+ get(name: string): string | null;
2631
+ getAll(name: string): string[];
2632
+ has(name: string): boolean;
2633
+ set(name: string, value: string): void;
2634
+ append(name: string, value: string): void;
2635
+ delete(name: string): void;
2636
+ sort(): void;
2637
+ forEach(cb: (value: string, name: string, parent: URLSearchParams) => void, thisArg?: any): void;
2638
+ keys(): IterableIterator<string>;
2639
+ values(): IterableIterator<string>;
2640
+ entries(): IterableIterator<[string, string]>;
2641
+ [Symbol.iterator](): IterableIterator<[string, string]>;
2642
+ toString(): string;
2643
+ }
2644
+ /** WebCrypto 的**子集**:摘要与 HMAC(raw 密钥),加上同步的 `getRandomValues`。
2645
+ * 没有非对称 / AES / deriveKey —— 特性检测会如实报告缺失。
2646
+ *
2647
+ * `subtle.*` 返回 Promise,但**底下是同步算完再 resolve** 的:几十 MB 的输入会在当前帧里
2648
+ * 一口气算完(低配 ARM 上 100ms+ 的掉帧),Promise 的形状不代表它不阻塞。大块
2649
+ * 数据请自己切片 + `zi.setTimeout` 分帧。`getRandomValues` 本身就是同步的,
2650
+ * 并且按规范把一次调用夹在 65536 字节。
2651
+ *
2652
+ * `data` / `keyData` 只收 BufferSource(ArrayBuffer 或其视图),普通数组和对象
2653
+ * 会被明确拒绝 —— 不会悄悄 ToString 成 `"97,98,99"` 去哈希。 */
2654
+ interface ZiCryptoKey {
2655
+ type: "secret";
2656
+ extractable: boolean;
2657
+ algorithm: { name: "HMAC"; hash: { name: string } };
2658
+ usages: string[];
2659
+ }
2660
+ const crypto: {
2661
+ /** 就地填入密码学随机字节并返回同一个视图。只收整数 TypedArray,超过 65536 字节抛 TypeError。 */
2662
+ getRandomValues<T extends Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | BigInt64Array | BigUint64Array>(typedArray: T): T;
2663
+ subtle: {
2664
+ digest(algorithm: string | { name: string }, data: ArrayBuffer | ArrayBufferView): Promise<ArrayBuffer>;
2665
+ importKey(format: "raw", keyData: ArrayBuffer | ArrayBufferView,
2666
+ algorithm: { name: "HMAC"; hash: string | { name: string } },
2667
+ extractable: boolean, usages: string[]): Promise<ZiCryptoKey>;
2668
+ sign(algorithm: "HMAC" | { name: "HMAC" }, key: ZiCryptoKey,
2669
+ data: ArrayBuffer | ArrayBufferView): Promise<ArrayBuffer>;
2670
+ verify(algorithm: "HMAC" | { name: "HMAC" }, key: ZiCryptoKey,
2671
+ signature: ArrayBuffer | ArrayBufferView,
2672
+ data: ArrayBuffer | ArrayBufferView): Promise<boolean>;
2673
+ };
2674
+ };
2675
+ interface Uint8ArrayConstructor { fromBase64(base64: string): Uint8Array; }
2676
+
2677
+ // `var` (not `const`) — required so framework runtime code can assign
2678
+ // to `zi.*` (e.g. `zi.ui = {...}`) without an `as any` cast.
2679
+ var zi: ZiGlobal;
2680
+
2681
+ // QuickJS host console (the DOM lib is intentionally excluded via
2682
+ // `lib: ["ES2021"]`, which would otherwise also declare it).
2683
+ var console: {
2684
+ log(...args: any[]): void;
2685
+ warn(...args: any[]): void;
2686
+ error(...args: any[]): void;
2687
+ info(...args: any[]): void;
2688
+ debug(...args: any[]): void;
2689
+ [k: string]: any;
2690
+ };
2691
+
2692
+ // Raw runtime natives the components call directly (registered by the
2693
+ // engine before any component module runs). The `zi.*` wrappers are
2694
+ // preferred, but presets use these low-level setters as well; declare
2695
+ // them so `.tsx` components type-check.
2696
+ function __zi_set_style(id: any, style: any): void;
2697
+ function __zi_replace_style(id: any, style: any): void;
2698
+ function __zi_set_text(id: any, text: string): void;
2699
+ function __zi_set_text_runs(
2700
+ id: any,
2701
+ runs: { text: string; color?: any; weight?: any }[],
2702
+ ): void;
2703
+ function __zi_set_children(id: any, ids: any[]): void;
2704
+ function __zi_set_top(id: any, top: number): void;
2705
+ function __zi_set_left(id: any, left: number): void;
2706
+ function __zi_set_layer_opacity(id: any, opacity: number): void;
2707
+ function __zi_set_layer_style(id: any, style: any): void;
2708
+ function __zi_after_layout(id: any, fn: () => void): void;
2709
+ function __zi_image_set_color(id: any, color: any): void;
2710
+ function __zi_image_set_src(id: any, src: string): void;
2711
+ function __zi_set_enabled(id: any, enabled: boolean): void;
2712
+ function __zi_focus_clear_subtree(rootId: any): void;
2713
+ function __zi_current_scope_id(): number;
2714
+ function __zi_input_set_value(id: any, value: string): void;
2715
+ function __zi_input_get_value(id: any): string;
2716
+ function __zi_input_get_selection(id: any): [number, number];
2717
+ function __zi_input_set_selection(id: any, start: number, end: number): void;
2718
+ function __zi_input_insert_text(id: any, text: string): void;
2719
+ function __zi_input_delete_selection(id: any): void;
2720
+ function __zi_input_select_all(id: any): void;
2721
+ function __zi_input_copy_selection(id: any): boolean;
2722
+ function __zi_input_cut_selection(id: any): boolean;
2723
+ function __zi_input_set_readonly(id: any, readonly: boolean): void;
2724
+ /** 换掉 Input 的占位文字。有 setter 才能翻译它 —— 创建期那一档只读一次。 */
2725
+ function __zi_input_set_placeholder(id: any, text: string): void;
2726
+ function __zi_textarea_set_placeholder(id: any, text: string): void;
2727
+ function __zi_input_set_stepper(id: any, colors: any): void;
2728
+ function __zi_divider_set_color(id: any, color: any, highlight?: any): void;
2729
+ // 图表:三个 native 覆盖四种图表 —— 数据形状都是「一个数或一组数」,旋钮都是
2730
+ // 「一个对象」,所以按关注点切而不是按类型切。
2731
+ //
2732
+ // `options` 里 **undefined = 不动这项、null = 关掉**(阈值线、y 量程、底槽)。
2733
+ // 每种图表只取自己认识的键,多给的静默忽略 —— tsx 可以一份 effect 推全套。
2734
+ function __zi_chart_set_data(id: any, values: number | number[], colors?: any[]): void;
2735
+ function __zi_chart_set_options(id: any, options: ZiChartOptions): void;
2736
+ // 各段在半径 `radial`(相对比例)处的落点 + 占比。只给几何 ——「多小算小、往外挪
2737
+ // 多少」与字号和图的物理尺寸有关,是调用方的语境(按需调两次自己挑)。
2738
+ function __zi_chart_pie_labels(id: any, radial?: number): { x: number; y: number; frac: number; index: number }[];
2739
+ function __zi_listview_set_row_colors(id: any, colors: any): void;
2740
+ function __zi_listview_set_item_count(id: any, count: number): void;
2741
+ function __zi_listview_set_selected(id: any, index: number): void;
2742
+ function __zi_listview_ensure_visible(id: any, index: number): void;
2743
+ function __zi_listview_invalidate(id: any): void;
2744
+ function __zi_listview_set_row_metrics(id: any, metrics: any): void;
2745
+ function __zi_text_copy_selection(id: any): boolean;
2746
+ function __zi_text_get_selection(id: any): [number, number];
2747
+ function __zi_textarea_set_value(id: any, value: string): void;
2748
+ function __zi_textarea_get_value(id: any): string;
2749
+ function __zi_textarea_get_selection(id: any): [number, number];
2750
+ function __zi_textarea_set_selection(id: any, start: number, end: number): void;
2751
+ function __zi_textarea_insert_text(id: any, text: string): void;
2752
+ function __zi_textarea_delete_selection(id: any): void;
2753
+ function __zi_textarea_select_all(id: any): void;
2754
+ function __zi_textarea_copy_selection(id: any): boolean;
2755
+ function __zi_textarea_cut_selection(id: any): boolean;
2756
+ function __zi_textarea_set_readonly(id: any, readonly: boolean): void;
2757
+ // CodeEditor(虚拟化只读视口)。调色板整份推一次,run 里只带下标 ——
2758
+ // 颜色不随每个 token 过 FFI,解析仍由引擎的 css.color.parse 负责。
2759
+ function __zi_editor_set_palette(id: any, entries: { color?: any; weight?: any }[]): void;
2760
+ // 一个视口窗口的着色 runs。扁平、不含文本、不含颜色:
2761
+ // [nLines, (nRuns, (utf8ByteLen, paletteIdx)*nRuns)*nLines]
2762
+ function __zi_editor_set_runs_batch(id: any, firstLine: number, flat: number[] | Int32Array): void;
2763
+ // 语言表 —— EditPlus .stx 的等价物。装完之后高亮全在引擎里跑,
2764
+ // 每个 token 都不过 FFI。keywords: [[paletteIdx, "空格分隔的词表"], …]
2765
+ function __zi_editor_set_language(id: any, def: any): void;
2766
+ function __zi_editor_set_text(id: any, text: string): void;
2767
+ function __zi_editor_document_create(opts?: { text?: string; language?: any }): EditorDocument;
2768
+ function __zi_editor_document_set_text(id: EditorDocument, text: string): void;
2769
+ function __zi_editor_document_set_language(id: EditorDocument, language: any): void;
2770
+ function __zi_editor_document_destroy(id: EditorDocument): void;
2771
+ function __zi_editor_line_count(id: any): number;
2772
+ function __zi_editor_get_selection(id: any): [number, number];
2773
+ function __zi_editor_select_all(id: any): void;
2774
+ function __zi_editor_copy_selection(id: any): boolean;
2775
+ function __zi_editor_selected_text(id: any): string;
2776
+ function __zi_editor_visible_range(id: any): [number, number];
2777
+ function __zi_editor_scroll_to_line(id: any, line: number): void;
2778
+ function __zi_set_scrollbar(opts: any): void;
2779
+ function __zi_set_default_text_color(color: any): void;
2780
+ function __zi_set_scrollbar_theme(opts: { thumb?: string; thumbHover?: string; thumbActive?: string; width?: number; margin?: number }): void;
2781
+ function __zi_h(tag: any, props?: any, children?: any): any;
2782
+ function __zi_widget_abs_rect(id: any): { x: number; y: number; w: number; h: number } | null;
2783
+ // Keyframe player natives — driven by the `zi.animate` wrapper.
2784
+ // channelsFlat: [kind, nStops, pct,val, …]; clockFlat: [dur, easing,
2785
+ // delay, repeat, yoyo, baseDir, hasSlow]. onSettled fires once with
2786
+ // `completed`; onFrame fires each frame with linear progress (slow
2787
+ // channels). Returns id ≥ 1, or -1 on failure.
2788
+ function __zi_anim_create(target: any, channelsFlat: number[], clockFlat: number[], onSettled: ((completed: boolean) => void) | null, onFrame: ((t: number) => void) | null): number;
2789
+ function __zi_anim_play(id: number): void;
2790
+ function __zi_anim_pause(id: number): void;
2791
+ function __zi_anim_reverse(id: number): void;
2792
+ function __zi_anim_cancel(id: number): void;
2793
+ // Reactive-scope natives used by Show/For control-flow instances.
2794
+ function __zi_effect_scoped(fn: () => void): number; // returns disposable effect id
2795
+ function __zi_dispose_effect(id: number): void;
2796
+ function __zi_rerun_effect(id: number): void; // re-run + re-track a scoped effect
2797
+ function __zi_subtree_ids(rootId: any): number[]; // deep element ids of a subtree
2798
+ // 直接子 element id —— **只枚举 flex / stack 的孩子**:Control / Modal 托管的那个
2799
+ // child 不在里面(要下探它们用 `__zi_subtree_ids`)。
2800
+ function __zi_children_ids(cid: any): number[];
2801
+ function __zi_is_widget(v: any): boolean; // `zi.isWidget` 的真身(形状 + registry 里有活槽)
2802
+ function __zi_portal_children_ids(): number[]; // overlay root's direct child ids
2803
+
2804
+ namespace JSX {
2805
+ interface IntrinsicElements {}
2806
+
2807
+ // A zi element is an opaque widget HANDLE (see ZiWidget): a number at
2808
+ // runtime, but branded so a plain number can't stand in for one.
2809
+ type Element = import("./zi").ZiWidget;
2810
+
2811
+ // What may appear as a JSX tag: a zi component function.
2812
+ // zi components take `(props, children?)` and return a widget
2813
+ // id — TS checks JSX attributes against the FIRST parameter (props).
2814
+ type ElementType = (props: any, children?: any) => any;
2815
+
2816
+ // JSX children are checked against the `children` prop name…
2817
+ interface ElementChildrenAttribute {
2818
+ children: {};
2819
+ }
2820
+ // …and `children` is permitted on every element: a zi component receives
2821
+ // children as its 2nd argument, so it need not declare them in props.
2822
+ interface IntrinsicAttributes {
2823
+ children?: any;
2824
+ }
2825
+ }
2826
+ }