@vincentt-xr/cli 0.1.5 → 0.3.0

package/dist/preview/copy.d.ts

@@ -0,0 +1,209 @@
+/** Flow L13 — the start block. */
+export interface StartBlockInput {
+    projectName: string;
+    orgName: string;
+    /** The forward target, printed BEFORE the URL so the 502 advisory matches it. */
+    targetUrl: string;
+    url: string;
+    /** Pre-rendered QR rows, or undefined for non-TTY / piped / --no-qr. */
+    qr?: string[];
+    expiresInHours: number;
+}
+export declare function startBlock(i: StartBlockInput): string[];
+/**
+ * Flow L14 — not signed in. The B2/B21 line, and the one screen that must not
+ * feel like a wall.
+ *
+ * Line 1 is f1's exact string, so a creator meeting this gate in a second
+ * command reads one product. The last paragraph is the most important copy in
+ * f3's CLI: the overview commits that the local room stays a real room, and a
+ * creator told only "sign in" has just been told the product does not work
+ * without an account, which is false. It is offered as a CAPABILITY, not as
+ * consolation — no "unfortunately", no "you can still".
+ */
+export declare function notSignedIn(): string[];
+/** Flow L16 — `--viewer`, a second terminal, not a second preview. */
+export declare function followingBlock(label: string, descriptor: string): string[];
+export declare function followingFooter(): string[];
+/**
+ * Flow L18 — their dev server is down.
+ *
+ * `!`, not `✗`, and the command does not exit: this is the most common failure
+ * in the whole feature and it is entirely the creator's to fix. Ending the
+ * preview would take away the link and force a re-scan of every phone in the
+ * room over an `npm run dev` they forgot.
+ *
+ * The middle line splits the wire in two, because the creator's first instinct
+ * on a 502 is to suspect us.
+ */
+export declare function originDown(targetUrl: string): string[];
+/** Flow L19 — the creator's own network drops. */
+export declare function reconnecting(): string[];
+export declare function reconnected(): string[];
+export declare function graceExhausted(): string[];
+/**
+ * The drop past the cap. The rule is stated AT THE MOMENT IT BITES and never
+ * before — explaining it up front would be a limit the creator carries through
+ * every healthy session.
+ *
+ * THE NUMBER IS DELIBERATELY NOT NAMED, and that reverses an earlier draft which
+ * read "for the third time" and "up to three times… a fourth time". Three
+ * reasons, in the order they decided it:
+ *
+ *  1. At three the numeral WAS the explanation — a creator could recognise their
+ *     own three drops. At ten nobody has been counting, so the numeral states a
+ *     tally the creator never kept and cannot audit (`graceUsed` is not
+ *     observable from the CLI), and an orienting sentence becomes one that
+ *     invites them to argue with the tally. What is left doing the work is the
+ *     STATE, not the count: the connection kept dropping.
+ *  2. Copy that spells a config value is a SECOND ENCODING of that constant. The
+ *     cap has already moved once mid-build (3 → 10) and this copy went false
+ *     with nothing failing. Not naming it removes the class of bug rather than
+ *     fixing one instance.
+ *  3. The remedy is what the creator needed and the old copy omitted it — the
+ *     block ended on "so the link is gone" with no next command, breaking f3's
+ *     own rule. It is now byte-identical to graceExhausted's, because from the
+ *     creator's position the two endings are the same event with a different
+ *     cause.
+ *
+ * "but only so many times" is a real limit stated without a value: a bound
+ * exists, it is finite, it was reached. If the cap is raised or lowered again the
+ * sentence is still true, which is the property the previous version lacked.
+ */
+export declare function graceCapReached(): string[];
+/**
+ * a. The creator stops it (SIGINT). The connected count appears on the stopping
+ * line ONLY when there are any, because the creator is about to blank someone's
+ * screen and has a half-second to reconsider. It does NOT prompt — a
+ * confirmation on Ctrl-C is the wrong trade in a command a creator stops fifty
+ * times a day, and it would break the unattended agent path (B20).
+ */
+export declare function stopping(connected: number): string;
+export declare function stopped(ranMs: number, totalConnections: number): string[];
+/**
+ * `stopped` arriving on a 410 — someone ended the preview from somewhere else.
+ *
+ * NOT `stopped()` with a different first line, and the difference is not tone.
+ * `stopped()` prints `Ran … · N viewers total` from the timer and counter THIS
+ * process held. A window that was not the actor holds neither, so it would
+ * render `Ran 0m 00s · 0 viewers total` for a preview that ran three hours to a
+ * roomful of phones. A fabricated zero is worse than an omitted line, so this
+ * screen carries no stats at all.
+ *
+ * The claim is exactly what the wire supports: `stopped` is produced by one
+ * route, authorized by the compound key {_id, userId}, so the actor is ALWAYS
+ * the same account as the reader. Never a teammate, never an admin. It does not
+ * say WHICH window, because another terminal, another machine and a future
+ * console control are all the same 410.
+ *
+ * `✓`, not `✗`: someone with the authority to stop it stopped it.
+ */
+export declare function stoppedElsewhere(): string[];
+/**
+ * `disconnected` — the connection closed and the session did not come back.
+ *
+ * This deliberately UNDER-CLAIMS. `disconnected` is the DEFAULT arm of the
+ * edge's reason mapping: a clean socket close, a crashed harness, a laptop lid,
+ * an edge restarting under a deploy, and a genuinely dropped network all land
+ * on this one value. Naming any of them is the over-claim that produced the
+ * abandoned→hard_max defect, so the copy states the one certain fact and then
+ * says out loud that it cannot narrow it.
+ *
+ * "or something on our side" stays. Removing it turns an honest unknown into a
+ * list of the creator's own failures.
+ *
+ * NOT merged with graceExhausted(), though they look adjacent: that screen is
+ * about the CLI's OWN observation — it watched the link go and tried to get it
+ * back, so "check your network" is earned. This one is a reason REPORTED to a
+ * process that may not have witnessed the disconnect, and its target case is
+ * the window that still looks healthy. Merging reinstates the original defect.
+ */
+export declare function endedDisconnected(): string[];
+export declare function formatElapsed(ms: number): string;
+/**
+ * b. The 12-hour hard maximum, warned at 30 minutes.
+ *
+ * The warning names the wall-clock time AND the interval — the first is what a
+ * creator plans a demo around, the second is what they feel — and it states the
+ * cost of restarting, which is the new link. A creator with a printed QR on a
+ * desk needs that sentence 30 minutes early, not at the ceiling.
+ */
+export declare function hardMaxWarning(clockTime: string, minutesLeft: number): string[];
+/**
+ * `✓`, not `✗`. Nothing failed; the preview did exactly what the start block
+ * said it would 12 hours earlier, and marking it as a failure would teach the
+ * creator that the ceiling is a fault. This is the ONLY place in f3 that points
+ * at f4, and it belongs here: it is the exact moment a creator first wants an
+ * address that lasts.
+ */
+export declare function hardMaxReached(): string[];
+/** c. Superseded — the terminal that LOST. */
+export declare function supersededLoser(): string[];
+/**
+ * c. Superseded — the terminal that WON. This sits ABOVE the `✓ Preview is live`
+ * block so the consequence is read before the URL is copied.
+ */
+export declare function supersededWinner(): string[];
+/**
+ * d. The fail-closed drain. TWO causes, one screen each, deliberately NOT
+ * merged, because the remedies differ: one is "find out who you are", the other
+ * is "try again". Neither names the edge, the API, or an outage — a creator
+ * cannot act on that and the retry is the whole of the advice.
+ */
+export declare function endedUnreachable(orgName: string): string[];
+export declare function endedUnconfirmed(): string[];
+/**
+ * e. Abandoned — this machine stopped checking in (the 30-minute heartbeat-
+ * silence flip, `D-Abandoned-sessions-are-judged-on-heartbeat-silence-alone`).
+ *
+ * THIS ENDING EXISTS BECAUSE REPORTING IT AS ANY OF THE OTHER FOUR WOULD BE A
+ * FALSE STATEMENT ABOUT OUR OWN BEHAVIOUR. The nearest neighbour is the hard max,
+ * and it is the one that must never be borrowed: a session flipped at minute 30
+ * has not reached a 12-hour ceiling, and that ending is a `✓` saying the preview
+ * did exactly what it promised. Rendering it here would tell a creator their 12
+ * hours elapsed when 30 minutes did.
+ *
+ * Written for the UNCOMMON reader. In the common case the CLI is dead and nobody
+ * sees this; the screen exists for the creator whose heartbeat channel wedged
+ * while the process lived, who is at a terminal that still looks alive and may
+ * have a working tunnel and a running app in front of them.
+ *
+ *  - "this machine", not the network and not the tunnel: `heartbeatAt` measures
+ *    the creator's check-in and nothing else. "You lost connection" would be
+ *    L19's event and would send them to their router; "the tunnel dropped" would
+ *    be false in the exact case this screen is for. "This machine" also
+ *    disambiguates in a two-machine org.
+ *  - "Nothing is wrong with your project" is load-bearing, not filler. This
+ *    ending arrives with no visible cause, and the first thing a creator does
+ *    with an unexplained ending is look for a fault in their own work.
+ *  - NO duration and no "30 minutes": the interval is a server-side threshold
+ *    the creator cannot observe or plan around, and naming it invites the same
+ *    drift the grace copy just removed.
+ *  - The remedy is `vincentt preview` and there is NO "resume": by the time this
+ *    fires the session's resume tokens are gone, so offering a resume would be
+ *    offering something that cannot work.
+ */
+export declare function endedAbandoned(): string[];
+/**
+ * The 2 GiB soft warning, printed ONCE. It names the ceiling (a warning without
+ * a number is only anxiety), names the cause (a full reload per edit is
+ * genuinely surprising), and names the remedy WITH ITS COST — the new link,
+ * which is otherwise learned the hard way.
+ */
+export declare function egressSoft(): string[];
+export declare function egressHard(): string[];
+/**
+ * The mint limit. No remaining-attempt count and no policy text. The second
+ * paragraph is load-bearing: the person most likely to hit 10/hour is someone
+ * restarting in a loop who has not realised a running preview already serves
+ * them, and that sentence is the actual fix.
+ */
+export declare function mintRateLimited(retryAfterSec: number): string[];
+/**
+ * The wait is rounded and hedged because the number comes from a token bucket
+ * that keeps refilling. "about 20 minutes" that turns out to be 19 is fine;
+ * "20 minutes" that turns out to be 21 reads as a broken promise.
+ */
+export declare function approxWait(seconds: number): string;
+/** The conflict a supersede lost (409). Rare: the mint supersedes first. */
+export declare function previewConflict(): string[];

