@cogcoin/client 0.5.0

package/dist/bitcoind/progress/quote-scene.js

@@ -0,0 +1,137 @@
+import { loadArtTemplate } from "./assets.js";
+import { MAX_QUOTE_LINES, MESSAGE_FIELD_ROW, NEUTRAL_MESSAGE_TITLE, SCROLL_WINDOW_HEIGHT, SCROLL_WINDOW_TOP, SCROLL_WINDOW_WIDTH, STATUS_FIELD_ROW, } from "./constants.js";
+import { centerLine, computeCenteredLeftPadding, normalizeInlineText, overlayCenteredField, positionLine, replaceWindowSegment, truncateLine, } from "./formatting.js";
+import { renderIntroFrame } from "./train-scene.js";
+function consumeWrappedLine(text, capacity) {
+    const remaining = text.trimStart();
+    if (remaining.length <= capacity) {
+        return {
+            line: remaining,
+            remaining: "",
+        };
+    }
+    const candidate = remaining.slice(0, capacity + 1);
+    const breakIndex = candidate.lastIndexOf(" ");
+    if (breakIndex > 0) {
+        return {
+            line: remaining.slice(0, breakIndex).trimEnd(),
+            remaining: remaining.slice(breakIndex + 1).trimStart(),
+        };
+    }
+    return {
+        line: remaining.slice(0, capacity),
+        remaining: remaining.slice(capacity).trimStart(),
+    };
+}
+function wrapTextToCapacities(text, capacities) {
+    let remaining = normalizeInlineText(text);
+    const lines = [];
+    for (const capacity of capacities) {
+        if (remaining.length === 0) {
+            break;
+        }
+        const wrapped = consumeWrappedLine(remaining, capacity);
+        lines.push(wrapped.line);
+        remaining = wrapped.remaining;
+    }
+    return { lines, remaining };
+}
+function decorateWrappedQuote(lines, truncated) {
+    const decorated = [...lines];
+    const lastIndex = decorated.length - 1;
+    decorated[0] = `"${decorated[0]}`;
+    decorated[lastIndex] = truncated
+        ? `${decorated[lastIndex]}\u2026"`
+        : `${decorated[lastIndex]}"`;
+    return decorated;
+}
+function wrapQuoteText(text) {
+    const normalized = normalizeInlineText(text);
+    if (normalized.length === 0) {
+        return {
+            lines: ["\"\""],
+            truncated: false,
+        };
+    }
+    for (let lineCount = 1; lineCount <= MAX_QUOTE_LINES; lineCount += 1) {
+        const capacities = lineCount === 1
+            ? [SCROLL_WINDOW_WIDTH - 2]
+            : [
+                SCROLL_WINDOW_WIDTH - 1,
+                ...Array.from({ length: Math.max(0, lineCount - 2) }, () => SCROLL_WINDOW_WIDTH),
+                SCROLL_WINDOW_WIDTH - 1,
+            ];
+        const wrapped = wrapTextToCapacities(normalized, capacities);
+        if (wrapped.remaining.length === 0) {
+            return {
+                lines: decorateWrappedQuote(wrapped.lines, false),
+                truncated: false,
+            };
+        }
+    }
+    const prefixCapacities = [
+        SCROLL_WINDOW_WIDTH - 1,
+        ...Array.from({ length: MAX_QUOTE_LINES - 2 }, () => SCROLL_WINDOW_WIDTH),
+    ];
+    const wrapped = wrapTextToCapacities(normalized, prefixCapacities);
+    const lastLine = consumeWrappedLine(wrapped.remaining, SCROLL_WINDOW_WIDTH - 2).line;
+    return {
+        lines: decorateWrappedQuote([...wrapped.lines, lastLine], true),
+        truncated: true,
+    };
+}
+function buildQuoteWindowLines(quoteLines) {
+    if (quoteLines.length <= 1) {
+        return quoteLines.map((line) => centerLine(line, SCROLL_WINDOW_WIDTH));
+    }
+    const centeredPaddings = quoteLines.map((line) => computeCenteredLeftPadding(line, SCROLL_WINDOW_WIDTH));
+    const lastLine = truncateLine(quoteLines[quoteLines.length - 1] ?? "", SCROLL_WINDOW_WIDTH);
+    const maxLastPadding = Math.max(0, SCROLL_WINDOW_WIDTH - lastLine.length);
+    const anchoredLastPadding = centeredPaddings
+        .slice(0, -1)
+        .sort((left, right) => left - right)
+        .find((padding) => padding <= maxLastPadding)
+        ?? computeCenteredLeftPadding(lastLine, SCROLL_WINDOW_WIDTH);
+    return quoteLines.map((line, index) => {
+        if (index === quoteLines.length - 1) {
+            return positionLine(line, SCROLL_WINDOW_WIDTH, anchoredLastPadding);
+        }
+        return centerLine(line, SCROLL_WINDOW_WIDTH);
+    });
+}
+function buildScrollWindow(quote) {
+    const lines = Array.from({ length: SCROLL_WINDOW_HEIGHT }, () => " ".repeat(SCROLL_WINDOW_WIDTH));
+    if (quote === null) {
+        return lines;
+    }
+    const wrappedQuote = wrapQuoteText(quote.quote);
+    const byline = truncateLine(`- ${normalizeInlineText(quote.author)}`, SCROLL_WINDOW_WIDTH);
+    const quoteWindowLines = buildQuoteWindowLines(wrappedQuote.lines);
+    const block = [...quoteWindowLines, " ".repeat(SCROLL_WINDOW_WIDTH), centerLine(byline, SCROLL_WINDOW_WIDTH)];
+    const topPadding = Math.max(0, Math.ceil((SCROLL_WINDOW_HEIGHT - block.length) / 2));
+    for (const [index, line] of block.entries()) {
+        const targetRow = topPadding + index;
+        if (targetRow >= SCROLL_WINDOW_HEIGHT) {
+            break;
+        }
+        lines[targetRow] = line;
+    }
+    return lines;
+}
+export function renderArtFrame(displayPhase, quote, statusFieldText, introElapsedMs = 0) {
+    if (displayPhase === "banner") {
+        return renderIntroFrame(introElapsedMs, statusFieldText);
+    }
+    const frame = [...loadArtTemplate("scroll")];
+    const windowLines = buildScrollWindow(quote);
+    for (const [rowOffset, windowLine] of windowLines.entries()) {
+        const rowIndex = SCROLL_WINDOW_TOP + rowOffset;
+        frame[rowIndex] = replaceWindowSegment(frame[rowIndex] ?? "", windowLine);
+    }
+    overlayCenteredField(frame, MESSAGE_FIELD_ROW, NEUTRAL_MESSAGE_TITLE);
+    overlayCenteredField(frame, STATUS_FIELD_ROW, statusFieldText);
+    return frame;
+}
+export function renderArtFrameForTesting(displayPhase, quote, statusFieldText = "", introElapsedMs = 0) {
+    return renderArtFrame(displayPhase, quote, statusFieldText, introElapsedMs);
+}

