gentle-shell-bridge 0.0.0-stage → 0.3.0

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.
Files changed (112) hide show
  1. package/.codegraph/.gitignore +5 -0
  2. package/PRD.md +144 -0
  3. package/README.md +745 -2
  4. package/docs/architecture.md +981 -0
  5. package/docs/contract.md +1266 -0
  6. package/docs/state.md +251 -0
  7. package/examples/bash-card.ts +1694 -0
  8. package/gentle-shell-bridge-0.3.0.tgz +0 -0
  9. package/odd/tasks/palette-sections.md +30 -0
  10. package/odd/tasks/plugin-keymap.md +32 -0
  11. package/odd/tasks/plugin-surface-contract.md +55 -0
  12. package/package.json +35 -4
  13. package/src/api.ts +492 -0
  14. package/src/arm.ts +83 -0
  15. package/src/bus.ts +558 -0
  16. package/src/capture.ts +886 -0
  17. package/src/card-style-line.ts +112 -0
  18. package/src/card-style-rows.ts +390 -0
  19. package/src/card-style-transform.ts +862 -0
  20. package/src/card-style-wiring.ts +472 -0
  21. package/src/card-styles.ts +159 -0
  22. package/src/config.ts +71 -0
  23. package/src/extension.ts +271 -0
  24. package/src/hook.ts +310 -0
  25. package/src/index.ts +71 -0
  26. package/src/notices.ts +137 -0
  27. package/src/plugin-lines.ts +865 -0
  28. package/src/plugin-surface.ts +218 -0
  29. package/src/presence.ts +259 -0
  30. package/src/repaint.ts +351 -0
  31. package/src/row-labels.ts +146 -0
  32. package/src/row-names.ts +273 -0
  33. package/src/row-origin.ts +144 -0
  34. package/src/rows.ts +248 -0
  35. package/src/section-panel.ts +378 -0
  36. package/src/section-pointer.ts +164 -0
  37. package/src/sections-rows.ts +128 -0
  38. package/src/sidebar-render.ts +535 -0
  39. package/src/sidebar.ts +919 -0
  40. package/src/status.ts +1161 -0
  41. package/src/store.ts +279 -0
  42. package/src/tool-design-adoption.ts +263 -0
  43. package/src/tool-design-rows.ts +246 -0
  44. package/src/tool-design-wiring.ts +428 -0
  45. package/src/tool-designs.ts +402 -0
  46. package/src/transform-pipeline.ts +351 -0
  47. package/src/types.ts +442 -0
  48. package/src/visibility.ts +154 -0
  49. package/test/api.test.ts +395 -0
  50. package/test/apply-on-move.test.ts +477 -0
  51. package/test/arm.test.ts +220 -0
  52. package/test/bridge-ready.test.ts +309 -0
  53. package/test/bus.test.ts +165 -0
  54. package/test/button-rows.test.ts +409 -0
  55. package/test/capture.test.ts +356 -0
  56. package/test/card-style-rows.test.ts +510 -0
  57. package/test/card-style-transform.test.ts +379 -0
  58. package/test/card-style-wiring.test.ts +258 -0
  59. package/test/card-styles-e2e.test.ts +491 -0
  60. package/test/card-styles.test.ts +324 -0
  61. package/test/card-transcript-path.test.ts +178 -0
  62. package/test/config.test.ts +93 -0
  63. package/test/e2e.test.ts +443 -0
  64. package/test/example-bash-identity.test.ts +372 -0
  65. package/test/example-bash-matrix.test.ts +856 -0
  66. package/test/example-designs.test.ts +734 -0
  67. package/test/example-neon-transform.test.ts +283 -0
  68. package/test/example-plain-style.test.ts +1268 -0
  69. package/test/extension.test.ts +160 -0
  70. package/test/fake-events.ts +58 -0
  71. package/test/fake-host.ts +211 -0
  72. package/test/fake-sidebar.ts +516 -0
  73. package/test/fake-transcript.ts +486 -0
  74. package/test/frame-telemetry.test.ts +417 -0
  75. package/test/hook.test.ts +196 -0
  76. package/test/manifest.test.ts +105 -0
  77. package/test/new-category.test.ts +979 -0
  78. package/test/notices.test.ts +328 -0
  79. package/test/plugin-integration-lines.test.ts +979 -0
  80. package/test/plugin-surface.test.ts +152 -0
  81. package/test/presence.test.ts +459 -0
  82. package/test/rail-surfaces.test.ts +457 -0
  83. package/test/rail-width.test.ts +423 -0
  84. package/test/regression.test.ts +483 -0
  85. package/test/repaint-api.test.ts +200 -0
  86. package/test/reserved-categories.test.ts +361 -0
  87. package/test/row-labels.test.ts +284 -0
  88. package/test/row-names.test.ts +473 -0
  89. package/test/row-origin.test.ts +395 -0
  90. package/test/section-interaction.test.ts +364 -0
  91. package/test/section-panel.test.ts +403 -0
  92. package/test/sections-rows.test.ts +291 -0
  93. package/test/sidebar-backend.test.ts +471 -0
  94. package/test/sidebar-e2e.test.ts +331 -0
  95. package/test/sidebar-hover.test.ts +276 -0
  96. package/test/sidebar-independent.test.ts +349 -0
  97. package/test/sidebar-render.test.ts +281 -0
  98. package/test/sidebar-sections.test.ts +245 -0
  99. package/test/status-card-styles.test.ts +201 -0
  100. package/test/status-section-frame.test.ts +181 -0
  101. package/test/status-sections.test.ts +243 -0
  102. package/test/status.test.ts +209 -0
  103. package/test/store.test.ts +192 -0
  104. package/test/surface-repaint-cost.test.ts +520 -0
  105. package/test/tool-design-chain.test.ts +483 -0
  106. package/test/tool-design-cost.test.ts +473 -0
  107. package/test/tool-design-rows.test.ts +359 -0
  108. package/test/tool-designs.test.ts +745 -0
  109. package/test/transform-pipeline.test.ts +465 -0
  110. package/test/transforms-bus.test.ts +233 -0
  111. package/test/verifier-width-regressions.test.ts +164 -0
  112. package/tsconfig.json +18 -0
