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.
- package/.codegraph/.gitignore +5 -0
- package/PRD.md +144 -0
- package/README.md +745 -2
- package/docs/architecture.md +981 -0
- package/docs/contract.md +1266 -0
- package/docs/state.md +251 -0
- package/examples/bash-card.ts +1694 -0
- package/gentle-shell-bridge-0.3.0.tgz +0 -0
- package/odd/tasks/palette-sections.md +30 -0
- package/odd/tasks/plugin-keymap.md +32 -0
- package/odd/tasks/plugin-surface-contract.md +55 -0
- package/package.json +35 -4
- package/src/api.ts +492 -0
- package/src/arm.ts +83 -0
- package/src/bus.ts +558 -0
- package/src/capture.ts +886 -0
- package/src/card-style-line.ts +112 -0
- package/src/card-style-rows.ts +390 -0
- package/src/card-style-transform.ts +862 -0
- package/src/card-style-wiring.ts +472 -0
- package/src/card-styles.ts +159 -0
- package/src/config.ts +71 -0
- package/src/extension.ts +271 -0
- package/src/hook.ts +310 -0
- package/src/index.ts +71 -0
- package/src/notices.ts +137 -0
- package/src/plugin-lines.ts +865 -0
- package/src/plugin-surface.ts +218 -0
- package/src/presence.ts +259 -0
- package/src/repaint.ts +351 -0
- package/src/row-labels.ts +146 -0
- package/src/row-names.ts +273 -0
- package/src/row-origin.ts +144 -0
- package/src/rows.ts +248 -0
- package/src/section-panel.ts +378 -0
- package/src/section-pointer.ts +164 -0
- package/src/sections-rows.ts +128 -0
- package/src/sidebar-render.ts +535 -0
- package/src/sidebar.ts +919 -0
- package/src/status.ts +1161 -0
- package/src/store.ts +279 -0
- package/src/tool-design-adoption.ts +263 -0
- package/src/tool-design-rows.ts +246 -0
- package/src/tool-design-wiring.ts +428 -0
- package/src/tool-designs.ts +402 -0
- package/src/transform-pipeline.ts +351 -0
- package/src/types.ts +442 -0
- package/src/visibility.ts +154 -0
- package/test/api.test.ts +395 -0
- package/test/apply-on-move.test.ts +477 -0
- package/test/arm.test.ts +220 -0
- package/test/bridge-ready.test.ts +309 -0
- package/test/bus.test.ts +165 -0
- package/test/button-rows.test.ts +409 -0
- package/test/capture.test.ts +356 -0
- package/test/card-style-rows.test.ts +510 -0
- package/test/card-style-transform.test.ts +379 -0
- package/test/card-style-wiring.test.ts +258 -0
- package/test/card-styles-e2e.test.ts +491 -0
- package/test/card-styles.test.ts +324 -0
- package/test/card-transcript-path.test.ts +178 -0
- package/test/config.test.ts +93 -0
- package/test/e2e.test.ts +443 -0
- package/test/example-bash-identity.test.ts +372 -0
- package/test/example-bash-matrix.test.ts +856 -0
- package/test/example-designs.test.ts +734 -0
- package/test/example-neon-transform.test.ts +283 -0
- package/test/example-plain-style.test.ts +1268 -0
- package/test/extension.test.ts +160 -0
- package/test/fake-events.ts +58 -0
- package/test/fake-host.ts +211 -0
- package/test/fake-sidebar.ts +516 -0
- package/test/fake-transcript.ts +486 -0
- package/test/frame-telemetry.test.ts +417 -0
- package/test/hook.test.ts +196 -0
- package/test/manifest.test.ts +105 -0
- package/test/new-category.test.ts +979 -0
- package/test/notices.test.ts +328 -0
- package/test/plugin-integration-lines.test.ts +979 -0
- package/test/plugin-surface.test.ts +152 -0
- package/test/presence.test.ts +459 -0
- package/test/rail-surfaces.test.ts +457 -0
- package/test/rail-width.test.ts +423 -0
- package/test/regression.test.ts +483 -0
- package/test/repaint-api.test.ts +200 -0
- package/test/reserved-categories.test.ts +361 -0
- package/test/row-labels.test.ts +284 -0
- package/test/row-names.test.ts +473 -0
- package/test/row-origin.test.ts +395 -0
- package/test/section-interaction.test.ts +364 -0
- package/test/section-panel.test.ts +403 -0
- package/test/sections-rows.test.ts +291 -0
- package/test/sidebar-backend.test.ts +471 -0
- package/test/sidebar-e2e.test.ts +331 -0
- package/test/sidebar-hover.test.ts +276 -0
- package/test/sidebar-independent.test.ts +349 -0
- package/test/sidebar-render.test.ts +281 -0
- package/test/sidebar-sections.test.ts +245 -0
- package/test/status-card-styles.test.ts +201 -0
- package/test/status-section-frame.test.ts +181 -0
- package/test/status-sections.test.ts +243 -0
- package/test/status.test.ts +209 -0
- package/test/store.test.ts +192 -0
- package/test/surface-repaint-cost.test.ts +520 -0
- package/test/tool-design-chain.test.ts +483 -0
- package/test/tool-design-cost.test.ts +473 -0
- package/test/tool-design-rows.test.ts +359 -0
- package/test/tool-designs.test.ts +745 -0
- package/test/transform-pipeline.test.ts +465 -0
- package/test/transforms-bus.test.ts +233 -0
- package/test/verifier-width-regressions.test.ts +164 -0
- 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
|
+
}
|