package/dist/bitcoind/progress/train-scene.d.ts

@@ -0,0 +1,9 @@
+export type TrainSceneKind = "intro" | "completion";
+export declare function resolveTrainSceneMessage(kind: TrainSceneKind, elapsedMs: number): string;
+export declare function resolveIntroMessageForTesting(introElapsedMs: number): string;
+export declare function resolveCompletionMessageForTesting(completionElapsedMs: number): string;
+export declare function renderTrainSceneFrame(kind: TrainSceneKind, elapsedMs: number, statusFieldText: string): string[];
+export declare function renderIntroFrame(introElapsedMs: number, statusFieldText: string): string[];
+export declare function renderCompletionFrame(completionElapsedMs: number, statusFieldText: string): string[];
+export declare function renderIntroFrameForTesting(introElapsedMs: number, statusFieldText?: string): string[];
+export declare function renderCompletionFrameForTesting(completionElapsedMs: number, statusFieldText?: string): string[];

package/dist/bitcoind/progress/train-scene.js

@@ -0,0 +1,92 @@
+import { INTRO_ENTRY_MS, INTRO_EXIT_MS, INTRO_PAUSE_MS, INTRO_TOTAL_MS, MESSAGE_FIELD_ROW, NEUTRAL_MESSAGE_TITLE, SCROLL_WINDOW_LEFT, STATUS_FIELD_ROW, TRAIN_CENTER_X, TRAIN_CLIP_MAX_COLUMN, TRAIN_CLIP_MIN_COLUMN, TRAIN_OFFSCREEN_LEFT_X, TRAIN_OFFSCREEN_RIGHT_X, TRAIN_SPRITE_TOP, } from "./constants.js";
+import { loadArtTemplate, loadSprite } from "./assets.js";
+import { overlayCenteredField } from "./formatting.js";
+export function resolveTrainSceneMessage(kind, elapsedMs) {
+    if (elapsedMs < INTRO_ENTRY_MS) {
+        return kind === "intro"
+            ? "Here comes the mining train!"
+            : "Congratuations, you are synced!";
+    }
+    if (elapsedMs < INTRO_ENTRY_MS + INTRO_PAUSE_MS) {
+        return kind === "intro"
+            ? "Welcome to Cogcoin!"
+            : "You shape your own future.";
+    }
+    if (elapsedMs < INTRO_TOTAL_MS) {
+        return kind === "intro"
+            ? "How many sentences will you mine?"
+            : "Your Cogcoin story begins...";
+    }
+    return "";
+}
+export function resolveIntroMessageForTesting(introElapsedMs) {
+    return resolveTrainSceneMessage("intro", introElapsedMs);
+}
+export function resolveCompletionMessageForTesting(completionElapsedMs) {
+    return resolveTrainSceneMessage("completion", completionElapsedMs);
+}
+function resolveIntroSpriteName(introElapsedMs) {
+    if (introElapsedMs >= INTRO_ENTRY_MS && introElapsedMs < INTRO_ENTRY_MS + INTRO_PAUSE_MS) {
+        return "train";
+    }
+    return "train-smoke";
+}
+function resolveIntroSpriteX(introElapsedMs) {
+    if (introElapsedMs <= 0) {
+        return TRAIN_OFFSCREEN_RIGHT_X;
+    }
+    if (introElapsedMs < INTRO_ENTRY_MS) {
+        const progress = introElapsedMs / INTRO_ENTRY_MS;
+        return Math.round(TRAIN_OFFSCREEN_RIGHT_X + ((TRAIN_CENTER_X - TRAIN_OFFSCREEN_RIGHT_X) * progress));
+    }
+    if (introElapsedMs < INTRO_ENTRY_MS + INTRO_PAUSE_MS) {
+        return TRAIN_CENTER_X;
+    }
+    if (introElapsedMs < INTRO_TOTAL_MS) {
+        const progress = (introElapsedMs - INTRO_ENTRY_MS - INTRO_PAUSE_MS) / INTRO_EXIT_MS;
+        return Math.round(TRAIN_CENTER_X + ((TRAIN_OFFSCREEN_LEFT_X - TRAIN_CENTER_X) * progress));
+    }
+    return TRAIN_OFFSCREEN_LEFT_X;
+}
+function overlaySpriteOnFrame(frame, sprite, spriteX) {
+    const rows = frame.map((line) => [...line]);
+    for (const [rowOffset, spriteLine] of sprite.entries()) {
+        const targetRow = TRAIN_SPRITE_TOP + rowOffset;
+        const targetChars = rows[targetRow];
+        if (targetChars === undefined) {
+            continue;
+        }
+        for (const [columnOffset, character] of [...spriteLine].entries()) {
+            const targetColumn = spriteX + columnOffset;
+            if (character === " "
+                || targetColumn < TRAIN_CLIP_MIN_COLUMN
+                || targetColumn > TRAIN_CLIP_MAX_COLUMN) {
+                continue;
+            }
+            targetChars[SCROLL_WINDOW_LEFT + targetColumn] = character;
+        }
+    }
+    return rows.map((chars) => chars.join(""));
+}
+export function renderTrainSceneFrame(kind, elapsedMs, statusFieldText) {
+    const frame = [...loadArtTemplate("scroll")];
+    const introFrame = elapsedMs >= INTRO_TOTAL_MS
+        ? frame
+        : overlaySpriteOnFrame(frame, loadSprite(resolveIntroSpriteName(elapsedMs)), resolveIntroSpriteX(elapsedMs));
+    const message = resolveTrainSceneMessage(kind, elapsedMs);
+    overlayCenteredField(introFrame, MESSAGE_FIELD_ROW, message.length > 0 ? message : NEUTRAL_MESSAGE_TITLE);
+    overlayCenteredField(introFrame, STATUS_FIELD_ROW, statusFieldText);
+    return introFrame;
+}
+export function renderIntroFrame(introElapsedMs, statusFieldText) {
+    return renderTrainSceneFrame("intro", introElapsedMs, statusFieldText);
+}
+export function renderCompletionFrame(completionElapsedMs, statusFieldText) {
+    return renderTrainSceneFrame("completion", completionElapsedMs, statusFieldText);
+}
+export function renderIntroFrameForTesting(introElapsedMs, statusFieldText = "") {
+    return renderIntroFrame(introElapsedMs, statusFieldText);
+}
+export function renderCompletionFrameForTesting(completionElapsedMs, statusFieldText = "") {
+    return renderCompletionFrame(completionElapsedMs, statusFieldText);
+}