package/src/capture.ts ADDED
@@ -0,0 +1,886 @@
1
+ /**
2
+ * Capture backend (docs/architecture.md §2–§5, docs/contract.md §5, §7).
3
+ *
4
+ * gentle-shell's `ctx.ui.custom` factory returns a plain adapter, not the view, so the rows
5
+ * array is unreachable by duck-typing. The only reachable moment is the view constructor's
6
+ * `options.rows.map(...)` (`lib/visual-customize-view.ts:387`), which runs synchronously inside
7
+ * the factory call. So: swap `Array.prototype.map` for the duration of the outermost factory
8
+ * call, record every row-like array it is invoked on BY REFERENCE, restore the original in
9
+ * `finally`, then push the providers' rows into that captured array and invalidate the adapter.
10
+ *
11
+ * ## Two moments, because the view fixes its page list in the constructor (S18)
12
+ *
13
+ * The view derives `categories` ONCE, in the constructor
14
+ * (`this.categories = [...new Set(options.rows.map(row => row.category ?? "Settings"))]`,
15
+ * `lib/visual-customize-view.ts:387`). `categoryRows()` then filters `options.rows` live
16
+ * (`:391-393`), which is why a row that joins an EXISTING page appears after a late push — and
17
+ * why a row that names a BRAND-NEW page never did: the page list was already fixed, so nothing
18
+ * could select it.
19
+ *
20
+ * So the probe injects at the earlier moment too, for the one array it can PROVE is the menu's,
21
+ * BEFORE that array's `map` reads it. The host's `Set` then contains the new pages, in registry
22
+ * order, after the host's own pages.
23
+ *
24
+ * ## The early step is provisional and is reconciled at the end of the factory (S20)
25
+ *
26
+ * The early step is a GUESS about which array is the menu, made before the factory finished; the
27
+ * late decision is the one that knows (it holds every candidate, the ambiguity rule and the async
28
+ * check). So the early step is provisional, and the late decision has the last word:
29
+ *
30
+ * - every early push is recorded: the array, where the rows were appended, the rows themselves, the
31
+ * `Card style` splice it made, and the marker it set;
32
+ * - when the factory returns a component the late decision runs. If it picks the SAME array, the
33
+ * rows stay and the build is reported `injected`; if it picks ANOTHER array, the session proved
34
+ * several (ambiguous), or the factory returned a promise, the early rows, the splice and the
35
+ * marker are REMOVED from the early array and the previous behaviour applies exactly;
36
+ * - when the factory throws, the same rollback runs in the `finally` that restores
37
+ * `Array.prototype.map`, so a throw leaves no trace — and a session only ever rolls back the
38
+ * array it pushed into, so an inner factory's rollback can never touch the outer session's rows.
39
+ *
40
+ * Net guarantee: after any factory invocation, no array holds bridge rows except the one the late
41
+ * decision chose. The cost, stated honestly: for the duration of the factory an array that
42
+ * satisfies the strict proof can hold bridge rows, visible only to code running inside that
43
+ * factory, and the guess is undone whenever the decision disagrees with it.
44
+ *
45
+ * ## The proof: what makes an array the menu's rows
46
+ *
47
+ * Nothing is written to an array that is not PROVEN at that `map` call, and the proof runs on
48
+ * EVERY call — never once per array, because the host may map its rows to something else first.
49
+ * A `map` call proves the array when the callback, run exactly as `Array.prototype.map` runs it:
50
+ *
51
+ * - derives `row.category ?? "Settings"` for every element of the array;
52
+ * - derives `"Settings"` for a synthetic row with NO category, and a unique sentinel page for a
53
+ * synthetic row naming it — so `row => row.category` and any constant mapper cannot qualify on
54
+ * the host's own rows alone;
55
+ * - does not throw (a throw means "not proven", never a broken host call);
56
+ * - and derives `row.category ?? "Settings"` for every row the bridge is about to append, run over
57
+ * them BEFORE they are pushed, so the host's own `map` can never throw because of a bridge row.
58
+ *
59
+ * Stated cost of the proof: the host's mapper runs over the host's own rows once more per row-like
60
+ * `map` call, and once over each row the bridge appends. It is the host's own
61
+ * `row => row.category ?? "Settings"`, pure by construction in the host; a mapper with side effects
62
+ * sees them once more per element, which is the price of not guessing.
63
+ *
64
+ * Exactly one injection happens per menu build: the early path records what it pushed, the late
65
+ * path reports that and does not repeat it, and the array marker keeps a second build of the same
66
+ * menu from injecting twice.
67
+ *
68
+ * ## Capture-selection rule (why a wrong target can never be silent)
69
+ *
70
+ * Each wrapped `custom` call owns one capture *session* and one candidate list, and the probe
71
+ * records a mapped array into the innermost active session only. The probe is installed around the
72
+ * FACTORY INVOCATION, not around the host call, so a host that resolves its factory in a later
73
+ * microtask (`Promise.resolve().then(factory)`) is still covered; a factory that itself returns a
74
+ * promise stays the documented unsupported case, and the early guess is rolled back for it.
75
+ *
76
+ * - A nested `custom` call — from the host factory or from a provider's own `rows()` — gets its
77
+ * own session, so it can never steal the outer menu's capture, and its menu receives its own
78
+ * injection.
79
+ * - A nested session that throws rolls back only its own array: nothing is left in it, and the
80
+ * outer session continues and resolves its own array.
81
+ * - If ONE session captures more than one row-like array (an incidental row-shaped array before
82
+ * the menu, for example) the bridge does not guess: the outcome is `uncaptured (ambiguous)` and
83
+ * nothing is injected. The one exception is the proof above: when exactly ONE of those arrays
84
+ * derives pages like the menu does, that array is the menu by evidence and is what the late path
85
+ * takes (S18 needs it, or a brand-new page could never be reached); two proven arrays are
86
+ * ambiguous, and so are two unproven ones.
87
+ *
88
+ * Diagnostics never claim an injection into an array that received nothing.
89
+ *
90
+ * Arming is idempotent per target: the non-enumerable marker holds the exact wrapper function it
91
+ * installed, and is read as an OWN property, so a rebind that installs a new `custom` on an
92
+ * instance inheriting an already-wrapped prototype always rearms. Every wrapper also carries the
93
+ * generation it was created in: `disableCaptureBackend()` bumps the generation, so a wrapper that
94
+ * foreign code kept a reference to becomes a plain pass-through instead of injecting later.
95
+ *
96
+ * Shared state lives on `globalThis` behind a `Symbol.for` key, like the bus: a second copy of
97
+ * this package loaded by jiti's `moduleCache: false` must see the same arming, the same sessions
98
+ * and the same diagnostics.
99
+ */
100
+
101
+ import { extendCardStyleLine } from "./card-style-rows.ts";
102
+ import { findCardStyleLine } from "./card-style-line.ts";
103
+ import { buildRows, createRowContext, type RowBuildFailure } from "./rows.ts";
104
+ import type { CustomizeRow } from "./types.ts";
105
+
106
+ /** Marks a UI target this module wrapped; the value is the wrapper function it installed. */
107
+ const CAPTURE_WRAPPED = Symbol.for("gentle-shell-bridge.capture.wrapped.v1");
108
+ /** Marks a captured rows array that already received an injection. */
109
+ const CAPTURE_INJECTED = Symbol.for("gentle-shell-bridge.capture.injected.v1");
110
+ /** Process-global arming/diagnostics slot. */
111
+ const CAPTURE_STATE = Symbol.for("gentle-shell-bridge.capture.state.v1");
112
+
113
+ /**
114
+ * Minimum length for a mapped array to count as the host's rows array.
115
+ *
116
+ * There is no type or name to key on, so the shape test is structural: an array of at least
117
+ * three objects that each expose a callable `action`. The threshold comes from the probe that
118
+ * proved this technique in the real TUI, where the customize menu builds far more than three
119
+ * rows; three keeps incidental one- and two-element arrays of objects out of the capture without
120
+ * matching anything smaller. The cost is explicit: a host menu with fewer than three rows is
121
+ * below the threshold and would not be captured.
122
+ */
123
+ const MIN_ROW_ARRAY_LENGTH = 3;
124
+
125
+ /**
126
+ * The host's own category for a row that names none, read from the view's page derivation
127
+ * (`row.category ?? "Settings"`, `lib/visual-customize-view.ts:387`). The early injection's proof
128
+ * compares against it, so a host that renames the default falls back to the late path instead of
129
+ * qualifying an array on a guess.
130
+ */
131
+ const HOST_DEFAULT_CATEGORY = "Settings";
132
+
133
+ /**
134
+ * The page name no host row can name, used by the proof's second synthetic row (S20). A mapper that
135
+ * ignores its argument — a constant — cannot return this for one row and `"Settings"` for another,
136
+ * and a mapper that echoes `row.category` cannot return `"Settings"` for the row that has none.
137
+ */
138
+ const SENTINEL_CATEGORY = "gentle-shell-bridge probe sentinel";
139
+
140
+ /**
141
+ * The two rows the host never had. They are the whole difference between "this callback derives
142
+ * pages" and "this callback happens to fit these rows": an incidental array mapped with
143
+ * `row => row.category` fits the host's rows perfectly and returns `undefined` for the first one
144
+ * (JD-A-001).
145
+ */
146
+ const SYNTHETIC_PROOF_ROWS: readonly CustomizeRow[] = [
147
+ { label: "Bridge probe without a category", action: () => {} },
148
+ { category: SENTINEL_CATEGORY, label: "Bridge probe with a sentinel category", action: () => {} },
149
+ ];
150
+
151
+ /** A provider that threw while its rows were built; its rows were dropped. */
152
+ export type CaptureFailure = RowBuildFailure;
153
+
154
+ /** Outcome of the most recent menu build the backend observed. */
155
+ export interface CaptureOutcome {
156
+ kind: "injected" | "uncaptured" | "already-injected";
157
+ /** How many rows this backend pushed into the captured array. */
158
+ injectedRows: number;
159
+ /** Only for `uncaptured`: why nothing was injected. */
160
+ reason?: "async-factory" | "no-capture" | "ambiguous" | "factory-threw";
161
+ }
162
+
163
+ /** What diagnostics (`status`, S6) reads from the capture backend. */
164
+ export interface CaptureDiagnostics {
165
+ /** Number of UI targets currently wrapped in this process. */
166
+ armedTargets: number;
167
+ /** Nesting depth of in-flight `custom` calls; 0 when idle. */
168
+ nestingDepth: number;
169
+ lastOutcome?: CaptureOutcome;
170
+ /** Failures recorded during the most recent menu build. */
171
+ lastFailures: CaptureFailure[];
172
+ }
173
+
174
+ /** Result of one arming attempt, so diagnostics can report why nothing was armed. */
175
+ export interface InstallCaptureResult {
176
+ armed: boolean;
177
+ /** Where the wrapper landed: the instance's own `custom`, the prototype's, or nowhere. */
178
+ target: "instance" | "prototype" | "none";
179
+ outcome: "armed" | "already-armed" | "no-custom";
180
+ }
181
+
182
+ /**
183
+ * What the host's `custom` hands back: the plain adapter component gentle-shell returns
184
+ * (`gentle-shell.ts:3550-3562`), possibly wrapped in a promise (`interactive-mode.ts:3136`).
185
+ * Opaque by design — the bridge only ever calls `invalidate()`, and only on the sync shape.
186
+ */
187
+ export interface HostComponent {
188
+ invalidate?: () => void;
189
+ [key: string]: unknown;
190
+ }
191
+
192
+ export type HostCustomResult = HostComponent | PromiseLike<HostComponent>;
193
+
194
+ type HostCustom = (this: unknown, factory: unknown, ...rest: unknown[]) => HostCustomResult;
195
+ type HostFactory = (ui: unknown, theme: unknown, ...rest: unknown[]) => HostCustomResult;
196
+ /** `Array.prototype.map` with the argument types widened, for the temporary patch only. */
197
+ type LooseMap = (this: unknown, callback: unknown, thisArg?: unknown) => unknown[];
198
+
199
+ /**
200
+ * The callback a `map` call passed, typed the way `Array.prototype.map` calls it — the shape the
201
+ * proof runs it with, so a mapper sees exactly what it would have seen.
202
+ */
203
+ type CategoryMapper = (
204
+ this: unknown,
205
+ row: CustomizeRow,
206
+ index: number,
207
+ rows: readonly CustomizeRow[],
208
+ ) => unknown;
209
+
210
+ type MutableTarget = Record<PropertyKey, unknown> & { custom?: unknown };
211
+
212
+ type CaptureWrapper = (this: unknown, ...args: unknown[]) => HostCustomResult;
213
+
214
+ /** One wrapped `custom` call in flight, with the arrays its factory mapped. */
215
+ interface CaptureSession {
216
+ candidates: CustomizeRow[][];
217
+ /** The candidates that proved themselves to be the menu's rows at a `map` call (S20). */
218
+ proven: CustomizeRow[][];
219
+ /**
220
+ * The theme this factory invocation received, so the rows can be built BEFORE the factory
221
+ * returns — the early path runs inside the view constructor's own `map` call.
222
+ */
223
+ theme: unknown;
224
+ /** True while this session is building/injecting rows, so its own maps are not re-captured. */
225
+ injecting: boolean;
226
+ /** True while a `map` call is being proved, so a mapper that maps again cannot recurse. */
227
+ proving: boolean;
228
+ /**
229
+ * True once the host's own `Card style` line was extended in this build. The splice is not
230
+ * idempotent (`src/card-style-line.ts:94-109`), so exactly one of the two paths may do it — and a
231
+ * rollback clears it again, so the array the late path picks gets its splice.
232
+ */
233
+ extendedCardStyle: boolean;
234
+ /** What the early path pushed and where, so the late decision can keep or undo it (S20). */
235
+ earlyInjection?: EarlyInjection;
236
+ }
237
+
238
+ /** One provisional injection: what landed, where, and how to take it back out. */
239
+ interface EarlyInjection {
240
+ array: CustomizeRow[];
241
+ /** The array's length before the providers' rows were appended. */
242
+ start: number;
243
+ /** The rows appended, by identity, so a rollback removes exactly those and nothing else. */
244
+ rows: readonly CustomizeRow[];
245
+ /** The in-place `Card style` splice, when one happened, so a rollback can undo it exactly. */
246
+ cardStyle?: EarlyCardStyleSplice;
247
+ /** What the build recorded while failing, reported if the injection survives. */
248
+ failures: CaptureFailure[];
249
+ }
250
+
251
+ /** The provisional `Card style` splice, recorded so it can be undone (`spliceCardStyleValues`). */
252
+ interface EarlyCardStyleSplice {
253
+ /** Index of the host's line in the array. */
254
+ start: number;
255
+ /** How many host rows the splice replaced at that index. */
256
+ hostCount: number;
257
+ /** How many bridge value rows it inserted after them. */
258
+ values: number;
259
+ /** The host's own rows, by identity, exactly as they were before the splice. */
260
+ original: readonly CustomizeRow[];
261
+ }
262
+
263
+ interface CaptureState {
264
+ armedTargets: number;
265
+ nestingDepth: number;
266
+ /** Bumped by `disableCaptureBackend()`; a wrapper from an older generation is a pass-through. */
267
+ generation: number;
268
+ /** Innermost last: a mapped array is recorded into the top session only. */
269
+ sessions: CaptureSession[];
270
+ /** The `Array.prototype.map` in force before the probe was installed, while it is installed. */
271
+ savedMap?: typeof Array.prototype.map;
272
+ lastOutcome?: CaptureOutcome;
273
+ lastFailures: CaptureFailure[];
274
+ /** One record per wrapped target, so a backend transition can restore the host's own method. */
275
+ wrappers: Array<{ target: MutableTarget; original: unknown; wrapper: CaptureWrapper }>;
276
+ }
277
+
278
+ function captureHost(): Record<symbol, CaptureState | undefined> {
279
+ // SAFETY: the only writes to this key are the `captureState()` creation below, so if the key
280
+ // holds anything it is a CaptureState from this module. Foreign or partial values are not
281
+ // trusted: `captureState()` checks `armedTargets` and replaces an unusable slot.
282
+ return globalThis as unknown as Record<symbol, CaptureState | undefined>;
283
+ }
284
+
285
+ function captureState(): CaptureState {
286
+ const host = captureHost();
287
+ const existing = host[CAPTURE_STATE];
288
+ if (existing !== undefined && typeof existing.armedTargets === "number") return existing;
289
+ const created: CaptureState = {
290
+ armedTargets: 0,
291
+ nestingDepth: 0,
292
+ generation: 0,
293
+ sessions: [],
294
+ lastOutcome: undefined,
295
+ lastFailures: [],
296
+ wrappers: [],
297
+ };
298
+ host[CAPTURE_STATE] = created;
299
+ return created;
300
+ }
301
+
302
+ /** Diagnostics snapshot for `status` (S6) and for the backend's own tests. */
303
+ export function getCaptureDiagnostics(): CaptureDiagnostics {
304
+ const state = captureState();
305
+ return {
306
+ armedTargets: state.armedTargets,
307
+ nestingDepth: state.nestingDepth,
308
+ lastOutcome: state.lastOutcome,
309
+ lastFailures: [...state.lastFailures],
310
+ };
311
+ }
312
+
313
+ /**
314
+ * Test-only seam: forget arming counts, the last outcome and the last failures. Deliberately not
315
+ * re-exported from `src/index.ts`. Markers live on host objects and arrays and are not cleared;
316
+ * `disableCaptureBackend()` is the seam that unwraps.
317
+ */
318
+ export function resetCaptureStateForTests(): void {
319
+ const state = captureState();
320
+ state.armedTargets = 0;
321
+ state.nestingDepth = 0;
322
+ // Bump so wrappers left in foreign closures from an earlier test become pass-throughs.
323
+ state.generation += 1;
324
+ state.sessions = [];
325
+ state.savedMap = undefined;
326
+ state.lastOutcome = undefined;
327
+ state.lastFailures = [];
328
+ state.wrappers = [];
329
+ }
330
+
331
+ /** The probe records into the innermost session and forwards to the saved original. */
332
+ const probe = function (this: unknown, callback: unknown, thisArg?: unknown): unknown[] {
333
+ const state = captureState();
334
+ const session = state.sessions[state.sessions.length - 1];
335
+ if (session !== undefined) {
336
+ try {
337
+ if (isRowLikeArray(this)) {
338
+ if (!session.candidates.includes(this)) session.candidates.push(this);
339
+ // S18: a brand-new page only exists if the rows are already in the array when the host's
340
+ // own `map` reads it, so the proof and the push happen BEFORE the call is forwarded. S20:
341
+ // the proof is evaluated on EVERY call, and the push is provisional until the factory ends.
342
+ observeRowMap(session, this, callback, thisArg);
343
+ }
344
+ } catch {
345
+ // Never break the host's own `map` call.
346
+ }
347
+ }
348
+
349
+ const original = state.savedMap;
350
+ // Unreachable while the probe is installed (installing saves the original first); returning an
351
+ // empty array keeps the host's call from throwing if a foreign swap cleared the saved value.
352
+ if (original === undefined) return [];
353
+ // SAFETY: `original` is the real `Array.prototype.map` captured in `installProbe()`; `LooseMap`
354
+ // only widens the parameter types so this forwards whatever the host's own call passed.
355
+ return (original as unknown as LooseMap).call(this, callback, thisArg);
356
+ };
357
+
358
+ function installProbe(): void {
359
+ const state = captureState();
360
+ if (state.savedMap !== undefined) return;
361
+ state.savedMap = Array.prototype.map;
362
+ // SAFETY: `probe` forwards the exact (callback, thisArg) pair to the saved original and only
363
+ // observes `this`, so it is a behavioural drop-in for the duration of one outermost call; the
364
+ // original is restored by `removeProbe()` in the wrapper's `finally`.
365
+ Array.prototype.map = probe as unknown as typeof Array.prototype.map;
366
+ }
367
+
368
+ function removeProbe(): void {
369
+ const state = captureState();
370
+ const saved = state.savedMap;
371
+ if (saved === undefined) return;
372
+ Array.prototype.map = saved;
373
+ state.savedMap = undefined;
374
+ }
375
+
376
+ /**
377
+ * Arm the capture backend on a `ctx.ui`-shaped object. Idempotent per target and per function:
378
+ * the marker is an own property holding the exact wrapper installed, so a rebind that gives the
379
+ * instance a new `custom` always rearms instead of reporting a stale `already-armed`.
380
+ *
381
+ * Both shapes Pi can use are covered. When the instance owns `custom`, that own property is
382
+ * wrapped. Otherwise the prototype method that provides `custom` is wrapped once for every
383
+ * instance that inherits it.
384
+ */
385
+ export function installCaptureBackend(ui: unknown): InstallCaptureResult {
386
+ if (ui === null || typeof ui !== "object") {
387
+ return { armed: false, target: "none", outcome: "no-custom" };
388
+ }
389
+ const instance = ui as MutableTarget;
390
+
391
+ if (Object.prototype.hasOwnProperty.call(instance, "custom")) {
392
+ return wrapCustom(instance, "instance");
393
+ }
394
+
395
+ const proto: unknown = Object.getPrototypeOf(instance);
396
+ const protoCustom =
397
+ proto !== null && typeof proto === "object" ? (proto as MutableTarget).custom : undefined;
398
+ if (typeof protoCustom === "function") {
399
+ return wrapCustom(proto as MutableTarget, "prototype");
400
+ }
401
+
402
+ return { armed: false, target: "none", outcome: "no-custom" };
403
+ }
404
+
405
+ function wrapCustom(target: MutableTarget, shape: "instance" | "prototype"): InstallCaptureResult {
406
+ const current = target.custom;
407
+ if (typeof current !== "function") {
408
+ return { armed: false, target: "none", outcome: "no-custom" };
409
+ }
410
+
411
+ // Own-property check plus function identity: an inherited marker describes the prototype's
412
+ // function, not this instance's, so it must never certify this target.
413
+ if (Object.hasOwn(target, CAPTURE_WRAPPED) && target[CAPTURE_WRAPPED] === current) {
414
+ return { armed: false, target: shape, outcome: "already-armed" };
415
+ }
416
+
417
+ const callHost = current as HostCustom;
418
+ // SAFETY: `current` is verified callable above, and the host's `custom` is documented to
419
+ // resolve its factory to a component (or a promise of one) — architecture.md §3. The bridge
420
+ // never inspects the result, it only forwards it, so the return type is not a claim about its
421
+ // shape.
422
+
423
+ const generation = captureState().generation;
424
+ const wrapper = function (this: unknown, ...args: unknown[]): HostCustomResult {
425
+ const state = captureState();
426
+ const factory = args[0];
427
+ const rest = args.slice(1);
428
+ // A wrapper retained by foreign code after a disable must never capture or inject again; it
429
+ // behaves exactly like the host's own method.
430
+ if (state.generation !== generation || typeof factory !== "function") {
431
+ return callHost.apply(this, args as [unknown, ...unknown[]]);
432
+ }
433
+ return callHost.apply(this, [createCaptureFactory(factory as HostFactory), ...rest]);
434
+ };
435
+
436
+ target.custom = wrapper;
437
+ Object.defineProperty(target, CAPTURE_WRAPPED, {
438
+ value: wrapper,
439
+ enumerable: false,
440
+ configurable: true,
441
+ });
442
+ const state = captureState();
443
+ const previous = state.wrappers.findIndex((record) => record.target === target);
444
+ if (previous === -1) state.armedTargets += 1;
445
+ else state.wrappers.splice(previous, 1);
446
+ state.wrappers.push({ target, original: current, wrapper });
447
+ return { armed: true, target: shape, outcome: "armed" };
448
+ }
449
+
450
+ /**
451
+ * Disable every capture wrapper, restoring the host's own `custom` on the exact targets that were
452
+ * wrapped. Used when a different backend becomes active, so one menu cannot receive two copies of
453
+ * the bridge's rows.
454
+ */
455
+ export function disableCaptureBackend(): number {
456
+ const state = captureState();
457
+ let restored = 0;
458
+ for (const record of state.wrappers.splice(0)) {
459
+ try {
460
+ if (record.target.custom === record.wrapper) record.target.custom = record.original;
461
+ if (Object.hasOwn(record.target, CAPTURE_WRAPPED)) delete record.target[CAPTURE_WRAPPED];
462
+ restored += 1;
463
+ } catch {
464
+ // A host object that refuses the assignment keeps its wrapper; the backend is still off.
465
+ }
466
+ }
467
+ state.armedTargets = 0;
468
+ state.generation += 1;
469
+ return restored;
470
+ }
471
+
472
+ /** Wrap exactly one factory invocation, attributing every mapped array to its own session. */
473
+ function createCaptureFactory(factory: HostFactory): HostFactory {
474
+ return (ui, theme, ...rest) => {
475
+ const state = captureState();
476
+ const outermost = state.sessions.length === 0;
477
+ const session: CaptureSession = {
478
+ candidates: [],
479
+ proven: [],
480
+ theme,
481
+ injecting: false,
482
+ proving: false,
483
+ extendedCardStyle: false,
484
+ };
485
+ state.sessions.push(session);
486
+ state.nestingDepth = state.sessions.length;
487
+ // The probe wraps the FACTORY INVOCATION, so a host that calls the factory in a later
488
+ // microtask still runs under it. A factory that returns a promise is handled below.
489
+ if (outermost) installProbe();
490
+
491
+ let component: HostCustomResult;
492
+ let failed = true;
493
+ try {
494
+ component = factory(ui, theme, ...rest);
495
+ failed = false;
496
+ } catch (error) {
497
+ // Nothing was injected into this session: say so rather than leaving the previous outcome.
498
+ state.lastOutcome = {
499
+ kind: "uncaptured",
500
+ injectedRows: 0,
501
+ reason: "factory-threw",
502
+ };
503
+ throw error;
504
+ } finally {
505
+ // A throw leaves no trace (JD-A-004): the early rows and the marker come out of the array in
506
+ // the SAME `finally` that restores `Array.prototype.map`. Only this session's own array is
507
+ // touched, so an inner factory's rollback can never reach the outer session's rows.
508
+ // The stack and the patched `map` are restored FIRST and unconditionally (E10), so nothing the
509
+ // rollback does can leave either installed. `rollbackEarly` never throws.
510
+ state.sessions.pop();
511
+ state.nestingDepth = state.sessions.length;
512
+ if (outermost) removeProbe();
513
+ if (failed) {
514
+ rollbackEarly(session);
515
+ state.lastFailures = [];
516
+ }
517
+ }
518
+ resolveSession(session, component);
519
+ return component;
520
+ };
521
+ }
522
+
523
+ /**
524
+ * Decide what this session's candidates mean and inject once. Never injects into an array it did
525
+ * not capture, and never reports `injected` for a menu that received nothing.
526
+ *
527
+ * S20: this is also where the provisional early injection is reconciled. The early step is a guess;
528
+ * this function is the decision, so it either keeps the guess (same array, sync factory) or takes
529
+ * it back before applying the previous behaviour exactly.
530
+ */
531
+ function resolveSession(session: CaptureSession, component: HostCustomResult): void {
532
+ const state = captureState();
533
+
534
+ // The host may resolve its factory asynchronously (`interactive-mode.ts:3136`). This backend only
535
+ // observes the synchronous shape, so the promise is returned untouched, the early rows are taken
536
+ // back (JD-A-005: no late decision will ever run for them) and the outcome is the previous one.
537
+ if (isThenable(component)) {
538
+ rollbackEarly(session);
539
+ state.lastFailures = [];
540
+ state.lastOutcome = { kind: "uncaptured", injectedRows: 0, reason: "async-factory" };
541
+ return;
542
+ }
543
+
544
+ const picked = pickLateTarget(session);
545
+ if (picked.kind === "none") {
546
+ // No array can be named, or several can (the ambiguity rule). Either way the guess is undone
547
+ // first, so the net guarantee holds whatever the report says.
548
+ rollbackEarly(session);
549
+ state.lastFailures = [];
550
+ state.lastOutcome = { kind: "uncaptured", injectedRows: 0, reason: picked.reason };
551
+ return;
552
+ }
553
+ const captured = picked.array;
554
+ const early = session.earlyInjection;
555
+
556
+ // The early path put the rows in before the view read its page list (S18) and the late decision
557
+ // agrees: report that build and do not build a second time, so the providers run once.
558
+ if (early !== undefined && early.array === captured) {
559
+ state.lastFailures = early.failures;
560
+ state.lastOutcome = { kind: "injected", injectedRows: early.rows.length };
561
+ invalidate(component);
562
+ return;
563
+ }
564
+
565
+ // The guess did not survive the decision (another array, or several arrays proved themselves):
566
+ // remove every trace of it before the late path runs.
567
+ rollbackEarly(session);
568
+
569
+ if (Object.hasOwn(captured, CAPTURE_INJECTED)) {
570
+ state.lastOutcome = { kind: "already-injected", injectedRows: 0 };
571
+ return;
572
+ }
573
+ // Non-enumerable marker on the array: the same menu built twice injects once.
574
+ Object.defineProperty(captured as object, CAPTURE_INJECTED, {
575
+ value: true,
576
+ enumerable: false,
577
+ configurable: true,
578
+ });
579
+
580
+ // S1: the host's own `Card style` line is extended IN PLACE here, before the providers' rows are
581
+ // appended — the one moment the array is reachable, and the only place the two could be confused.
582
+ // It never throws: an unreachable line records the `separate` mode and leaves the fallback
583
+ // provider to draw the bridge's own line on this same build. The early path extends the same line
584
+ // at the same point in the array's life; the splice is not idempotent, so only one of them runs.
585
+ if (!session.extendedCardStyle) {
586
+ session.extendedCardStyle = true;
587
+ extendCardStyleLine(captured);
588
+ }
589
+
590
+ const built = buildRows(createRowContext(session.theme));
591
+ state.lastFailures = built.failures;
592
+ if (built.rows.length > 0) captured.push(...built.rows);
593
+ state.lastOutcome = { kind: "injected", injectedRows: built.rows.length };
594
+
595
+ invalidate(component);
596
+ }
597
+
598
+ /** What the late decision chose: one array, or nothing with the reason to report. */
599
+ type LatePick =
600
+ | { kind: "pick"; array: CustomizeRow[] }
601
+ | { kind: "none"; reason: "no-capture" | "ambiguous" };
602
+
603
+ /**
604
+ * The late decision: which array this factory's rows belong in, if any.
605
+ *
606
+ * The rule is the previous one — one row-like candidate is the menu, none means nothing was
607
+ * captured, several are ambiguous and nothing is injected — with one refinement S18 needs: when
608
+ * exactly ONE candidate proved itself the menu's rows at a `map` call (S20's proof), that array is
609
+ * the menu by evidence, so a merely row-LIKE array mapped beside it does not make the target
610
+ * ambiguous. Two proven arrays are ambiguous, and so are two unproven ones: the bridge still never
611
+ * guesses between two arrays that both look like the menu.
612
+ */
613
+ function pickLateTarget(session: CaptureSession): LatePick {
614
+ if (session.proven.length === 1) {
615
+ const proven = session.proven[0];
616
+ if (proven !== undefined) return { kind: "pick", array: proven };
617
+ }
618
+ if (session.proven.length > 1) return { kind: "none", reason: "ambiguous" };
619
+ if (session.candidates.length === 0) return { kind: "none", reason: "no-capture" };
620
+ if (session.candidates.length > 1) return { kind: "none", reason: "ambiguous" };
621
+ const only = session.candidates[0];
622
+ if (only === undefined) return { kind: "none", reason: "no-capture" };
623
+ return { kind: "pick", array: only };
624
+ }
625
+
626
+ /**
627
+ * Take a provisional injection back out, exactly.
628
+ *
629
+ * Three things were written and all three are undone in place, on the SAME array object the host
630
+ * holds: the providers' rows (by identity, at the index they were appended to), the `Card style`
631
+ * values the provisional splice inserted into the host's own line, and the injection marker. If the
632
+ * host itself moved those elements the rollback leaves them alone rather than guessing — but the
633
+ * marker still comes off, so nothing is left claiming this array was served.
634
+ */
635
+ function rollbackEarly(session: CaptureSession): void {
636
+ const early = session.earlyInjection;
637
+ if (early === undefined) return;
638
+ session.earlyInjection = undefined;
639
+ const { array } = early;
640
+
641
+ // Every step is best effort and none may throw (E10): the host can freeze, seal or proxy its array
642
+ // between our push and this rollback, and a rollback that threw would replace the host's own error
643
+ // and skip the steps after it. An array we cannot restore is left as the host made it.
644
+ try {
645
+ if (early.rows.length > 0 && array.length >= early.start + early.rows.length) {
646
+ let intact = true;
647
+ for (let index = 0; index < early.rows.length; index++) {
648
+ if (array[early.start + index] !== early.rows[index]) {
649
+ intact = false;
650
+ break;
651
+ }
652
+ }
653
+ if (intact) array.splice(early.start, early.rows.length);
654
+ }
655
+ } catch {
656
+ // frozen, sealed or exotic: nothing more can be taken back from this array
657
+ }
658
+ try {
659
+ undoCardStyleSplice(array, early.cardStyle);
660
+ } catch {
661
+ // same: the host's own line stays as the host left it
662
+ }
663
+ // The late path may now extend the line of the array IT picks; the splice runs once per build.
664
+ session.extendedCardStyle = false;
665
+ Reflect.deleteProperty(array as object, CAPTURE_INJECTED);
666
+ }
667
+
668
+ /**
669
+ * Observe one `map` call on a row-like array (S18, S20).
670
+ *
671
+ * The proof runs on EVERY call — never latched to the first one, because the host may map its rows
672
+ * to labels before the constructor maps them to categories (JD-A-002). An array that proves itself
673
+ * is remembered as such, and the provisional push happens at most once per build.
674
+ */
675
+ function observeRowMap(
676
+ session: CaptureSession,
677
+ array: CustomizeRow[],
678
+ callback: unknown,
679
+ thisArg: unknown,
680
+ ): void {
681
+ // Reentrancy: building the rows itself maps row-like arrays (a provider's own array, a nested
682
+ // menu's), and those maps belong to the build, not to the host's menu. A mapper that itself maps
683
+ // is the same case: the callback is proved once, and its own maps prove nothing.
684
+ if (session.injecting || session.proving) return;
685
+ session.proving = true;
686
+ let proven: boolean;
687
+ try {
688
+ proven = provesCategoryMap(array, callback, thisArg);
689
+ } finally {
690
+ session.proving = false;
691
+ }
692
+ if (!proven) return;
693
+ if (!session.proven.includes(array)) session.proven.push(array);
694
+ injectProvisionalRows(session, array, callback, thisArg);
695
+ }
696
+
697
+ /**
698
+ * S18: give a brand-new page to the view before it fixes its page list — provisionally (S20).
699
+ *
700
+ * The view computes `categories` once, in its constructor, from `options.rows.map(...)`
701
+ * (`lib/visual-customize-view.ts:387`). A row that joins an EXISTING page is visible after a late
702
+ * push because `categoryRows()` filters `options.rows` live (`:391-393`); a row naming a NEW page
703
+ * is not, because nothing can select a page the list does not hold. So the rows must be in the
704
+ * array before that `map` reads it.
705
+ *
706
+ * Everything here is recorded so `rollbackEarly` can undo it: the append index, the rows by
707
+ * identity, and the `Card style` splice. The mapper is also run over the rows about to be appended,
708
+ * before they are pushed, so the host's own `map` can never throw because of a bridge row
709
+ * (JD-A-003) — if it would, nothing is appended and the late path behaves exactly as before.
710
+ */
711
+ function injectProvisionalRows(
712
+ session: CaptureSession,
713
+ array: CustomizeRow[],
714
+ callback: unknown,
715
+ thisArg: unknown,
716
+ ): void {
717
+ // One injection per build, and a menu built twice already received its rows.
718
+ if (session.earlyInjection !== undefined) return;
719
+ if (Object.hasOwn(array, CAPTURE_INJECTED)) return;
720
+
721
+ session.injecting = true;
722
+ const state = captureState();
723
+ let cardStyle: EarlyCardStyleSplice | undefined;
724
+ try {
725
+ // S1, same ordering as the late path: the host's own line is extended before the providers'
726
+ // rows are appended (the fallback provider's contribution depends on that order). The splice is
727
+ // NOT idempotent, so it happens once per menu build.
728
+ if (!session.extendedCardStyle) {
729
+ session.extendedCardStyle = true;
730
+ cardStyle = extendCardStyleProvisional(array);
731
+ }
732
+ const built = buildRows(createRowContext(session.theme));
733
+ if (built.rows.length > 0 && !provesAppendedRows(callback, thisArg, array, built.rows)) {
734
+ // The host's own `map` would meet a row it cannot derive a page for. Nothing is pushed: the
735
+ // splice goes back too, and the late path handles this array exactly as it did before S18.
736
+ undoCardStyleSplice(array, cardStyle);
737
+ session.extendedCardStyle = false;
738
+ return;
739
+ }
740
+ const start = array.length;
741
+ if (built.rows.length > 0) array.push(...built.rows);
742
+ Object.defineProperty(array as object, CAPTURE_INJECTED, {
743
+ value: true,
744
+ enumerable: false,
745
+ configurable: true,
746
+ });
747
+ const injection: EarlyInjection = {
748
+ array,
749
+ start,
750
+ rows: built.rows,
751
+ failures: built.failures,
752
+ };
753
+ if (cardStyle !== undefined) injection.cardStyle = cardStyle;
754
+ session.earlyInjection = injection;
755
+ state.lastFailures = built.failures;
756
+ } catch {
757
+ // The provider build isolates its own failures, so reaching this means the array refused the
758
+ // edit. Nothing of the provisional step stays behind.
759
+ undoCardStyleSplice(array, cardStyle);
760
+ session.extendedCardStyle = false;
761
+ } finally {
762
+ session.injecting = false;
763
+ }
764
+ }
765
+
766
+ /**
767
+ * Extend the host's `Card style` line in place, remembering the splice so a rollback can undo it.
768
+ * Returns `undefined` when nothing was written (no line, nothing registered, or a refusing array).
769
+ */
770
+ function extendCardStyleProvisional(array: CustomizeRow[]): EarlyCardStyleSplice | undefined {
771
+ const line = findCardStyleLine(array);
772
+ const original = line === undefined ? [] : array.slice(line.start, line.start + line.count);
773
+ const before = array.length;
774
+ extendCardStyleLine(array);
775
+ const values = array.length - before;
776
+ if (line === undefined || values <= 0) return undefined;
777
+ return { start: line.start, hostCount: line.count, values, original };
778
+ }
779
+
780
+ /** Put the host's own rows back where the provisional splice replaced them. */
781
+ function undoCardStyleSplice(array: CustomizeRow[], splice: EarlyCardStyleSplice | undefined): void {
782
+ if (splice === undefined) return;
783
+ const total = splice.hostCount + splice.values;
784
+ if (array.length < splice.start + total) return;
785
+ array.splice(splice.start, total, ...splice.original);
786
+ }
787
+
788
+ /**
789
+ * The proof that qualifies an array for the early injection (S20).
790
+ *
791
+ * The host's own mapper is run exactly as `Array.prototype.map` would run it — same `this`, element,
792
+ * index and array, and nothing else — over:
793
+ *
794
+ * 1. the array's own elements, each required to derive that element's `category ?? "Settings"`
795
+ * (the view's page derivation, `lib/visual-customize-view.ts:387`);
796
+ * 2. two synthetic rows the host never had, required to derive `"Settings"` for the one with no
797
+ * category and its own unique page for the one naming the sentinel. This is what a mapper that
798
+ * merely echoes what it is given, or ignores it, can never do;
799
+ * 3. never a throw: a mapper that throws on any of those rows is simply not proven, so the host's
800
+ * own call keeps its own behaviour and nothing is mutated.
801
+ *
802
+ * Nothing here mutates, runs a provider, or forwards anything to the host.
803
+ */
804
+ function provesCategoryMap(
805
+ array: readonly CustomizeRow[],
806
+ callback: unknown,
807
+ thisArg: unknown,
808
+ ): boolean {
809
+ if (typeof callback !== "function") return false;
810
+ const mapper = callback as CategoryMapper;
811
+ try {
812
+ for (let index = 0; index < array.length; index++) {
813
+ const row = array[index];
814
+ if (mapper.call(thisArg, row, index, array) !== expectedCategory(row)) return false;
815
+ }
816
+ for (let index = 0; index < SYNTHETIC_PROOF_ROWS.length; index++) {
817
+ const row = SYNTHETIC_PROOF_ROWS[index];
818
+ if (mapper.call(thisArg, row, index, SYNTHETIC_PROOF_ROWS) !== expectedCategory(row)) {
819
+ return false;
820
+ }
821
+ }
822
+ return true;
823
+ } catch {
824
+ return false;
825
+ }
826
+ }
827
+
828
+ /**
829
+ * The same mapper, run over the rows this injection is about to append — BEFORE they are pushed, so
830
+ * a mapper that throws on a bridge row (or that would put one in the wrong page) never meets one in
831
+ * the host's own `map` call (JD-A-003).
832
+ *
833
+ * The index is the one the row will have in the host's array, and the third argument is the live
834
+ * array itself: it is the same object the host will map, one row shorter at this point.
835
+ */
836
+ function provesAppendedRows(
837
+ callback: unknown,
838
+ thisArg: unknown,
839
+ array: readonly CustomizeRow[],
840
+ rows: readonly CustomizeRow[],
841
+ ): boolean {
842
+ if (typeof callback !== "function") return false;
843
+ const mapper = callback as CategoryMapper;
844
+ try {
845
+ for (let index = 0; index < rows.length; index++) {
846
+ const row = rows[index];
847
+ if (mapper.call(thisArg, row, array.length + index, array) !== expectedCategory(row)) {
848
+ return false;
849
+ }
850
+ }
851
+ return true;
852
+ } catch {
853
+ return false;
854
+ }
855
+ }
856
+
857
+ /** The page the view would derive for a row: `row.category ?? "Settings"` (`:387`). */
858
+ function expectedCategory(row: CustomizeRow): string {
859
+ return row.category ?? HOST_DEFAULT_CATEGORY;
860
+ }
861
+
862
+ /**
863
+ * Row-like means: an array of at least three objects that each expose a callable `action`.
864
+ * Deliberately allocation-free and `map`-free, because it runs while `Array.prototype.map` is
865
+ * patched.
866
+ */
867
+ function isRowLikeArray(value: unknown): value is CustomizeRow[] {
868
+ if (!Array.isArray(value) || value.length < MIN_ROW_ARRAY_LENGTH) return false;
869
+ for (const element of value) {
870
+ if (element === null || typeof element !== "object") return false;
871
+ const action = (element as { action?: unknown }).action;
872
+ if (typeof action !== "function") return false;
873
+ }
874
+ return true;
875
+ }
876
+
877
+ function invalidate(component: HostCustomResult): void {
878
+ if (component === null || typeof component !== "object") return;
879
+ const invalidateFn = (component as HostComponent).invalidate;
880
+ if (typeof invalidateFn === "function") invalidateFn.call(component);
881
+ }
882
+
883
+ function isThenable(value: unknown): value is PromiseLike<unknown> {
884
+ if (value === null || (typeof value !== "object" && typeof value !== "function")) return false;
885
+ return typeof (value as { then?: unknown }).then === "function";
886
+ }