package/dist/preview/copy.js

@@ -0,0 +1,444 @@
+// Every line `vincentt preview` prints that is not a stream event (Flows
+// L13-L21). Pure functions returning string arrays, so the transcripts are
+// assertable without a terminal.
+//
+// Four vocabulary rules govern all of it:
+//   - "Preview" is the noun and the verb. `session` is the API's word and never
+//     reaches a creator's screen. What ends is THE PREVIEW; what the phone holds
+//     is THE LINK.
+//   - "Viewer" is a phone, spoken of as a DEVICE, never as a person. The moment
+//     the UI says "who", the label has been promoted into an identity.
+//   - The link is "temporary", never "expired", "revoked" or "invalid".
+//   - The creator's own dev server is "your dev server" / "your app", never
+//     "the origin" or "upstream".
+//
+// NEVER PRINTED, at any point, in any state: the grant, the resume token, the
+// session id, the edge hostname, or the workingTreeKey. The grant is the
+// sharpest — it transits an agent's tool-output transcript by default in this
+// product, so f1's "a token is never printed" extends to it verbatim.
+export function startBlock(i) {
+    const out = [
+        "",
+        // The org is dropped rather than rendered as a dangling separator when it
+        // is not known. `Museum AR Tour · ` reads as a truncated line — the one
+        // moment a wrong binding is cheap to catch is the one moment the line must
+        // not look broken.
+        i.orgName ? `→ ${i.projectName} · ${i.orgName}` : `→ ${i.projectName}`,
+        `→ Serving ${i.targetUrl}`,
+        "",
+        "✓ Preview is live",
+        "",
+        // The URL is on its own line, indented, unwrapped and UNADORNED. No `URL:`
+        // label, no backticks, no surrounding punctuation — it is the single
+        // most-copied string in the product, and anything beside it ends up in
+        // someone's paste.
+        `    ${i.url}`,
+        "",
+    ];
+    if (i.qr && i.qr.length > 0) {
+        out.push(...i.qr.map((row) => `    ${row}`), "");
+    }
+    out.push("    Scan it, or open the link on any phone. No sign-in needed on the phone.", `    Expires in ${i.expiresInHours}h · Ctrl-C to stop`, "", "  Waiting for a device…", "");
+    return out;
+}
+/**
+ * Flow L14 — not signed in. The B2/B21 line, and the one screen that must not
+ * feel like a wall.
+ *
+ * Line 1 is f1's exact string, so a creator meeting this gate in a second
+ * command reads one product. The last paragraph is the most important copy in
+ * f3's CLI: the overview commits that the local room stays a real room, and a
+ * creator told only "sign in" has just been told the product does not work
+ * without an account, which is false. It is offered as a CAPABILITY, not as
+ * consolation — no "unfortunately", no "you can still".
+ */
+export function notSignedIn() {
+    return [
+        "",
+        "✗ You're not signed in.",
+        "",
+        "  A preview needs a hostname your phone can reach, and that needs an account.",
+        "",
+        "  Sign in:  vincentt login",
+        "",
+        "  Your local dev loop does not need one — `npm run dev` and open",
+        "  http://localhost:5173 on this machine. The camera works there.",
+        "  What signing in adds is the phone.",
+        "",
+    ];
+}
+/** Flow L16 — `--viewer`, a second terminal, not a second preview. */
+export function followingBlock(label, descriptor) {
+    return [
+        "→ Attaching to the preview running in this folder",
+        descriptor ? `✓ Following ${label} · ${descriptor}` : `✓ Following ${label}`,
+        "",
+    ];
+}
+export function followingFooter() {
+    return ["", "  Ctrl-C to stop following. The preview keeps running."];
+}
+/**
+ * Flow L18 — their dev server is down.
+ *
+ * `!`, not `✗`, and the command does not exit: this is the most common failure
+ * in the whole feature and it is entirely the creator's to fix. Ending the
+ * preview would take away the link and force a re-scan of every phone in the
+ * room over an `npm run dev` they forgot.
+ *
+ * The middle line splits the wire in two, because the creator's first instinct
+ * on a 502 is to suspect us.
+ */
+export function originDown(targetUrl) {
+    return [
+        `! Your dev server isn't responding on ${targetUrl}.`,
+        "",
+        "  The preview is still live — the phone is reaching us, we can't reach your app.",
+        "  Start it and reload the phone:  npm run dev",
+        "",
+    ];
+}
+/** Flow L19 — the creator's own network drops. */
+export function reconnecting() {
+    return [
+        "! Lost the connection to Vincentt. Reconnecting…",
+        '  Your phone will show "reconnecting" and retry on its own.',
+        "",
+    ];
+}
+export function reconnected() {
+    return ["✓ Reconnected. Same link, same session.", ""];
+}
+export function graceExhausted() {
+    return [
+        "",
+        "✗ Couldn't reconnect. The preview has ended and the link no longer works.",
+        "",
+        "  Check your network, then:  vincentt preview",
+        "",
+    ];
+}
+/**
+ * The drop past the cap. The rule is stated AT THE MOMENT IT BITES and never
+ * before — explaining it up front would be a limit the creator carries through
+ * every healthy session.
+ *
+ * THE NUMBER IS DELIBERATELY NOT NAMED, and that reverses an earlier draft which
+ * read "for the third time" and "up to three times… a fourth time". Three
+ * reasons, in the order they decided it:
+ *
+ *  1. At three the numeral WAS the explanation — a creator could recognise their
+ *     own three drops. At ten nobody has been counting, so the numeral states a
+ *     tally the creator never kept and cannot audit (`graceUsed` is not
+ *     observable from the CLI), and an orienting sentence becomes one that
+ *     invites them to argue with the tally. What is left doing the work is the
+ *     STATE, not the count: the connection kept dropping.
+ *  2. Copy that spells a config value is a SECOND ENCODING of that constant. The
+ *     cap has already moved once mid-build (3 → 10) and this copy went false
+ *     with nothing failing. Not naming it removes the class of bug rather than
+ *     fixing one instance.
+ *  3. The remedy is what the creator needed and the old copy omitted it — the
+ *     block ended on "so the link is gone" with no next command, breaking f3's
+ *     own rule. It is now byte-identical to graceExhausted's, because from the
+ *     creator's position the two endings are the same event with a different
+ *     cause.
+ *
+ * "but only so many times" is a real limit stated without a value: a bound
+ * exists, it is finite, it was reached. If the cap is raised or lowered again the
+ * sentence is still true, which is the property the previous version lacked.
+ */
+export function graceCapReached() {
+    return [
+        "",
+        "✗ The connection to Vincentt kept dropping. Ending the preview.",
+        "",
+        "  A preview holds its link across a brief drop, but only so many times, and",
+        "  this one has used them up. The link is gone.",
+        "",
+        "  Check your network, then:  vincentt preview",
+        "",
+    ];
+}
+// ---- Flow L20, the four endings ---------------------------------------------
+/**
+ * a. The creator stops it (SIGINT). The connected count appears on the stopping
+ * line ONLY when there are any, because the creator is about to blank someone's
+ * screen and has a half-second to reconsider. It does NOT prompt — a
+ * confirmation on Ctrl-C is the wrong trade in a command a creator stops fifty
+ * times a day, and it would break the unattended agent path (B20).
+ */
+// Both lines say CONNECTIONS, not viewers. One device opens several (the edge is
+// HTTP/1.1 only, so a browser cannot multiplex and opens a second connection for
+// assets), and the device count is not available to print instead — ViewerConn
+// deliberately holds nothing a correlator could use. Naming the unit is the only
+// honest option; "2 viewers" for one phone was not.
+export function stopping(connected) {
+    return connected > 0
+        ? `→ Stopping…  ${connected} connection${connected === 1 ? "" : "s"} open`
+        : "→ Stopping…";
+}
+export function stopped(ranMs, totalConnections) {
+    return [
+        "✓ Preview stopped. The link no longer works.",
+        // Kept at stop time: a connection total is a true statement about the run,
+        // and unlike the live count it does not masquerade as "who is watching".
+        // Nothing is retained.
+        `  Ran ${formatElapsed(ranMs)} · ${totalConnections} connection${totalConnections === 1 ? "" : "s"} total`,
+    ];
+}
+/**
+ * `stopped` arriving on a 410 — someone ended the preview from somewhere else.
+ *
+ * NOT `stopped()` with a different first line, and the difference is not tone.
+ * `stopped()` prints `Ran … · N viewers total` from the timer and counter THIS
+ * process held. A window that was not the actor holds neither, so it would
+ * render `Ran 0m 00s · 0 viewers total` for a preview that ran three hours to a
+ * roomful of phones. A fabricated zero is worse than an omitted line, so this
+ * screen carries no stats at all.
+ *
+ * The claim is exactly what the wire supports: `stopped` is produced by one
+ * route, authorized by the compound key {_id, userId}, so the actor is ALWAYS
+ * the same account as the reader. Never a teammate, never an admin. It does not
+ * say WHICH window, because another terminal, another machine and a future
+ * console control are all the same 410.
+ *
+ * `✓`, not `✗`: someone with the authority to stop it stopped it.
+ */
+export function stoppedElsewhere() {
+    return [
+        "",
+        "✓ Preview stopped from another terminal. The link no longer works.",
+        "",
+        "  It was stopped on your account, not by this window. Nothing is wrong here.",
+        "",
+        "  Start a new one:  vincentt preview",
+        "",
+    ];
+}
+/**
+ * `disconnected` — the connection closed and the session did not come back.
+ *
+ * This deliberately UNDER-CLAIMS. `disconnected` is the DEFAULT arm of the
+ * edge's reason mapping: a clean socket close, a crashed harness, a laptop lid,
+ * an edge restarting under a deploy, and a genuinely dropped network all land
+ * on this one value. Naming any of them is the over-claim that produced the
+ * abandoned→hard_max defect, so the copy states the one certain fact and then
+ * says out loud that it cannot narrow it.
+ *
+ * "or something on our side" stays. Removing it turns an honest unknown into a
+ * list of the creator's own failures.
+ *
+ * NOT merged with graceExhausted(), though they look adjacent: that screen is
+ * about the CLI's OWN observation — it watched the link go and tried to get it
+ * back, so "check your network" is earned. This one is a reason REPORTED to a
+ * process that may not have witnessed the disconnect, and its target case is
+ * the window that still looks healthy. Merging reinstates the original defect.
+ */
+export function endedDisconnected() {
+    return [
+        "",
+        "✗ Preview ended — the connection to Vincentt closed.",
+        "",
+        "  This window can't tell whether that was your network, your machine going to",
+        "  sleep, or something on our side. Nothing is wrong with your project.",
+        "",
+        "  Start a new one:  vincentt preview",
+        "",
+    ];
+}
+export function formatElapsed(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    const pad = (n) => String(n).padStart(2, "0");
+    return h > 0 ? `${h}h ${pad(m)}m ${pad(s)}s` : `${m}m ${pad(s)}s`;
+}
+/**
+ * b. The 12-hour hard maximum, warned at 30 minutes.
+ *
+ * The warning names the wall-clock time AND the interval — the first is what a
+ * creator plans a demo around, the second is what they feel — and it states the
+ * cost of restarting, which is the new link. A creator with a printed QR on a
+ * desk needs that sentence 30 minutes early, not at the ceiling.
+ */
+export function hardMaxWarning(clockTime, minutesLeft) {
+    return [
+        `! This preview reaches its 12-hour maximum at ${clockTime} (in ${minutesLeft}m) and will stop.`,
+        "",
+        "  A preview link is deliberately short-lived. To keep going, start a new one",
+        "  then — you'll get a new link, so any QR code on a desk will need re-scanning.",
+        "",
+    ];
+}
+/**
+ * `✓`, not `✗`. Nothing failed; the preview did exactly what the start block
+ * said it would 12 hours earlier, and marking it as a failure would teach the
+ * creator that the ceiling is a fault. This is the ONLY place in f3 that points
+ * at f4, and it belongs here: it is the exact moment a creator first wants an
+ * address that lasts.
+ */
+export function hardMaxReached() {
+    return [
+        "",
+        "✓ Preview stopped — 12-hour maximum reached. The link no longer works.",
+        "",
+        "  Start a new one:  vincentt preview",
+        "  For an address that lasts, publish it:  vincentt publish",
+        "",
+    ];
+}
+/** c. Superseded — the terminal that LOST. */
+export function supersededLoser() {
+    return [
+        "",
+        "✗ This preview was replaced by a newer one for this folder.",
+        "",
+        "  Its link no longer works. The new preview has a different link — whoever",
+        "  is holding a phone will need it again.",
+        "",
+    ];
+}
+/**
+ * c. Superseded — the terminal that WON. This sits ABOVE the `✓ Preview is live`
+ * block so the consequence is read before the URL is copied.
+ */
+export function supersededWinner() {
+    return [
+        "",
+        "! Replaced the preview that was already running for this folder.",
+        "  Its link stopped working. Anyone on it will need the new one below.",
+    ];
+}
+/**
+ * d. The fail-closed drain. TWO causes, one screen each, deliberately NOT
+ * merged, because the remedies differ: one is "find out who you are", the other
+ * is "try again". Neither names the edge, the API, or an outage — a creator
+ * cannot act on that and the retry is the whole of the advice.
+ */
+export function endedUnreachable(orgName) {
+    return [
+        "",
+        "✗ Preview ended — this project is no longer available to you.",
+        "",
+        `  Your access to ${orgName} may have changed. Check who you are:  vincentt whoami`,
+        "",
+    ];
+}
+export function endedUnconfirmed() {
+    return [
+        "",
+        "✗ Preview ended — couldn't confirm your access to this project.",
+        "",
+        "  Try again:  vincentt preview",
+        "",
+    ];
+}
+/**
+ * e. Abandoned — this machine stopped checking in (the 30-minute heartbeat-
+ * silence flip, `D-Abandoned-sessions-are-judged-on-heartbeat-silence-alone`).
+ *
+ * THIS ENDING EXISTS BECAUSE REPORTING IT AS ANY OF THE OTHER FOUR WOULD BE A
+ * FALSE STATEMENT ABOUT OUR OWN BEHAVIOUR. The nearest neighbour is the hard max,
+ * and it is the one that must never be borrowed: a session flipped at minute 30
+ * has not reached a 12-hour ceiling, and that ending is a `✓` saying the preview
+ * did exactly what it promised. Rendering it here would tell a creator their 12
+ * hours elapsed when 30 minutes did.
+ *
+ * Written for the UNCOMMON reader. In the common case the CLI is dead and nobody
+ * sees this; the screen exists for the creator whose heartbeat channel wedged
+ * while the process lived, who is at a terminal that still looks alive and may
+ * have a working tunnel and a running app in front of them.
+ *
+ *  - "this machine", not the network and not the tunnel: `heartbeatAt` measures
+ *    the creator's check-in and nothing else. "You lost connection" would be
+ *    L19's event and would send them to their router; "the tunnel dropped" would
+ *    be false in the exact case this screen is for. "This machine" also
+ *    disambiguates in a two-machine org.
+ *  - "Nothing is wrong with your project" is load-bearing, not filler. This
+ *    ending arrives with no visible cause, and the first thing a creator does
+ *    with an unexplained ending is look for a fault in their own work.
+ *  - NO duration and no "30 minutes": the interval is a server-side threshold
+ *    the creator cannot observe or plan around, and naming it invites the same
+ *    drift the grace copy just removed.
+ *  - The remedy is `vincentt preview` and there is NO "resume": by the time this
+ *    fires the session's resume tokens are gone, so offering a resume would be
+ *    offering something that cannot work.
+ */
+export function endedAbandoned() {
+    return [
+        "",
+        "✗ Preview ended — this machine stopped checking in with Vincentt.",
+        "",
+        "  The preview needed this computer to stay in touch and it went quiet, so the",
+        "  link was released. Nothing is wrong with your project.",
+        "",
+        "  Start a new one:  vincentt preview",
+        "",
+    ];
+}
+// ---- Flow L21, the two budget stops -----------------------------------------
+/**
+ * The 2 GiB soft warning, printed ONCE. It names the ceiling (a warning without
+ * a number is only anxiety), names the cause (a full reload per edit is
+ * genuinely surprising), and names the remedy WITH ITS COST — the new link,
+ * which is otherwise learned the hard way.
+ */
+export function egressSoft() {
+    return [
+        "! This preview has served 2 GB. There's a 5 GB ceiling per preview.",
+        "",
+        "  Large models reload in full on every edit. If you're near the ceiling,",
+        "  stopping and starting gives you a fresh budget (and a new link).",
+        "",
+    ];
+}
+export function egressHard() {
+    return [
+        "",
+        "✗ Preview ended — it reached the 5 GB ceiling.",
+        "",
+        "  Start a new one:  vincentt preview",
+        "",
+    ];
+}
+/**
+ * The mint limit. No remaining-attempt count and no policy text. The second
+ * paragraph is load-bearing: the person most likely to hit 10/hour is someone
+ * restarting in a loop who has not realised a running preview already serves
+ * them, and that sentence is the actual fix.
+ */
+export function mintRateLimited(retryAfterSec) {
+    return [
+        "",
+        `✗ Too many previews started recently. Try again in ${approxWait(retryAfterSec)}.`,
+        "",
+        "  A running preview does not count against this — if one is already running",
+        "  for this folder, you don't need a new one.",
+        "",
+    ];
+}
+/**
+ * The wait is rounded and hedged because the number comes from a token bucket
+ * that keeps refilling. "about 20 minutes" that turns out to be 19 is fine;
+ * "20 minutes" that turns out to be 21 reads as a broken promise.
+ */
+export function approxWait(seconds) {
+    if (seconds < 90)
+        return "about a minute";
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `about ${minutes} minutes`;
+    const hours = Math.round(minutes / 60);
+    return `about ${hours} hour${hours === 1 ? "" : "s"}`;
+}
+/** The conflict a supersede lost (409). Rare: the mint supersedes first. */
+export function previewConflict() {
+    return [
+        "",
+        "✗ A preview is already running for this folder.",
+        "",
+        "  Watch it from here:  vincentt preview",
+        "",
+    ];
+}