package/dist/bitcoind/progress/tty-renderer.d.ts

@@ -0,0 +1,18 @@
+import type { QuoteDisplayPhase } from "../quotes.js";
+import type { BootstrapProgress, WritingQuote } from "../types.js";
+import type { FollowSceneStateForTesting } from "./follow-scene.js";
+import { type TrainSceneKind } from "./train-scene.js";
+interface RenderStream {
+    isTTY?: boolean;
+    columns?: number;
+    write(chunk: string): boolean | void;
+}
+export declare class TtyProgressRenderer {
+    #private;
+    constructor(stream?: RenderStream);
+    render(displayPhase: QuoteDisplayPhase, quote: WritingQuote | null, progress: BootstrapProgress, cogcoinSyncHeight: number | null, cogcoinSyncTargetHeight: number | null, introElapsedMs?: number, statusFieldText?: string): void;
+    renderTrainScene(kind: TrainSceneKind, progress: BootstrapProgress, cogcoinSyncHeight: number | null, cogcoinSyncTargetHeight: number | null, elapsedMs: number, statusFieldText?: string): void;
+    renderFollowScene(progress: BootstrapProgress, cogcoinSyncHeight: number | null, cogcoinSyncTargetHeight: number | null, followScene: FollowSceneStateForTesting, statusFieldText?: string): void;
+    close(): void;
+}
+export {};

