@narumitw/pi-btw 0.63.0 → 0.63.1

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.
@@ -4,7 +4,15 @@
4
4
 
5
5
  BTW keeps its side-thread policy separate from Pi's renderer and Kit's shared screens.
6
6
  Local improvements do not remove the need for a public Pi workspace API.
7
- The contracts below are proposals, not available Pi APIs. No external issue, core change, or publication is implied.
7
+ The upstream Pi contracts below are proposals, not available Pi APIs. No external issue, core change, or publication is implied.
8
+
9
+ ## Shared physical handoff extraction
10
+
11
+ The Kit `createFullscreenHandoff()` resource shares only terminal entry, native drain, stop/start, owned-overlay hiding, and restoration. BTW retains its multi-screen context adapter, private split-pane layout integration, input priority, paste handling, selection/copy, root cancellation, main-thread updates, bring-to-main, and queued settings writes.
12
+
13
+ The [retained shared matrix and verification record](https://github.com/narumiruna/pi-extensions/blob/main/packages/pi-tui-kit/docs/fullscreen-handoff.md) records two-consumer admission with Starship, lifecycle regressions, artifact and PTY smokes, dependency propagation, and exact-artifact release guards. Historical checks below do not replace the shared resource's evidence. The proposed Pi workspace-composition API remains necessary.
14
+
15
+ Pi's official [TUI guidance](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/tui.md) advises against a second terminal renderer. BTW intentionally deviates: a second TUI instance exists, but only one renderer actively owns the shared terminal. Extracting the physical lifecycle into Kit does not make that deviation officially supported or remove private layout access from BTW.
8
16
 
9
17
  ## Evidence boundary
10
18
 
@@ -242,7 +250,7 @@ These steps define contract tests, not instructions to open a live provider or i
242
250
 
243
251
  The Pi core maintainer owns API design, implementation, tests, and publication after repository-owner approval.
244
252
  A later authorized BTW migration must pass the existing native-dispatch and terminal-restoration regressions before removing the workaround.
245
- No new Kit API or raised BTW dependency floor is required for this handoff.
253
+ No new Kit API or raised BTW dependency floor was required for that upstream API proposal. The separate shared physical-handoff extraction above must require the Kit release that first contains its API before dependent publication.
246
254
 
247
255
  ## Verification and remaining acceptance
248
256
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-btw",
3
- "version": "0.63.0",
3
+ "version": "0.63.1",
4
4
  "description": "Pi extension that adds a /btw side-question command.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -32,9 +32,9 @@
32
32
  "prepack": "npm run build"
33
33
  },
34
34
  "devDependencies": {
35
- "@earendil-works/pi-ai": "1.3.0",
36
- "@earendil-works/pi-coding-agent": "1.3.0",
37
- "@earendil-works/pi-tui": "1.3.0",
35
+ "@earendil-works/pi-ai": "1.4.0",
36
+ "@earendil-works/pi-coding-agent": "1.4.0",
37
+ "@earendil-works/pi-tui": "1.4.0",
38
38
  "esbuild": "0.28.2",
39
39
  "typescript": "7.0.2"
40
40
  },
@@ -44,7 +44,7 @@
44
44
  "directory": "packages/pi-btw"
45
45
  },
46
46
  "dependencies": {
47
- "@narumitw/pi-tui-kit": "^0.64.0"
47
+ "@narumitw/pi-tui-kit": "^0.67.0"
48
48
  },
