@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

package/dist/app/session-shell/prompt-history-controller.js

@@ -0,0 +1,170 @@
+import { randomUUID } from "node:crypto";
+import { PROMPT_HISTORY_MAX_TEXT_BYTES } from "../../contracts/owned-ui/index.js";
+/** Merges bounded recall snapshots; the editor alone owns browsing, draft, cursor, and undo state. */
+export class PromptHistoryController {
+    #local = new Map();
+    #unsubscribe;
+    #snapshot;
+    #fallback;
+    #rehydrateCache;
+    #disposed = false;
+    #generation = 0;
+    #unsubscribeSnapshot;
+    #unsubscribeFailure;
+    #closeFailed = false;
+    #closePromise;
+    options;
+    constructor(options) {
+        this.options = options;
+        if (options.editor.recall === undefined)
+            throw new Error("The selected editor does not expose typed history");
+        this.#snapshot = { revision: 0, limit: options.limit, entries: [] };
+        this.#rehydrateCache = new Map();
+        this.#fallback = boundedTexts([...options.fallback].reverse(), options.limit);
+        this.#unsubscribeSnapshot = this.#subscribeSnapshot();
+        this.#unsubscribeFailure = options.store.onFailure(() => {
+            if (this.#disposed)
+                this.#closeFailed = true;
+        });
+        this.#unsubscribe = [
+            options.editor.recall.observe(() => {
+                if (this.#disposed)
+                    return;
+                if (options.editor.recall.position().index === -1)
+                    this.synchronize();
+                options.store.refresh();
+            }),
+        ];
+        this.synchronize();
+    }
+    start() { this.options.store.start(); }
+    capture(text, kind, cwd, sessionId) {
+        const canonical = text.trim();
+        if (!canonical || this.#disposed)
+            return;
+        const id = randomUUID();
+        const generation = this.#generation;
+        this.#local.set(id, { text: canonical, committed: false });
+        this.#boundLocal();
+        this.synchronize();
+        void this.options.store.record({ id, text: canonical, timestamp: Date.now(), kind, cwd, sessionId }).then(outcome => {
+            if (this.#disposed || generation !== this.#generation)
+                return;
+            const local = this.#local.get(id);
+            if (local === undefined || outcome !== "committed")
+                return;
+            local.committed = true;
+            if (this.#snapshot.entries.some(entry => entry.submissionId === id))
+                this.#local.delete(id);
+            this.synchronize();
+        }).catch(() => { });
+    }
+    rememberRecovery(text) {
+        if (this.#disposed || !text.trim())
+            return;
+        const canonical = text.trim();
+        if ([...this.#local.values()].some(item => item.text === canonical)
+            || this.#snapshot.entries.some(item => item.text === canonical))
+            return;
+        this.#local.set(randomUUID(), { text: canonical, committed: false });
+        this.#boundLocal();
+        this.synchronize();
+    }
+    synchronize() {
+        if (this.#disposed || !this.options.active())
+            return;
+        const local = [...this.#local.values()].reverse().map(item => item.text);
+        const saved = this.#snapshot.entries.map(item => item.text);
+        const values = this.#rehydrateAll(local.concat(saved, this.#fallback));
+        this.options.editor.recall.replace(boundedTexts(values, this.#snapshot.limit));
+        this.options.render();
+    }
+    #rehydrateAll(values) {
+        const rehydrate = this.options.rehydrate;
+        if (rehydrate === undefined)
+            return [...values];
+        const cache = this.#rehydrateCache;
+        const results = [];
+        for (const value of values) {
+            const cached = cache.get(value);
+            if (cached !== undefined) {
+                results.push(cached);
+                continue;
+            }
+            const rendered = rehydrate(value);
+            cache.set(value, rendered);
+            results.push(rendered);
+        }
+        if (cache.size > 512) {
+            // Performance: keep the cache bounded so long sessions cannot grow it without limit.
+            const keys = [...cache.keys()].slice(0, cache.size - 256);
+            for (const key of keys)
+                cache.delete(key);
+        }
+        return results;
+    }
+    reset(fallback) {
+        this.#generation++;
+        this.#unsubscribeSnapshot();
+        this.#unsubscribeSnapshot = this.#subscribeSnapshot();
+        this.#fallback = boundedTexts([...fallback].reverse(), this.options.limit);
+        this.#local.clear();
+        this.#rehydrateCache.clear();
+        this.options.editor.recall.reset();
+        this.synchronize();
+        this.options.store.refresh();
+    }
+    close() {
+        if (this.#closePromise !== undefined)
+            return this.#closePromise;
+        this.#disposed = true;
+        this.#unsubscribeSnapshot();
+        for (const unsubscribe of this.#unsubscribe)
+            unsubscribe();
+        this.#local.clear();
+        this.#fallback = [];
+        this.#closePromise = this.options.store.close().then(() => !this.#closeFailed, () => false)
+            .finally(() => this.#unsubscribeFailure());
+        return this.#closePromise;
+    }
+    #subscribeSnapshot() {
+        const generation = this.#generation;
+        return this.options.store.onSnapshot(snapshot => {
+            if (this.#disposed || generation !== this.#generation || snapshot.revision < this.#snapshot.revision)
+                return;
+            this.#snapshot = snapshot;
+            for (const [id, entry] of this.#local) {
+                if (entry.committed || snapshot.entries.some(saved => saved.submissionId === id))
+                    this.#local.delete(id);
+            }
+            this.synchronize();
+        });
+    }
+    #boundLocal() {
+        let bytes = [...this.#local.values()].reduce((sum, item) => sum + Buffer.byteLength(item.text), 0);
+        while (this.#local.size > this.options.limit || bytes > PROMPT_HISTORY_MAX_TEXT_BYTES) {
+            const id = this.#local.keys().next().value;
+            bytes -= Buffer.byteLength(this.#local.get(id).text);
+            this.#local.delete(id);
+        }
+    }
+}
+function boundedTexts(values, limit) {
+    const result = [];
+    const seen = new Set();
+    let bytes = 0;
+    for (const value of values) {
+        const text = value.trim();
+        if (!text || seen.has(text))
+            continue;
+        const size = Buffer.byteLength(text);
+        if (bytes + size > PROMPT_HISTORY_MAX_TEXT_BYTES)
+            continue;
+        result.push(text);
+        seen.add(text);
+        bytes += size;
+        if (result.length >= limit)
+            break;
+    }
+    return result;
+}

package/dist/app/session-shell/prompt-suggestion-controller.d.ts

@@ -0,0 +1,35 @@
+import { type OwnedUiPromptSuggestionGeneratorPort, type OwnedUiPromptSuggestionIdentity, type OwnedUiPromptSuggestionState, type SuggestionDecision, type SuggestionDecisionReason, type SuggestionDiagnosticObserver } from "../../contracts/owned-ui/index.js";
+export interface ContextualPromptSuggestionSurface {
+    canPresent(identity: OwnedUiPromptSuggestionIdentity): boolean;
+    presentationBlockReason?(identity: OwnedUiPromptSuggestionIdentity): SuggestionDecision;
+    present(text: string): boolean;
+    clear(): void;
+    requestRender(): void;
+}
+export interface ContextualPromptSuggestionControllerOptions {
+    readonly generator: OwnedUiPromptSuggestionGeneratorPort;
+    readonly surface: ContextualPromptSuggestionSurface;
+    readonly enabled: boolean;
+    readonly timeoutMs?: number;
+    readonly diagnostics?: SuggestionDiagnosticObserver;
+    readonly now?: () => number;
+}
+type DecisionIdentity = Omit<OwnedUiPromptSuggestionIdentity, "model"> & {
+    readonly model: OwnedUiPromptSuggestionIdentity["model"] | null;
+};
+/** Prefetches one inert candidate; owns retirement even when a provider ignores abort. */
+export declare class ContextualPromptSuggestionController {
+    #private;
+    readonly options: ContextualPromptSuggestionControllerOptions;
+    constructor(options: ContextualPromptSuggestionControllerOptions);
+    get state(): OwnedUiPromptSuggestionState;
+    setEnabled(enabled: boolean): void;
+    skip(identity: DecisionIdentity, reason: SuggestionDecisionReason): void;
+    consider(identity: OwnedUiPromptSuggestionIdentity, decision: boolean | SuggestionDecision): void;
+    settle(identity: OwnedUiPromptSuggestionIdentity): void;
+    accept(): void;
+    invalidate(): void;
+    dispose(): void;
+}
+export declare function samePromptSuggestionIdentity(left: OwnedUiPromptSuggestionIdentity, right: OwnedUiPromptSuggestionIdentity): boolean;
+export {};

package/dist/app/session-shell/prompt-suggestion-controller.js

@@ -0,0 +1,207 @@
+import { assertOwnedUiPromptSuggestionResult, normalizePromptSuggestionCandidate, } from "../../contracts/owned-ui/index.js";
+/** Prefetches one inert candidate; owns retirement even when a provider ignores abort. */
+export class ContextualPromptSuggestionController {
+    #state = { status: "idle" };
+    #request = null;
+    #lastConsidered = "";
+    #enabled;
+    #disposed = false;
+    #sessionKey = "";
+    #sessionSequence = 0;
+    #requestSequence = 0;
+    #timeoutMs;
+    #now;
+    options;
+    constructor(options) {
+        this.options = options;
+        this.#enabled = options.enabled;
+        this.#timeoutMs = options.timeoutMs ?? 15_000;
+        this.#now = options.now ?? Date.now;
+    }
+    get state() { return this.#state; }
+    setEnabled(enabled) {
+        if (this.#enabled === enabled)
+            return;
+        this.#enabled = enabled;
+        this.invalidate();
+    }
+    skip(identity, reason) {
+        this.invalidate();
+        this.#emit(this.#metadata(identity), "skipped", reason);
+    }
+    consider(identity, decision) {
+        const key = identityKey(identity);
+        if (key === this.#lastConsidered)
+            return;
+        this.#lastConsidered = key;
+        this.invalidate();
+        const reason = this.#disposed ? "disposed" : !this.#enabled ? "disabled"
+            : decision === false ? "ineligible" : decision === true ? null : decision;
+        if (reason !== null) {
+            this.#emit(this.#metadata(identity), "skipped", reason);
+            return;
+        }
+        let reasoning = "unavailable";
+        try {
+            reasoning = this.options.generator.suggestionReasoningPolicy?.() ?? "unavailable";
+        }
+        catch { /* Security: isolate diagnostic metadata failure. */ }
+        const request = {
+            identity,
+            metadata: { ...this.#metadata(identity), request: ++this.#requestSequence, reasoning },
+            abort: new AbortController(), startedAt: this.#now(), terminal: false,
+        };
+        this.#request = request;
+        this.#state = { status: "generating", identity, settled: false };
+        this.#emit(request.metadata, "started");
+        request.timer = setTimeout(() => {
+            if (this.#request !== request || this.#state.status !== "generating")
+                return;
+            this.#finish(request, "timeout");
+            this.#state = { status: "idle" };
+            this.#request = null;
+            request.abort.abort();
+        }, this.#timeoutMs);
+        request.timer.unref?.();
+        try {
+            void this.options.generator.generate({ identity, signal: request.abort.signal })
+                .then(result => this.#receive(request, result), () => this.#failed(request))
+                .finally(() => clearTimeout(request.timer));
+        }
+        catch {
+            this.#failed(request);
+        }
+    }
+    settle(identity) {
+        if (this.#disposed || !this.#enabled || this.#state.status === "idle")
+            return;
+        if (!samePromptSuggestionIdentity(this.#state.identity, identity)) {
+            if (this.#request)
+                this.#finish(this.#request, "stale-result", "stale-identity");
+            this.invalidate();
+            return;
+        }
+        if (this.#state.status === "generating")
+            this.#state = { ...this.#state, settled: true };
+        else if (this.#state.status === "prepared" && this.#request)
+            this.#show(this.#request, this.#state.text);
+    }
+    accept() { this.#invalidate(false); }
+    invalidate() { this.#invalidate(true); }
+    dispose() {
+        this.#disposed = true;
+        this.invalidate();
+        this.#lastConsidered = "";
+        this.#sessionKey = "";
+    }
+    #invalidate(clearSurface) {
+        const hadVisibleSuggestion = this.#state.status === "available";
+        const request = this.#request;
+        if (request)
+            this.#finish(request, "cancelled");
+        this.#request = null;
+        this.#state = { status: "idle" };
+        request?.abort.abort();
+        if (clearSurface && hadVisibleSuggestion) {
+            this.options.surface.clear();
+            this.options.surface.requestRender();
+        }
+    }
+    #failed(request) {
+        if (this.#request !== request || request.terminal) {
+            this.#late(request);
+            return;
+        }
+        this.#finish(request, "provider-failure");
+        this.#request = null;
+        this.#state = { status: "idle" };
+    }
+    #receive(request, result) {
+        if (this.#disposed || this.#request !== request || request.terminal || this.#state.status !== "generating") {
+            this.#late(request);
+            return;
+        }
+        try {
+            assertOwnedUiPromptSuggestionResult(result);
+        }
+        catch {
+            this.#finish(request, "rejected");
+            this.invalidate();
+            return;
+        }
+        if (!samePromptSuggestionIdentity(request.identity, result.identity)) {
+            this.#finish(request, "stale-result", "stale-identity");
+            this.invalidate();
+            return;
+        }
+        if (result.outcome !== "candidate") {
+            this.#finish(request, result.outcome);
+            this.invalidate();
+            return;
+        }
+        const text = normalizePromptSuggestionCandidate(result.text);
+        if (text === null) {
+            this.#finish(request, "rejected");
+            this.invalidate();
+            return;
+        }
+        clearTimeout(request.timer);
+        if (this.#state.settled)
+            this.#show(request, text);
+        else
+            this.#state = { status: "prepared", identity: request.identity, text };
+    }
+    #show(request, text) {
+        const reason = this.options.surface.presentationBlockReason?.(request.identity)
+            ?? (this.options.surface.canPresent(request.identity) ? null : "presentation-unavailable");
+        if (reason !== null || !this.options.surface.present(text)) {
+            this.#finish(request, "presentation-blocked", reason ?? "presentation-unavailable");
+            this.invalidate();
+            return;
+        }
+        this.#state = { status: "available", identity: request.identity, text };
+        this.#finish(request, "displayed");
+        this.options.surface.requestRender();
+    }
+    #finish(request, event, reason) {
+        if (request.terminal)
+            return;
+        // Concurrency: retire before notifying observers or aborting; neither may rewrite the winner.
+        request.terminal = true;
+        clearTimeout(request.timer);
+        this.#emit({ ...request.metadata, elapsedMs: Math.max(0, this.#now() - request.startedAt) }, event, reason);
+    }
+    #late(request) {
+        if (!this.#disposed)
+            this.#emit({ ...request.metadata, elapsedMs: Math.max(0, this.#now() - request.startedAt) }, "late-result-discarded");
+    }
+    #metadata(identity) {
+        const key = `${identity.sessionId}\0${identity.sessionGeneration}`;
+        if (this.#sessionKey !== key) {
+            this.#sessionKey = key;
+            this.#sessionSequence++;
+        }
+        return {
+            event: "skipped", session: this.#sessionSequence, run: identity.runSequence, response: identity.responseSequence,
+            request: 0, provider: identity.model?.providerId ?? "", model: identity.model?.modelId ?? "",
+            reasoning: "unavailable", elapsedMs: 0,
+        };
+    }
+    #emit(metadata, event, reason) {
+        try {
+            this.options.diagnostics?.record({ ...metadata, event, ...(reason === undefined ? {} : { reason }) });
+        }
+        catch { /* Security: diagnostics never own input or lifecycle. */ }
+    }
+}
+export function samePromptSuggestionIdentity(left, right) {
+    return left.sessionId === right.sessionId
+        && left.sessionGeneration === right.sessionGeneration
+        && left.runSequence === right.runSequence
+        && left.responseSequence === right.responseSequence
+        && left.model.providerId === right.model.providerId
+        && left.model.modelId === right.model.modelId;
+}
+function identityKey(identity) {
+    return `${identity.sessionId}\0${identity.sessionGeneration}\0${identity.runSequence}\0${identity.responseSequence}\0${identity.model.providerId}\0${identity.model.modelId}`;
+}

package/dist/app/session-shell/quit-outro-effects.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Deterministic quit-outro effect plans, ported from the v2 sketch.
+ *
+ * Each effect turns the captured frame's per-row visible widths and a seed into
+ * two sorted schedules over unit playback progress: sparkles paint a glyph at a
+ * cell from `start`, and clears blank a cell at `end`. The player consumes both
+ * in order, so a fixed seed yields a byte-stable animation.
+ */
+export interface QuitOutroCell {
+    readonly row: number;
+    readonly col: number;
+    /** Progress at which the sparkle glyph is painted. */
+    readonly start: number;
+    /** Progress at which the cell is cleared. */
+    readonly end: number;
+    readonly glyph: string;
+    readonly color: string;
+}
+export interface QuitOutroPlan {
+    /** Sorted by `start`. */
+    readonly sparkles: readonly QuitOutroCell[];
+    /** Sorted by `end`. */
+    readonly clears: readonly QuitOutroCell[];
+}
+export declare const QUIT_OUTRO_EFFECTS: readonly ["fall", "dissolve", "starburst", "waves"];
+export type QuitOutroEffect = (typeof QUIT_OUTRO_EFFECTS)[number];
+export declare function isQuitOutroEffect(value: unknown): value is QuitOutroEffect;
+/** Builds the selected effect's deterministic plan for the captured row widths. */
+export declare function createQuitOutroPlan(effect: QuitOutroEffect, rowWidths: readonly number[], seed: number): QuitOutroPlan;

package/dist/app/session-shell/quit-outro-effects.js

@@ -0,0 +1,242 @@
+/**
+ * Deterministic quit-outro effect plans, ported from the v2 sketch.
+ *
+ * Each effect turns the captured frame's per-row visible widths and a seed into
+ * two sorted schedules over unit playback progress: sparkles paint a glyph at a
+ * cell from `start`, and clears blank a cell at `end`. The player consumes both
+ * in order, so a fixed seed yields a byte-stable animation.
+ */
+export const QUIT_OUTRO_EFFECTS = Object.freeze(["fall", "dissolve", "starburst", "waves"]);
+export function isQuitOutroEffect(value) {
+    return typeof value === "string" && QUIT_OUTRO_EFFECTS.includes(value);
+}
+const WHITE = "\x1b[38;2;238;238;238m";
+const DUST_GLYPHS = [".", "·", "'", ":", "+", "°"];
+const FALL_GLYPHS = [".", ".", "·", "'", ":", "°"];
+const GRAVITY = 85;
+function mulberry32(seed) {
+    let value = seed >>> 0;
+    return () => {
+        value = (value + 0x6d2b79f5) | 0;
+        let next = Math.imul(value ^ (value >>> 15), 1 | value);
+        next = (next + Math.imul(next ^ (next >>> 7), 61 | next)) ^ next;
+        return ((next ^ (next >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+function pick(random, values) {
+    return values[Math.floor(random() * values.length)];
+}
+function rowWidth(rowWidths, row) {
+    return Math.max(0, Math.floor(rowWidths[row] ?? 0));
+}
+function finish(sparkles, clears) {
+    sparkles.sort((a, b) => a.start - b.start);
+    clears.sort((a, b) => a.end - b.end);
+    return { sparkles, clears };
+}
+/** Calm white ASCII dust dissolve. */
+function dissolvePlan(rowWidths, seed) {
+    const random = mulberry32(seed);
+    const height = Math.max(1, rowWidths.length);
+    const width = Math.max(1, ...rowWidths);
+    const sparkles = [];
+    const clears = [];
+    for (let row = 0; row < rowWidths.length; row++) {
+        for (let col = 0; col < rowWidth(rowWidths, row); col++) {
+            const sweep = (row / height) * 0.14 + (col / width) * 0.08;
+            const start = Math.min(0.76, sweep + random() * 0.54);
+            const cell = {
+                row, col, start,
+                end: Math.min(0.96, start + 0.1 + random() * 0.1),
+                glyph: pick(random, DUST_GLYPHS),
+                color: WHITE,
+            };
+            clears.push(cell);
+            if (random() < 0.34)
+                sparkles.push(cell);
+        }
+    }
+    return finish(sparkles, clears);
+}
+/** Soft white harmonic ripple dissolve. */
+function starburstPlan(rowWidths, seed) {
+    const random = mulberry32(seed);
+    const height = Math.max(1, rowWidths.length);
+    const width = Math.max(1, ...rowWidths);
+    const center = (width - 1) / 2;
+    const sparkles = [];
+    const clears = [];
+    for (let row = 0; row < rowWidths.length; row++) {
+        for (let col = 0; col < rowWidth(rowWidths, row); col++) {
+            const distance = Math.abs(col - center) / Math.max(1, width / 2);
+            const ripple = (Math.sin(distance * Math.PI * 3 + (row / height) * Math.PI) + 1) * 0.035;
+            const sweep = distance * 0.2 + (row / height) * 0.1 + ripple;
+            const start = Math.min(0.79, sweep + random() * 0.34);
+            const cell = {
+                row, col, start,
+                end: Math.min(0.97, start + 0.12 + random() * 0.1),
+                glyph: pick(random, DUST_GLYPHS),
+                color: WHITE,
+            };
+            clears.push(cell);
+            if (random() < 0.38)
+                sparkles.push(cell);
+        }
+    }
+    return finish(sparkles, clears);
+}
+/** White dotted fragments accelerating downward and collecting in a floor pile. */
+function fallPlan(rowWidths, seed) {
+    const random = mulberry32(seed);
+    const height = Math.max(1, rowWidths.length);
+    const width = Math.max(1, ...rowWidths);
+    const floor = height - 1;
+    const area = Math.max(1, width * height);
+    const fragmentChance = clamp(150 / area, 0.1, 0.24);
+    const particles = [];
+    const sparkles = [];
+    const clears = [];
+    let fallbackParticle;
+    for (let row = 0; row < rowWidths.length; row++) {
+        for (let col = 0; col < rowWidth(rowWidths, row); col++) {
+            const release = 0.025 + random() * 0.13 + (1 - row / height) * 0.035;
+            const glyph = pick(random, FALL_GLYPHS);
+            clears.push({ row, col, start: release, end: release + 0.04, glyph, color: WHITE });
+            if (row >= floor)
+                continue;
+            const particle = { row, col, release, glyph, velocityCol: (random() - 0.5) * 9 };
+            fallbackParticle ??= particle;
+            if (random() < fragmentChance)
+                particles.push(particle);
+        }
+    }
+    if (particles.length === 0 && fallbackParticle)
+        particles.push(fallbackParticle);
+    const arrival = (particle) => particle.release + Math.sqrt((2 * (floor - particle.row)) / GRAVITY);
+    particles.sort((a, b) => arrival(a) - arrival(b));
+    const pileHeights = Array(width).fill(0);
+    for (const particle of particles) {
+        const floorFallTime = Math.max(0.05, Math.sqrt((2 * (floor - particle.row)) / GRAVITY));
+        const predictedCol = clamp(Math.round(particle.col + particle.velocityCol * floorFallTime), 0, width - 1);
+        let landingCol = predictedCol;
+        for (let radius = 1; radius <= 3; radius++) {
+            for (const candidate of [predictedCol - radius, predictedCol + radius]) {
+                if (candidate >= 0 && candidate < width && pileHeights[candidate] < pileHeights[landingCol])
+                    landingCol = candidate;
+            }
+        }
+        const stackHeight = pileHeights[landingCol]++;
+        const restingRow = clamp(floor - stackHeight, particle.row + 1, floor);
+        const fallDistance = Math.max(1, restingRow - particle.row);
+        const fallTime = Math.sqrt((2 * fallDistance) / GRAVITY);
+        const velocityCol = (landingCol - particle.col) / fallTime;
+        const steps = Math.max(4, Math.min(14, Math.ceil(fallTime / 0.045)));
+        const interval = fallTime / steps;
+        for (let step = 1; step < steps; step++) {
+            const elapsed = step * interval;
+            const progress = step / steps;
+            const row = particle.row + 0.5 * GRAVITY * elapsed * elapsed;
+            const col = particle.col + velocityCol * elapsed + Math.sin(progress * Math.PI) * 0.3;
+            const start = clamp(particle.release + elapsed, 0, 0.93);
+            const cell = {
+                row: clamp(Math.round(row), 0, floor),
+                col: clamp(Math.round(col), 0, width - 1),
+                start,
+                end: Math.min(0.96, start + Math.max(0.025, interval * 0.72)),
+                glyph: particle.glyph,
+                color: WHITE,
+            };
+            sparkles.push(cell);
+            clears.push(cell);
+        }
+        const settledAt = clamp(particle.release + fallTime, 0, 0.93);
+        const settled = { row: restingRow, col: landingCol, start: settledAt, end: 0.97, glyph: particle.glyph, color: WHITE };
+        sparkles.push(settled);
+        clears.push(settled);
+    }
+    return finish(sparkles, clears);
+}
+/** Soft white dotted radio pulses expanding from a gently moving center. */
+function wavesPlan(rowWidths, seed) {
+    const random = mulberry32(seed);
+    const height = Math.max(1, rowWidths.length);
+    const width = Math.max(1, ...rowWidths);
+    const baseCenterCol = (width - 1) / 2;
+    const baseCenterRow = (height - 1) / 2;
+    const sparkles = [];
+    const clears = [];
+    const addPulseCell = (row, col, start, lifetime, glyph) => {
+        const safeStart = clamp(start, 0, 0.94);
+        const cell = {
+            row: clamp(Math.round(row), 0, height - 1),
+            col: clamp(Math.round(col), 0, width - 1),
+            start: safeStart,
+            end: clamp(safeStart + lifetime, safeStart + 0.02, 0.98),
+            glyph,
+            color: WHITE,
+        };
+        sparkles.push(cell);
+        clears.push(cell);
+    };
+    // Rationale: clear the frame in the same outward direction as the expanding signal.
+    for (let row = 0; row < rowWidths.length; row++) {
+        for (let col = 0; col < rowWidth(rowWidths, row); col++) {
+            const x = (col - baseCenterCol) / Math.max(1, width * 0.5);
+            const y = (row - baseCenterRow) / Math.max(1, height * 0.5);
+            const distance = Math.min(1.25, Math.sqrt(x * x + y * y));
+            const start = 0.04 + random() * 0.1;
+            const cell = {
+                row, col, start,
+                end: Math.min(0.95, 0.18 + distance * 0.54 + random() * 0.12),
+                glyph: pick(random, DUST_GLYPHS),
+                color: WHITE,
+            };
+            clears.push(cell);
+            if (random() < 0.055)
+                sparkles.push(cell);
+        }
+    }
+    const pulseCount = 4;
+    const expansionSteps = 9;
+    for (let pulse = 0; pulse < pulseCount; pulse++) {
+        const pulseStart = 0.025 + pulse * 0.135;
+        const phase = pulse * 1.47 + random() * 0.45;
+        for (let step = 0; step <= expansionSteps; step++) {
+            const progress = step / expansionSteps;
+            const centerCol = baseCenterCol + Math.sin(phase + progress * Math.PI) * width * 0.035;
+            const centerRow = baseCenterRow + Math.cos(phase + progress * Math.PI * 0.8) * height * 0.065;
+            const radiusCol = progress * width * 0.56;
+            const radiusRow = progress * height * 0.56;
+            const samples = Math.max(10, Math.min(58, Math.round(12 + radiusCol * 0.48)));
+            const time = pulseStart + progress * 0.28;
+            if (step === 0) {
+                addPulseCell(centerRow, centerCol, time, 0.1, pulse % 2 === 0 ? "+" : "°");
+                continue;
+            }
+            for (let sample = 0; sample < samples; sample++) {
+                if (random() < 0.08 + progress * 0.06)
+                    continue;
+                const angle = (sample / samples) * Math.PI * 2 + Math.sin(phase) * 0.035;
+                const shimmer = (random() - 0.5) * (0.25 + progress * 0.55);
+                const row = centerRow + Math.sin(angle) * radiusRow + shimmer * 0.4;
+                const col = centerCol + Math.cos(angle) * radiusCol + shimmer;
+                const glyph = progress < 0.28 ? "°" : progress < 0.62 ? "·" : random() < 0.72 ? "." : "'";
+                addPulseCell(row, col, time + random() * 0.018, 0.065 + (1 - progress) * 0.055, glyph);
+            }
+        }
+    }
+    return finish(sparkles, clears);
+}
+const PLANS = Object.freeze({
+    fall: fallPlan,
+    dissolve: dissolvePlan,
+    starburst: starburstPlan,
+    waves: wavesPlan,
+});
+/** Builds the selected effect's deterministic plan for the captured row widths. */
+export function createQuitOutroPlan(effect, rowWidths, seed) {
+    return PLANS[effect](rowWidths, seed);
+}