package/dist/bitcoind/progress/tty-renderer.js

@@ -0,0 +1,150 @@
+import { ART_WIDTH, INTRO_TOTAL_MS, NEUTRAL_MESSAGE_TITLE } from "./constants.js";
+import { renderFollowFrame } from "./follow-scene.js";
+import { formatProgressLine, formatQuoteLine, truncateLine } from "./formatting.js";
+import { renderArtFrame } from "./quote-scene.js";
+import { renderTrainSceneFrame, resolveTrainSceneMessage } from "./train-scene.js";
+const STREAM_WRITE_OBSERVERS = new WeakMap();
+function getStreamWriteObserver(stream) {
+    const existing = STREAM_WRITE_OBSERVERS.get(stream);
+    if (existing !== undefined) {
+        existing.refCount += 1;
+        return existing;
+    }
+    const observer = {
+        externalWriteCount: 0,
+        internalWriteDepth: 0,
+        refCount: 1,
+        originalWrite: stream.write,
+    };
+    stream.write = ((chunk) => {
+        if (observer.internalWriteDepth === 0) {
+            observer.externalWriteCount += 1;
+        }
+        const result = observer.originalWrite.call(stream, chunk);
+        return result ?? true;
+    });
+    STREAM_WRITE_OBSERVERS.set(stream, observer);
+    return observer;
+}
+function releaseStreamWriteObserver(stream, observer) {
+    observer.refCount -= 1;
+    if (observer.refCount > 0) {
+        return;
+    }
+    stream.write = observer.originalWrite;
+    STREAM_WRITE_OBSERVERS.delete(stream);
+}
+export class TtyProgressRenderer {
+    #stream;
+    #streamWriteObserver;
+    #rendered = false;
+    #observerReleased = false;
+    #lastExternalWriteCount = 0;
+    #previousFrameHeight = 0;
+    constructor(stream = process.stderr) {
+        this.#stream = stream;
+        this.#streamWriteObserver = getStreamWriteObserver(stream);
+        this.#lastExternalWriteCount = this.#streamWriteObserver.externalWriteCount;
+    }
+    render(displayPhase, quote, progress, cogcoinSyncHeight, cogcoinSyncTargetHeight, introElapsedMs = 0, statusFieldText = "") {
+        const now = Date.now();
+        const width = Math.max(20, this.#stream.columns ?? 120);
+        const progressLine = formatProgressLine(progress, cogcoinSyncHeight, cogcoinSyncTargetHeight, width, now);
+        const lines = width >= ART_WIDTH
+            ? [...renderArtFrame(displayPhase, quote, statusFieldText, introElapsedMs), "", progressLine, ""]
+            : [formatQuoteLine(quote, width), progressLine, ""];
+        const frame = lines.join("\n");
+        this.#resetFrameIfExternalWritesDetected();
+        if (!this.#rendered) {
+            this.#writeChunk(frame);
+            this.#rendered = true;
+            this.#previousFrameHeight = lines.length;
+            return;
+        }
+        this.#writeChunk(this.#clearPreviousFrame());
+        this.#writeChunk(frame);
+        this.#previousFrameHeight = lines.length;
+    }
+    renderTrainScene(kind, progress, cogcoinSyncHeight, cogcoinSyncTargetHeight, elapsedMs, statusFieldText = "") {
+        const now = Date.now();
+        const width = Math.max(20, this.#stream.columns ?? 120);
+        const progressLine = formatProgressLine(progress, cogcoinSyncHeight, cogcoinSyncTargetHeight, width, now);
+        const sceneMessage = resolveTrainSceneMessage(kind, elapsedMs);
+        const lines = width >= ART_WIDTH
+            ? [...renderTrainSceneFrame(kind, elapsedMs, statusFieldText), "", progressLine, ""]
+            : [truncateLine(sceneMessage, width), progressLine, ""];
+        const frame = lines.join("\n");
+        this.#resetFrameIfExternalWritesDetected();
+        if (!this.#rendered) {
+            this.#writeChunk(frame);
+            this.#rendered = true;
+            this.#previousFrameHeight = lines.length;
+            return;
+        }
+        this.#writeChunk(this.#clearPreviousFrame());
+        this.#writeChunk(frame);
+        this.#previousFrameHeight = lines.length;
+    }
+    renderFollowScene(progress, cogcoinSyncHeight, cogcoinSyncTargetHeight, followScene, statusFieldText = "") {
+        const now = Date.now();
+        const width = Math.max(20, this.#stream.columns ?? 120);
+        const progressLine = formatProgressLine(progress, cogcoinSyncHeight, cogcoinSyncTargetHeight, width, now);
+        const lines = width >= ART_WIDTH
+            ? [...renderFollowFrame(followScene, statusFieldText, now), "", progressLine, ""]
+            : [truncateLine(NEUTRAL_MESSAGE_TITLE, width), progressLine, ""];
+        const frame = lines.join("\n");
+        this.#resetFrameIfExternalWritesDetected();
+        if (!this.#rendered) {
+            this.#writeChunk(frame);
+            this.#rendered = true;
+            this.#previousFrameHeight = lines.length;
+            return;
+        }
+        this.#writeChunk(this.#clearPreviousFrame());
+        this.#writeChunk(frame);
+        this.#previousFrameHeight = lines.length;
+    }
+    close() {
+        if (this.#rendered) {
+            this.#writeChunk("\n");
+            this.#rendered = false;
+            this.#previousFrameHeight = 0;
+        }
+        if (this.#observerReleased) {
+            return;
+        }
+        releaseStreamWriteObserver(this.#stream, this.#streamWriteObserver);
+        this.#observerReleased = true;
+    }
+    #writeChunk(chunk) {
+        this.#streamWriteObserver.internalWriteDepth += 1;
+        try {
+            this.#stream.write(chunk);
+        }
+        finally {
+            this.#streamWriteObserver.internalWriteDepth = Math.max(0, this.#streamWriteObserver.internalWriteDepth - 1);
+            this.#lastExternalWriteCount = this.#streamWriteObserver.externalWriteCount;
+        }
+    }
+    #resetFrameIfExternalWritesDetected() {
+        if (!this.#rendered) {
+            return;
+        }
+        if (this.#streamWriteObserver.externalWriteCount === this.#lastExternalWriteCount) {
+            return;
+        }
+        this.#rendered = false;
+        this.#previousFrameHeight = 0;
+        this.#lastExternalWriteCount = this.#streamWriteObserver.externalWriteCount;
+    }
+    #clearPreviousFrame() {
+        let clear = "";
+        for (let index = 0; index < this.#previousFrameHeight; index += 1) {
+            clear += "\r\u001B[2K";
+            if (index < this.#previousFrameHeight - 1) {
+                clear += "\u001B[1A";
+            }
+        }
+        return clear;
+    }
+}

package/dist/bitcoind/progress.d.ts

@@ -0,0 +1,7 @@
+export { ManagedProgressController } from "./progress/controller.js";
+export { type FollowAnimation, type FollowAnimationKind, type FollowSceneStateForTesting, advanceFollowSceneStateForTesting, createFollowSceneStateForTesting, formatCompactFollowAgeLabelForTesting, renderFollowFrameForTesting, setFollowBlockTimeForTesting, setFollowBlockTimesForTesting, syncFollowSceneStateForTesting, } from "./progress/follow-scene.js";
+export { createBootstrapProgressForTesting, formatProgressLineForTesting, formatQuoteLineForTesting, resolveStatusFieldTextForTesting, } from "./progress/formatting.js";
+export { renderArtFrameForTesting } from "./progress/quote-scene.js";
+export { renderCompletionFrameForTesting, renderIntroFrameForTesting, resolveCompletionMessageForTesting, resolveIntroMessageForTesting, } from "./progress/train-scene.js";
+export { TtyProgressRenderer } from "./progress/tty-renderer.js";
+export { loadBannerArtForTesting, loadScrollArtForTesting, loadTrainArtForTesting, loadTrainCarArtForTesting, loadTrainSmokeArtForTesting, } from "./progress/assets.js";

package/dist/bitcoind/progress.js

@@ -0,0 +1,7 @@
+export { ManagedProgressController } from "./progress/controller.js";
+export { advanceFollowSceneStateForTesting, createFollowSceneStateForTesting, formatCompactFollowAgeLabelForTesting, renderFollowFrameForTesting, setFollowBlockTimeForTesting, setFollowBlockTimesForTesting, syncFollowSceneStateForTesting, } from "./progress/follow-scene.js";
+export { createBootstrapProgressForTesting, formatProgressLineForTesting, formatQuoteLineForTesting, resolveStatusFieldTextForTesting, } from "./progress/formatting.js";
+export { renderArtFrameForTesting } from "./progress/quote-scene.js";
+export { renderCompletionFrameForTesting, renderIntroFrameForTesting, resolveCompletionMessageForTesting, resolveIntroMessageForTesting, } from "./progress/train-scene.js";
+export { TtyProgressRenderer } from "./progress/tty-renderer.js";
+export { loadBannerArtForTesting, loadScrollArtForTesting, loadTrainArtForTesting, loadTrainCarArtForTesting, loadTrainSmokeArtForTesting, } from "./progress/assets.js";

package/dist/bitcoind/quotes.d.ts

@@ -0,0 +1,24 @@
+import type { WritingQuote } from "./types.js";
+export type QuoteDisplayPhase = "banner" | "scroll";
+export interface QuoteStateSnapshot {
+    currentQuote: WritingQuote;
+    completedCycles: number;
+    index: number;
+    permutation: number[];
+    displayPhase: QuoteDisplayPhase;
+    displayStartedAt: number;
+    quoteStartedAt: number;
+}
+export declare function shuffleIndicesForTesting(length: number, random?: () => number): number[];
+export declare function loadWritingQuotesForTesting(): Promise<{
+    datasetHash: string;
+    quotes: WritingQuote[];
+}>;
+export declare class WritingQuoteRotator {
+    #private;
+    private constructor();
+    static create(statePath: string, random?: () => number): Promise<WritingQuoteRotator>;
+    current(now?: number): Promise<QuoteStateSnapshot>;
+    forceAdvance(now?: number): Promise<QuoteStateSnapshot>;
+    getPersistedStateForTesting(): Promise<QuoteStateSnapshot>;
+}

package/dist/bitcoind/quotes.js

@@ -0,0 +1,195 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+const BANNER_DISPLAY_MS = 15_000;
+const QUOTE_ROTATION_MS = 7_000;
+async function writeJsonAtomic(path, payload) {
+    await mkdir(dirname(path), { recursive: true });
+    const tempPath = `${path}.tmp`;
+    await writeFile(tempPath, JSON.stringify(payload, null, 2));
+    await rename(tempPath, path);
+}
+function isPermutation(indices, length) {
+    if (indices.length !== length) {
+        return false;
+    }
+    const seen = new Set(indices);
+    if (seen.size !== length) {
+        return false;
+    }
+    for (let index = 0; index < length; index += 1) {
+        if (!seen.has(index)) {
+            return false;
+        }
+    }
+    return true;
+}
+export function shuffleIndicesForTesting(length, random = Math.random) {
+    const indices = Array.from({ length }, (_value, index) => index);
+    for (let index = indices.length - 1; index > 0; index -= 1) {
+        const swapIndex = Math.floor(random() * (index + 1));
+        [indices[index], indices[swapIndex]] = [indices[swapIndex] ?? 0, indices[index] ?? 0];
+    }
+    return indices;
+}
+async function loadWritingQuotes() {
+    const raw = await readFile(new URL("../writing_quotes.json", import.meta.url));
+    const datasetHash = createHash("sha256").update(raw).digest("hex");
+    const quotes = JSON.parse(raw.toString("utf8"));
+    if (!Array.isArray(quotes) || quotes.length === 0) {
+        throw new Error("writing_quotes_invalid");
+    }
+    return { datasetHash, quotes };
+}
+export async function loadWritingQuotesForTesting() {
+    return loadWritingQuotes();
+}
+export class WritingQuoteRotator {
+    #quotes;
+    #datasetHash;
+    #statePath;
+    #random;
+    #state;
+    #queue = Promise.resolve();
+    constructor(quotes, datasetHash, statePath, random, state) {
+        this.#quotes = quotes;
+        this.#datasetHash = datasetHash;
+        this.#statePath = statePath;
+        this.#random = random;
+        this.#state = state;
+    }
+    static async create(statePath, random = Math.random) {
+        const { datasetHash, quotes } = await loadWritingQuotes();
+        const state = await WritingQuoteRotator.#loadState(statePath, quotes.length, datasetHash, random);
+        return new WritingQuoteRotator(quotes, datasetHash, statePath, random, state);
+    }
+    async current(now = Date.now()) {
+        await this.#advanceIfNeeded(now);
+        return this.#snapshot(now);
+    }
+    async forceAdvance(now = Date.now()) {
+        await this.#enqueue(async () => {
+            this.#advanceState(now, 1);
+            await writeJsonAtomic(this.#statePath, this.#state);
+        });
+        return this.#snapshot(now);
+    }
+    async getPersistedStateForTesting() {
+        return this.current(Date.now());
+    }
+    async #advanceIfNeeded(now) {
+        await this.#enqueue(async () => {
+            const elapsed = Math.max(0, now - this.#state.quoteStartedAt);
+            const steps = Math.floor(elapsed / QUOTE_ROTATION_MS);
+            if (steps <= 0) {
+                return;
+            }
+            this.#advanceState(now, steps);
+            await writeJsonAtomic(this.#statePath, this.#state);
+        });
+    }
+    #advanceState(now, steps) {
+        let remaining = steps;
+        while (remaining > 0) {
+            const nextIndex = this.#state.index + 1;
+            if (nextIndex < this.#state.permutation.length) {
+                this.#state.index = nextIndex;
+            }
+            else {
+                this.#state.completedCycles += 1;
+                this.#state.permutation = shuffleIndicesForTesting(this.#quotes.length, this.#random);
+                this.#state.index = 0;
+            }
+            this.#state.quoteStartedAt += QUOTE_ROTATION_MS;
+            remaining -= 1;
+        }
+        if (now > this.#state.quoteStartedAt + QUOTE_ROTATION_MS) {
+            this.#state.quoteStartedAt = now - ((now - this.#state.quoteStartedAt) % QUOTE_ROTATION_MS);
+        }
+        this.#state.updatedAt = now;
+    }
+    static #advanceLoadedState(state, quoteCount, random, now) {
+        let remaining = Math.floor(Math.max(0, now - state.quoteStartedAt) / QUOTE_ROTATION_MS);
+        while (remaining > 0) {
+            const nextIndex = state.index + 1;
+            if (nextIndex < state.permutation.length) {
+                state.index = nextIndex;
+            }
+            else {
+                state.completedCycles += 1;
+                state.permutation = shuffleIndicesForTesting(quoteCount, random);
+                state.index = 0;
+            }
+            state.quoteStartedAt += QUOTE_ROTATION_MS;
+            remaining -= 1;
+        }
+        if (now > state.quoteStartedAt + QUOTE_ROTATION_MS) {
+            state.quoteStartedAt = now - ((now - state.quoteStartedAt) % QUOTE_ROTATION_MS);
+        }
+        state.updatedAt = now;
+    }
+    #snapshot(now) {
+        const quoteIndex = this.#state.permutation[this.#state.index] ?? 0;
+        return {
+            currentQuote: this.#quotes[quoteIndex] ?? this.#quotes[0],
+            completedCycles: this.#state.completedCycles,
+            index: this.#state.index,
+            permutation: [...this.#state.permutation],
+            displayPhase: now < this.#state.displayStartedAt + BANNER_DISPLAY_MS ? "banner" : "scroll",
+            displayStartedAt: this.#state.displayStartedAt,
+            quoteStartedAt: this.#state.quoteStartedAt,
+        };
+    }
+    async #enqueue(fn) {
+        const resultPromise = this.#queue.then(fn, fn);
+        this.#queue = resultPromise.then(() => undefined, () => undefined);
+        return resultPromise;
+    }
+    static async #loadState(statePath, quoteCount, datasetHash, random) {
+        const now = Date.now();
+        try {
+            const raw = await readFile(statePath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed.datasetHash === datasetHash
+                && Array.isArray(parsed.permutation)
+                && isPermutation(parsed.permutation, quoteCount)
+                && typeof parsed.index === "number"
+                && parsed.index >= 0
+                && parsed.index < parsed.permutation.length
+                && typeof parsed.quoteStartedAt === "number"
+                && typeof parsed.completedCycles === "number") {
+                const state = {
+                    datasetHash,
+                    permutation: parsed.permutation,
+                    index: parsed.index,
+                    displayStartedAt: typeof parsed.displayStartedAt === "number"
+                        ? parsed.displayStartedAt
+                        : parsed.quoteStartedAt - BANNER_DISPLAY_MS,
+                    quoteStartedAt: parsed.quoteStartedAt,
+                    completedCycles: parsed.completedCycles,
+                    updatedAt: typeof parsed.updatedAt === "number" ? parsed.updatedAt : now,
+                };
+                WritingQuoteRotator.#advanceLoadedState(state, quoteCount, random, now);
+                state.displayStartedAt = now;
+                state.quoteStartedAt = now + BANNER_DISPLAY_MS;
+                state.updatedAt = now;
+                await writeJsonAtomic(statePath, state);
+                return state;
+            }
+        }
+        catch {
+            // Fall back to a fresh randomized cycle.
+        }
+        const state = {
+            datasetHash,
+            permutation: shuffleIndicesForTesting(quoteCount, random),
+            index: 0,
+            displayStartedAt: now,
+            quoteStartedAt: now + BANNER_DISPLAY_MS,
+            completedCycles: 0,
+            updatedAt: now,
+        };
+        await writeJsonAtomic(statePath, state);
+        return state;
+    }
+}