49
49
  "peerDependencies": {
50
50
  "@earendil-works/pi-ai": "*",
@@ -5,6 +5,7 @@ import {
5
5
  type Theme,
6
6
  } from "@earendil-works/pi-coding-agent";
7
7
  import { type Component, type OverlayHandle, ScrollView, type TUI, truncateToWidth } from "@earendil-works/pi-tui";
8
+ import type { createFullscreenHandoff, FullscreenHandoff } from "@narumitw/pi-tui-kit";
8
9
  import {
9
10
  type BtwFullscreenTui,
10
11
  createBtwFullscreenTui,
@@ -83,6 +84,10 @@ export async function runBtwFullscreen<T>(
83
84
  options: BtwFullscreenOptions = {},
84
85
  dependencies: BtwFullscreenDependencies = {},
85
86
  ): Promise<T> {
87
+ const { createFullscreenHandoff } = await import("@narumitw/pi-tui-kit/fullscreen-handoff");
88
+ if (ctx.signal?.aborted || options.signal?.aborted || options.canRestoreParent?.() === false) {
89
+ throw new FullscreenUiDisposedError();
90
+ }
86
91
  const createTui =
87
92
  dependencies.createTui ??
88
93
  ((parent: TUI, theme: Theme, keybindings: KeybindingsManager, fullscreenOptions: BtwFullscreenOptions) =>
@@ -121,6 +126,7 @@ export async function runBtwFullscreen<T>(
121
126
  },
122
127
  createTui,
123
128
  options,
129
+ createFullscreenHandoff,
124
130
  );
125
131
  return host;
126
132
  },
@@ -142,7 +148,7 @@ export async function runBtwFullscreen<T>(
142
148
 
143
149
  class BtwFullscreenHost<T> implements Component {
144
150
  private fullscreen: BtwFullscreenTui | undefined;
145
- private parentOverlay: OverlayHandle | undefined;
151
+ private readonly handoff: FullscreenHandoff<BtwFullscreenTui>;
146
152
  private cancelActiveCustom: (() => void) | undefined;
147
153
  private hardCancelActiveCustom: (() => void) | undefined;
148
154
  private removeHardCancelListener: (() => void) | undefined;
@@ -150,13 +156,8 @@ class BtwFullscreenHost<T> implements Component {
150
156
  private started = false;
151
157
  private disposed = false;
152
158
  private finished = false;
153
- private parentStopped = false;
154
- private parentRestoreAttempted = false;
155
- private fullscreenCreated = false;
156
- private fullscreenStopped = false;
157
- private parentRestoreQueued = false;
158
159
  private parentRestorePromise: Promise<void> | undefined;
159
- private cleanupError: unknown;
160
+ private readonly cleanupErrors: unknown[] = [];
160
161
  private removeMainThreadUpdateListener: (() => void) | undefined;
161
162
  private mainThreadRefreshTimer: ReturnType<typeof setTimeout> | undefined;
162
163
  private readonly mainThreadInput: BtwMainThreadInput;
@@ -175,6 +176,7 @@ class BtwFullscreenHost<T> implements Component {
175
176
  private readonly done: (outcome: FullscreenOutcome<T>) => void,
176
177
  private readonly createTui: BtwFullscreenTuiFactory,
177
178
  private readonly options: BtwFullscreenOptions,
179
+ createHandoff: typeof createFullscreenHandoff,
178
180
  ) {
179
181
  const initialMainInput = getFocusedComponent(parent);
180
182
  this.mainThreadInput = new BtwMainThreadInput(
@@ -185,12 +187,20 @@ class BtwFullscreenHost<T> implements Component {
185
187
  },
186
188
  () => this.fullscreen?.requestRender(),
187
189
  );
190
+ this.handoff = createHandoff<BtwFullscreenTui>(parent, {
191
+ isCurrent: () =>
192
+ !this.disposed &&
193
+ !this.finished &&
194
+ !this.lifetimeController.signal.aborted &&
195
+ this.options.canRestoreParent?.() !== false,
196
+ canRestoreParent: () => this.options.canRestoreParent?.() !== false,
197
+ });
188
198
  this.sidePaneRatio = options.sidePaneRatio;
189
199
  queueMicrotask(() => void this.start());
190
200
  }
191
201
 
192
202
  setParentOverlay(overlay: OverlayHandle): void {
193
- this.parentOverlay = overlay;
203
+ this.handoff.setOverlayHandle(overlay);
194
204
  }
195
205
 
196
206
  render(width: number): string[] {
@@ -221,12 +231,12 @@ class BtwFullscreenHost<T> implements Component {
221
231
  getParentFullscreenLayout(this.parent);
222
232
  getParentFullscreenScrollView(this.parent);
223
233
  }
224
- this.parent.stop({ preserveScreen: true });
225
- this.parentStopped = true;
226
- if (this.disposed) throw new FullscreenUiDisposedError();
227
- this.fullscreen = this.createTui(this.parent, this.theme, this.keybindings, this.options);
228
- this.fullscreenCreated = true;
229
- this.fullscreen.start();
234
+ this.fullscreen = await this.handoff.enter(() =>
235
+ this.createTui(this.parent, this.theme, this.keybindings, this.options),
236
+ );
237
+ if (!this.fullscreen || this.disposed || this.finished || this.options.canRestoreParent?.() === false) {
238
+ throw new FullscreenUiDisposedError();
239
+ }
230
240
  this.watchMainThreadUpdates();
231
241
  const shortcuts = resolveBtwShortcuts(
232
242
  this.options.keybindings,
@@ -287,11 +297,19 @@ class BtwFullscreenHost<T> implements Component {
287
297
  try {
288
298
  this.cancelActiveCustom?.();
289
299
  } catch (error) {
290
- this.cleanupError ??= error;
300
+ this.cleanupErrors.push(error);
301
+ }
302
+ this.queueParentRestore();
303
+ await this.parentRestorePromise;
304
+ if (this.cleanupErrors.length) {
305
+ outcome = {
306
+ kind: "failed",
307
+ error: combineErrors(
308
+ outcome.kind === "failed" ? [outcome.error, ...this.cleanupErrors] : this.cleanupErrors,
309
+ "Pi BTW flow and terminal cleanup failed",
310
+ ),
311
+ };
291
312
  }
292
- if (this.parentRestorePromise) await this.parentRestorePromise;
293
- else this.restoreParent();
294
- if (this.cleanupError !== undefined) outcome = { kind: "failed", error: this.cleanupError };
295
313
  this.finished = true;
296
314
  this.done(outcome);
297
315
  }
@@ -333,16 +351,13 @@ class BtwFullscreenHost<T> implements Component {
333
351
  }
334
352
 
335
353
  private queueParentRestore(): void {
336
- if (this.parentRestoreQueued || this.parentRestoreAttempted) return;
337
- this.parentRestoreQueued = true;
354
+ if (this.parentRestorePromise) return;
355
+ const restoration = this.handoff.restore().catch((error: unknown) => {
356
+ this.cleanupErrors.push(error);
357
+ });
338
358
  this.parentRestorePromise = Promise.resolve().then(async () => {
339
- try {
340
- await this.fullscreen?.terminal.drainInput?.();
341
- } catch (error) {
342
- this.cleanupError ??= error;
343
- }
344
- this.parentRestoreQueued = false;
345
359
  this.restoreParent();
360
+ await restoration;
346
361
  });
347
362
  }
348
363
 
@@ -369,50 +384,26 @@ class BtwFullscreenHost<T> implements Component {
369
384
  try {
370
385
  removeMainThreadUpdateListener?.();
371
386
  } catch (error) {
372
- this.cleanupError ??= error;
387
+ this.cleanupErrors.push(error);
373
388
  }
374
389
  try {
375
390
  this.mainThreadInput.dispose();
376
391
  } catch (error) {
377
- this.cleanupError ??= error;
392
+ this.cleanupErrors.push(error);
378
393
  }
379
394
  const removeUpstreamAbortListener = this.removeUpstreamAbortListener;
380
395
  this.removeUpstreamAbortListener = undefined;
381
396
  try {
382
397
  removeUpstreamAbortListener?.();
383
398
  } catch (error) {
384
- this.cleanupError ??= error;
399
+ this.cleanupErrors.push(error);
385
400
  }
386
401
  const removeHardCancelListener = this.removeHardCancelListener;
387
402
  this.removeHardCancelListener = undefined;
388
403
  try {
389
404
  removeHardCancelListener?.();
390
405
  } catch (error) {
391
- this.cleanupError ??= error;
392
- }
393
- if (this.fullscreenCreated && !this.fullscreenStopped) {
394
- this.fullscreenStopped = true;
395
- try {
396
- this.fullscreen?.stop({ preserveScreen: true });
397
- } catch (error) {
398
- this.cleanupError ??= error;
399
- }
400
- }
401
- if (!this.parentStopped || this.parentRestoreAttempted) return;
402
- const parentOverlay = this.parentOverlay;
403
- this.parentOverlay = undefined;
404
- try {
405
- parentOverlay?.setHidden(true);
406
- } catch (error) {
407
- this.cleanupError ??= error;
408
- }
409
- try {
410
- this.parentRestoreAttempted = true;
411
- if (this.options.canRestoreParent?.() === false) return;
412
- this.parent.start();
413
- this.parent.renderNow(false);
414
- } catch (error) {
415
- this.cleanupError ??= error;
406
+ this.cleanupErrors.push(error);
416
407
  }
417
408
  }
418
409
 
@@ -487,23 +478,23 @@ class BtwFullscreenHost<T> implements Component {
487
478
  componentDisposed = true;
488
479
  try {
489
480
  component.dispose?.();
490
- } catch {
491
- // Cleanup must continue so terminal ownership is restored.
481
+ } catch (error) {
482
+ this.cleanupErrors.push(error);
492
483
  }
493
484
  };
494
485
  const unmount = () => {
495
- let cleanupError: unknown;
486
+ const cleanupErrors: unknown[] = [];
496
487
  const removeFocusListener = removePaneFocusListener;
497
488
  removePaneFocusListener = undefined;
498
489
  try {
499
490
  removeFocusListener?.();
500
491
  } catch (error) {
501
- cleanupError = error;
492
+ cleanupErrors.push(error);
502
493
  }
503
494
  try {
504
495
  splitPane?.dispose();
505
496
  } catch (error) {
506
- cleanupError ??= error;
497
+ cleanupErrors.push(error);
507
498
  }
508
499
  splitPane = undefined;
509
500
  try {
@@ -511,18 +502,18 @@ class BtwFullscreenHost<T> implements Component {
511
502
  else if (mounted && layoutMounted) fullscreen.setLayoutRoot(undefined);
512
503
  else if (mounted && component) fullscreen.removeChild(component);
513
504
  } catch (error) {
514
- cleanupError ??= error;
505
+ cleanupErrors.push(error);
515
506
  }
516
507
  if (overlay || mounted) {
517
508
  try {
518
509
  fullscreen.setFocus(null);
519
510
  fullscreen.requestRender();
520
511
  } catch (error) {
521
- cleanupError ??= error;
512
+ cleanupErrors.push(error);
522
513
  }
523
514
  }
524
515
  disposeComponent();
525
- if (cleanupError !== undefined) throw cleanupError;
516
+ if (cleanupErrors.length) throw combineErrors(cleanupErrors, "Pi BTW custom UI cleanup failed");
526
517
  };
527
518
  const complete = () => {
528
519
  if (promiseSettled || !hasPendingValue) return;
@@ -557,7 +548,7 @@ class BtwFullscreenHost<T> implements Component {
557
548
  unmount();
558
549
  reject(error);
559
550
  } catch (cleanupError) {
560
- reject(cleanupError);
551
+ reject(combineErrors([error, cleanupError], "Pi BTW custom UI and cleanup failed"));
561
552
  }
562
553
  };
563
554
  this.cancelActiveCustom = () => {
@@ -710,6 +701,35 @@ class BtwFullscreenHost<T> implements Component {
710
701
  }
711
702
  }
712
703
 
704
+ // Keep an existing aggregate intact unless it overlaps causes already collected.
705
+ function combineErrors(errors: readonly unknown[], message: string): unknown {
706
+ const causes: unknown[] = [];
707
+ const seen = new Set<unknown>();
708
+ const remember = (error: unknown): void => {
709
+ if (seen.has(error)) return;
710
+ seen.add(error);
711
+ if (error instanceof AggregateError) error.errors.forEach(remember);
712
+ };
713
+ const overlaps = (error: unknown, visited = new Set<unknown>()): boolean => {
714
+ if (seen.has(error)) return true;
715
+ if (visited.has(error)) return false;
716
+ visited.add(error);
717
+ return error instanceof AggregateError && error.errors.some((cause: unknown) => overlaps(cause, visited));
718
+ };
719
+ const append = (error: unknown): void => {
720
+ if (seen.has(error)) return;
721
+ if (error instanceof AggregateError && overlaps(error)) {
722
+ seen.add(error);
723
+ error.errors.forEach(append);
724
+ return;
725
+ }
726
+ causes.push(error);
727
+ remember(error);
728
+ };
729
+ errors.forEach(append);
730
+ return causes.length === 1 ? causes[0] : new AggregateError(causes, message);
731
+ }
732
+
713
733
  function formatError(error: unknown): string {
714
734
  return error instanceof Error ? error.message : String(error);
715
735
  }