package/dist/preview/index.d.ts

@@ -1,3 +1,2 @@
-export { startSessionTunnel, type SessionTunnel } from "./tunnel.js";
-export { ensureCloudflared, type EnsureCloudflaredOptions } from "./cloudflared.js";
-export { startPreview, type StartPreviewOptions, type RunningPreview } from "./runner.js";
+export { startPreview, controlToReason, runHeartbeat, type StartPreviewOptions, type RunningPreview, type PreviewEndReason, } from "./runner.js";
+export { endPreviewSession, heartbeatPreviewSession, mintPreviewSession, parseMint, parseRetryAfter, workingTreeKey, PreviewConflictError, PreviewEndedError, PreviewRateLimitedError, type HeartbeatResult, type MintedPreview, } from "./api.js";

package/dist/preview/index.js

@@ -1,6 +1,5 @@
-// Public surface of the preview limb (`@vincentt-xr/harness/preview`): the tunnel
-// mint, the cloudflared resolver, and the full one-call preview runner. Barrel
-// only — implementations live in the sibling modules.
-export { startSessionTunnel } from "./tunnel.js";
-export { ensureCloudflared } from "./cloudflared.js";
-export { startPreview } from "./runner.js";
+// Public surface of the preview limb (`@vincentt-xr/cli/preview`): the preview-
+// session API calls and the one-call preview runner. Barrel only —
+// implementations live in the sibling modules.
+export { startPreview, controlToReason, runHeartbeat, } from "./runner.js";
+export { endPreviewSession, heartbeatPreviewSession, mintPreviewSession, parseMint, parseRetryAfter, workingTreeKey, PreviewConflictError, PreviewEndedError, PreviewRateLimitedError, } from "./api.js";