@vincentt-xr/cli 0.20.0 → 0.21.0

package/dist/publish/weight.d.ts

@@ -0,0 +1,23 @@
+import type { ManifestEntry } from "./manifest.js";
+export declare const HEAVY_MODEL_BYTES = 10000000;
+export declare const HEAVY_IMAGE_PX = 2048;
+export declare const IMAGE_HEAD_BYTES = 524288;
+export type HeavyFinding = {
+    path: string;
+    kind: "model";
+    bytes: number;
+} | {
+    path: string;
+    kind: "image";
+    width: number;
+    height: number;
+};
+export type ReadHead = (path: string, n: number) => Promise<Uint8Array>;
+export declare function heavyFileFindings(files: readonly ManifestEntry[], readHead: ReadHead): Promise<HeavyFinding[]>;
+type Size = {
+    width: number;
+    height: number;
+};
+/** Pixel size from a file header, or undefined for an unknown or truncated one. */
+export declare function imageSize(head: Uint8Array): Size | undefined;
+export {};

package/dist/publish/weight.js

@@ -0,0 +1,113 @@
+// The checklist's `Heavy files` finding: a model over 10 MB, or an image over
+// 2048 px on its long side. Local and warning-only; nothing here can fail a
+// publish, and nothing is sent anywhere.
+export const HEAVY_MODEL_BYTES = 10_000_000;
+export const HEAVY_IMAGE_PX = 2048;
+export const IMAGE_HEAD_BYTES = 524_288;
+const MODEL_EXT = /\.(glb|gltf)$/i;
+const IMAGE_EXT = /\.(png|jpe?g|webp|gif)$/i;
+const longSide = (f) => Math.max(f.width, f.height);
+export async function heavyFileFindings(files, readHead) {
+    const models = [];
+    const images = [];
+    for (const f of files) {
+        if (MODEL_EXT.test(f.path)) {
+            if (f.size > HEAVY_MODEL_BYTES) {
+                models.push({ path: f.path, kind: "model", bytes: f.size });
+            }
+        }
+        else if (IMAGE_EXT.test(f.path)) {
+            let head;
+            try {
+                head = await readHead(f.path, Math.min(f.size, IMAGE_HEAD_BYTES));
+            }
+            catch {
+                continue;
+            }
+            const dims = imageSize(head);
+            if (dims && longSide(dims) > HEAVY_IMAGE_PX) {
+                images.push({ path: f.path, kind: "image", ...dims });
+            }
+        }
+    }
+    models.sort((a, b) => b.bytes - a.bytes);
+    images.sort((a, b) => longSide(b) - longSide(a));
+    return [...models, ...images];
+}
+const u16be = (b, o) => (b[o] << 8) | b[o + 1];
+const u32be = (b, o) => ((b[o] << 24) | (b[o + 1] << 16) | (b[o + 2] << 8) | b[o + 3]) >>> 0;
+const u16le = (b, o) => b[o] | (b[o + 1] << 8);
+const u24le = (b, o) => b[o] | (b[o + 1] << 8) | (b[o + 2] << 16);
+const ascii = (b, o, s) => {
+    if (o + s.length > b.length)
+        return false;
+    for (let i = 0; i < s.length; i++)
+        if (b[o + i] !== s.charCodeAt(i))
+            return false;
+    return true;
+};
+/** Pixel size from a file header, or undefined for an unknown or truncated one. */
+export function imageSize(head) {
+    const size = readSize(head);
+    return size && size.width > 0 && size.height > 0 ? size : undefined;
+}
+function readSize(b) {
+    if (b.length >= 24 && b[0] === 0x89 && ascii(b, 1, "PNG\r\n\x1a\n") && ascii(b, 12, "IHDR")) {
+        return { width: u32be(b, 16), height: u32be(b, 20) };
+    }
+    if (b.length >= 10 && (ascii(b, 0, "GIF87a") || ascii(b, 0, "GIF89a"))) {
+        return { width: u16le(b, 6), height: u16le(b, 8) };
+    }
+    if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8)
+        return jpegSize(b);
+    if (b.length >= 16 && ascii(b, 0, "RIFF") && ascii(b, 8, "WEBP"))
+        return webpSize(b);
+    return undefined;
+}
+function jpegSize(b) {
+    let o = 2;
+    while (o + 4 <= b.length) {
+        if (b[o] !== 0xff)
+            return undefined;
+        const marker = b[o + 1];
+        if (marker === 0xff) {
+            o += 1;
+            continue;
+        }
+        // Standalone markers carry no length: TEM, RSTn, SOI, EOI.
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) {
+            o += 2;
+            continue;
+        }
+        const len = u16be(b, o + 2);
+        if (len < 2)
+            return undefined;
+        const isSof = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+        if (isSof) {
+            if (o + 9 > b.length)
+                return undefined;
+            return { height: u16be(b, o + 5), width: u16be(b, o + 7) };
+        }
+        o += 2 + len;
+    }
+    return undefined;
+}
+function webpSize(b) {
+    if (ascii(b, 12, "VP8X")) {
+        if (b.length < 30)
+            return undefined;
+        return { width: u24le(b, 24) + 1, height: u24le(b, 27) + 1 };
+    }
+    if (ascii(b, 12, "VP8L")) {
+        if (b.length < 25 || b[20] !== 0x2f)
+            return undefined;
+        const bits = (b[21] | (b[22] << 8) | (b[23] << 16) | (b[24] << 24)) >>> 0;
+        return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+    }
+    if (ascii(b, 12, "VP8 ")) {
+        if (b.length < 30 || b[23] !== 0x9d || b[24] !== 0x01 || b[25] !== 0x2a)
+            return undefined;
+        return { width: u16le(b, 26) & 0x3fff, height: u16le(b, 28) & 0x3fff };
+    }
+    return undefined;
+}

package/dist/shared/credentialNames.d.ts

@@ -0,0 +1,17 @@
+export declare const CREDENTIAL_NAMES: readonly RegExp[];
+export declare const PUBLISH_CREDENTIAL_NAMES: readonly RegExp[];
+/** Backup endings a name may carry and still match. */
+export declare const PREVIEW_STRIP: readonly string[];
+/** Preview's endings plus the precompressed copies a build tool writes beside a file. */
+export declare const PUBLISH_STRIP: readonly string[];
+/**
+ * The name a case-insensitive or Windows file system would open: trailing dots
+ * and spaces dropped once (Windows resolves `server.pem. .` to `server.pem`),
+ * then compatibility and case forms folded.
+ */
+export declare function foldName(name: string): string;
+/**
+ * Whether an already folded name matches `list`, as is or after removing one
+ * ending from `strip`, repeatedly (`credentials.json.bak.gz`).
+ */
+export declare function isCredentialName(name: string, list: readonly RegExp[], strip: readonly string[]): boolean;

package/dist/shared/credentialNames.js

@@ -0,0 +1,72 @@
+// The one credential-name list. Preview refuses to serve these names and publish
+// refuses to upload them (publish without `*.pem`, because a public certificate
+// is published legitimately and a private key in one is caught by content).
+// Hard-coded, no opt-out, no exception list.
+const PEM_GLOB = "*.pem";
+const GLOBS = [
+    "credentials.json",
+    "service-account*.json",
+    "*firebase-adminsdk*.json",
+    PEM_GLOB,
+    "*.key",
+    "*.p12",
+    "*.pfx",
+    "*.p8",
+    "*.ppk",
+    "id_rsa*",
+    "id_dsa*",
+    "id_ed25519*",
+    "id_ecdsa*",
+    "*.jks",
+    "*.keystore",
+    "*.env",
+    "*.tfstate",
+    "*.tfvars",
+];
+/** Anchored; `*` is any run of characters, including none. */
+function compileGlob(glob) {
+    return new RegExp(`^${glob
+        .split("*")
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*")}$`, "s");
+}
+export const CREDENTIAL_NAMES = Object.freeze(GLOBS.map(compileGlob));
+const PEM_SOURCE = compileGlob(PEM_GLOB).source;
+export const PUBLISH_CREDENTIAL_NAMES = Object.freeze(CREDENTIAL_NAMES.filter((re) => re.source !== PEM_SOURCE));
+/** Backup endings a name may carry and still match. */
+export const PREVIEW_STRIP = Object.freeze(["~", ".bak"]);
+/** Preview's endings plus the precompressed copies a build tool writes beside a file. */
+export const PUBLISH_STRIP = Object.freeze([
+    "~",
+    ".bak",
+    ".gz",
+    ".br",
+    ".zst",
+]);
+/**
+ * The name a case-insensitive or Windows file system would open: trailing dots
+ * and spaces dropped once (Windows resolves `server.pem. .` to `server.pem`),
+ * then compatibility and case forms folded.
+ */
+export function foldName(name) {
+    return name
+        .replace(/[. ]+$/, "")
+        .normalize("NFKC")
+        .toUpperCase()
+        .toLowerCase();
+}
+/**
+ * Whether an already folded name matches `list`, as is or after removing one
+ * ending from `strip`, repeatedly (`credentials.json.bak.gz`).
+ */
+export function isCredentialName(name, list, strip) {
+    let candidate = name;
+    for (;;) {
+        if (list.some((re) => re.test(candidate)))
+            return true;
+        const suffix = strip.find((s) => candidate.endsWith(s));
+        if (suffix === undefined)
+            return false;
+        candidate = candidate.slice(0, candidate.length - suffix.length);
+    }
+}

package/dist/shared/http.d.ts

@@ -1,3 +1,4 @@
+import { type IncomingMessage } from "node:http";
 /** A request that did not finish inside its deadline. Nothing is known about its outcome. */
 export declare class RequestTimeout extends Error {
     readonly ms: number;
@@ -16,6 +17,39 @@ export declare function withDeadline(fetchImpl: typeof fetch, ms: number): typeo
  * a test that stubs the global still reaches its stub.
  */
 export declare const apiFetch: typeof fetch;
+/** Where an api request goes: the configured API host, and the token when one is held. */
+export interface ApiTarget {
+    apiUrl: string;
+    pat?: string;
+}
+export interface ApiRequestOptions {
+    /**
+     * Whether the request carries the machine token. Declared at every call site
+     * rather than inferred from whether a token happens to be held, so a public
+     * route can never pick one up by accident.
+     */
+    authenticated: boolean;
+}
+/** A request aimed off the configured API origin. Refused before any socket opens. */
+export declare class ApiOriginError extends Error {
+    constructor();
+}
+/** The absolute URL for an API path, refusing anything that would leave the API origin. */
+export declare function apiRequestUrl(target: Pick<ApiTarget, "apiUrl">, path: string): URL;
+/**
+ * The caller's headers plus the client tag, and the bearer only when
+ * authenticated. A caller-supplied tag or Authorization, in any casing, is
+ * dropped first, so exactly one of each reaches the wire.
+ */
+export declare function apiHeaders(target: ApiTarget, init: RequestInit["headers"], opts: ApiRequestOptions): Record<string, string>;
+/** Every api request the CLI makes over fetch is built here. S3 uploads are not api requests. */
+export declare function apiRequest(target: ApiTarget, path: string, init: RequestInit | undefined, opts: ApiRequestOptions, fetchImpl?: typeof fetch): Promise<Response>;
+/**
+ * An unauthenticated GET whose socket is unref'd, so a pending request never
+ * holds the process open. There is no credential parameter at all: the only
+ * caller is the public versions refresh after a verb has finished.
+ */
+export declare function apiRequestDetached(target: Pick<ApiTarget, "apiUrl">, path: string, headers: Record<string, string>, timeoutMs: number, onResponse: (res: IncomingMessage, abort: () => void) => void): void;
 /**
  * A request abandoned by the network or by its deadline, as opposed to a
  * response the server sent. Its outcome on the server is unknown.

package/dist/shared/http.js

@@ -1,6 +1,10 @@
-// The one fetch wrapper with a deadline. Every api call goes through apiFetch, so
-// a stalled server or a dead network ends in a bounded error instead of a hang
+// The one place an api request is built. apiRequest stamps the client tag and,
+// only when asked, the bearer; apiFetch bounds every call with a deadline, so a
+// stalled server or a dead network ends in a bounded error instead of a hang
 // (including the Ctrl-C path, which ends the preview session with an api call).
+import http from "node:http";
+import https from "node:https";
+import { CLIENT_HEADER, clientHeaderValue } from "./clientHeader.js";
 /** A request that did not finish inside its deadline. Nothing is known about its outcome. */
 export class RequestTimeout extends Error {
     ms;
@@ -46,6 +50,98 @@ export function withDeadline(fetchImpl, ms) {
  * a test that stubs the global still reaches its stub.
  */
 export const apiFetch = withDeadline((input, init) => globalThis.fetch(input, init), API_DEADLINE_MS);
+/** A request aimed off the configured API origin. Refused before any socket opens. */
+export class ApiOriginError extends Error {
+    constructor() {
+        super("refusing an api request that is not a path on the configured API host");
+        this.name = "ApiOriginError";
+    }
+}
+/** The absolute URL for an API path, refusing anything that would leave the API origin. */
+export function apiRequestUrl(target, path) {
+    if (!path.startsWith("/") || path.startsWith("//") || path.includes("\\")) {
+        throw new ApiOriginError();
+    }
+    let base;
+    let url;
+    try {
+        base = new URL(target.apiUrl);
+        url = new URL(`${target.apiUrl.replace(/\/+$/, "")}${path}`);
+    }
+    catch {
+        throw new ApiOriginError();
+    }
+    if (url.origin !== base.origin)
+        throw new ApiOriginError();
+    return url;
+}
+const STAMPED = new Set([CLIENT_HEADER.toLowerCase(), "authorization"]);
+/**
+ * The caller's headers plus the client tag, and the bearer only when
+ * authenticated. A caller-supplied tag or Authorization, in any casing, is
+ * dropped first, so exactly one of each reaches the wire.
+ */
+export function apiHeaders(target, init, opts) {
+    const out = {};
+    new Headers(init).forEach((value, name) => {
+        if (!STAMPED.has(name))
+            out[name] = value;
+    });
+    out[CLIENT_HEADER] = clientHeaderValue();
+    if (opts.authenticated) {
+        if (!target.pat)
+            throw new Error("an authenticated api request needs a token");
+        out.authorization = `Bearer ${target.pat}`;
+    }
+    return out;
+}
+/** Every api request the CLI makes over fetch is built here. S3 uploads are not api requests. */
+export function apiRequest(target, path, init = {}, opts, fetchImpl = apiFetch) {
+    let url;
+    let headers;
+    try {
+        url = apiRequestUrl(target, path);
+        headers = apiHeaders(target, init.headers, opts);
+    }
+    catch (err) {
+        return Promise.reject(err);
+    }
+    return fetchImpl(url.toString(), { ...init, headers });
+}
+/**
+ * An unauthenticated GET whose socket is unref'd, so a pending request never
+ * holds the process open. There is no credential parameter at all: the only
+ * caller is the public versions refresh after a verb has finished.
+ */
+export function apiRequestDetached(target, path, headers, timeoutMs, onResponse) {
+    let url;
+    let stamped;
+    try {
+        url = apiRequestUrl(target, path);
+        stamped = apiHeaders({ apiUrl: target.apiUrl }, headers, { authenticated: false });
+    }
+    catch {
+        return;
+    }
+    const transport = url.protocol === "https:" ? https : http;
+    try {
+        const req = transport.request({
+            protocol: url.protocol,
+            hostname: url.hostname,
+            port: url.port,
+            path: `${url.pathname}${url.search}`,
+            method: "GET",
+            headers: stamped,
+        }, (res) => onResponse(res, () => req.destroy()));
+        req.on("socket", (socket) => socket.unref());
+        req.on("error", () => { });
+        req.setTimeout(timeoutMs, () => req.destroy());
+        req.end();
+    }
+    catch {
+        // A request that cannot even be started is nothing to say.
+    }
+}
 /**
  * A request abandoned by the network or by its deadline, as opposed to a
  * response the server sent. Its outcome on the server is unknown.

package/dist/shared/upgradeError.d.ts

@@ -0,0 +1,62 @@
+export declare const UPGRADE_REQUIRED_STATUS = 426;
+export declare const UPGRADE_REQUIRED_CODE = "cli_upgrade_required";
+/** A constant, never built from the wire. `@latest` is always at or above any floor. */
+export declare const INSTALL_COMMAND = "npm install -g @vincentt-xr/cli@latest";
+/** Why the platform refused: a category, never the declared version itself. */
+export type RefusalCategory = "below" | "missing" | "unparseable";
+export interface UpgradeFacts {
+    /** The floor, only when it parsed as strict X.Y.Z. */
+    minimum?: string;
+    declared?: RefusalCategory;
+}
+export declare class UpgradeRequiredError extends Error implements UpgradeFacts {
+    readonly minimum?: string | undefined;
+    readonly declared?: RefusalCategory | undefined;
+    readonly status = 426;
+    constructor(minimum?: string | undefined, declared?: RefusalCategory | undefined);
+}
+/** The floor as the platform sent it, or undefined unless it is strict X.Y.Z. */
+export declare function parseMinimum(raw: unknown): string | undefined;
+/** A refusal category outside the closed set reads as absent. */
+export declare function parseDeclared(raw: unknown): RefusalCategory | undefined;
+/**
+ * Every api client calls this on a response before any other refusal arm,
+ * including rejectAuthExpired. Any 426 is the version refusal, whatever code
+ * its body carries.
+ */
+export declare function rejectUpgradeRequired(res: Response): Promise<void>;
+/** Where the refusal landed, which decides what the screen says did not happen. */
+export type RefusalArm = {
+    kind: "generic";
+} | {
+    kind: "create";
+    dir?: string;
+} | {
+    kind: "login";
+}
+/**
+ * The exchange was admitted and the token saved, then the account check was
+ * refused. Something WAS changed: this machine is signed in, and the lines
+ * name any machine the sign-in signed out.
+ */
+ | {
+    kind: "login_saved";
+    evictionLines: string[];
+} | {
+    kind: "publish";
+    /** The live host, when the project was read before the refusal. */
+    address?: string;
+    /** Set only when the upload completed before the refusal. */
+    stillServing?: number;
+} | {
+    kind: "preview_start";
+    devCommand: string;
+    localUrl: string;
+};
+/** Flow L22: the version refusal on any verb, in the arm that knows where it landed. */
+export declare function upgradeRefusalLines(facts: UpgradeFacts, arm?: RefusalArm, own?: string): string[];
+/**
+ * Flow L20 (h): a running preview the platform refused, on the heartbeat or on a
+ * reconnect dial. One screen for both arrival paths.
+ */
+export declare function previewTooOldLines(facts: UpgradeFacts, own?: string): string[];

package/dist/shared/upgradeError.js

@@ -0,0 +1,215 @@
+// The platform refused this CLI's version (`426 cli_upgrade_required`, or a dial
+// answered 410 with `X-Vincentt-Refusal: cli_upgrade_required`). The CLI never
+// compares versions itself: it renders what it was told, with its own version
+// read from its own manifest, and it never prints the platform's `message`.
+import { clientVersion } from "./clientHeader.js";
+export const UPGRADE_REQUIRED_STATUS = 426;
+export const UPGRADE_REQUIRED_CODE = "cli_upgrade_required";
+/** A constant, never built from the wire. `@latest` is always at or above any floor. */
+export const INSTALL_COMMAND = "npm install -g @vincentt-xr/cli@latest";
+export class UpgradeRequiredError extends Error {
+    minimum;
+    declared;
+    status = UPGRADE_REQUIRED_STATUS;
+    constructor(minimum, declared) {
+        super("This vincentt CLI is too old for Vincentt.");
+        this.minimum = minimum;
+        this.declared = declared;
+        this.name = "UpgradeRequiredError";
+    }
+}
+const STRICT_SEMVER = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+const CATEGORIES = new Set(["below", "missing", "unparseable"]);
+/** The floor as the platform sent it, or undefined unless it is strict X.Y.Z. */
+export function parseMinimum(raw) {
+    return typeof raw === "string" && STRICT_SEMVER.test(raw) ? raw : undefined;
+}
+/** A refusal category outside the closed set reads as absent. */
+export function parseDeclared(raw) {
+    return typeof raw === "string" && CATEGORIES.has(raw)
+        ? raw
+        : undefined;
+}
+/**
+ * Every api client calls this on a response before any other refusal arm,
+ * including rejectAuthExpired. Any 426 is the version refusal, whatever code
+ * its body carries.
+ */
+export async function rejectUpgradeRequired(res) {
+    if (res.status !== UPGRADE_REQUIRED_STATUS)
+        return;
+    let detail = {};
+    try {
+        const body = (await res.json());
+        if (typeof body?.detail === "object" && body.detail !== null) {
+            detail = body.detail;
+        }
+    }
+    catch {
+        // A refusal with no readable body is still the refusal, with no facts.
+    }
+    throw new UpgradeRequiredError(parseMinimum(detail.minimum), parseDeclared(detail.declared));
+}
+const WIDTH = 79;
+/** Wrap one sentence to the CLI's line width under a two-space indent. */
+function wrap(text, indent = "  ") {
+    const out = [];
+    let line = "";
+    for (const word of text.split(" ")) {
+        const next = line === "" ? word : `${line} ${word}`;
+        if (line !== "" && indent.length + next.length > WIDTH) {
+            out.push(indent + line);
+            line = word;
+        }
+        else {
+            line = next;
+        }
+    }
+    if (line !== "")
+        out.push(indent + line);
+    return out;
+}
+/**
+ * The variant comes from facts the CLI holds: its own manifest version, and the
+ * platform's refusal category. An absent or unknown category is the first row.
+ */
+function variantOf(facts, own) {
+    if (own === "unknown")
+        return "own_unknown";
+    if (facts.declared === "missing" || facts.declared === "unparseable") {
+        return "not_received";
+    }
+    return "too_old";
+}
+function needs(facts) {
+    return facts.minimum
+        ? `Vincentt needs ${facts.minimum} or later.`
+        : "Vincentt needs a newer one.";
+}
+function factLines(facts, own, variant) {
+    switch (variant) {
+        case "own_unknown":
+            return [
+                "  It couldn't read its own version, so Vincentt treats it as too old.",
+                `  ${needs(facts)}`,
+            ];
+        case "not_received":
+            return facts.minimum
+                ? [
+                    `  This is ${own}. Vincentt needs ${facts.minimum} or later, so upgrading will not fix this.`,
+                ]
+                : [`  This is ${own}, so upgrading will not fix this.`];
+        case "too_old":
+            return [`  This is ${own}. ${needs(facts)}`];
+    }
+}
+function headline(variant) {
+    switch (variant) {
+        case "own_unknown":
+            return "✗ This vincentt CLI couldn't tell Vincentt which version it is.";
+        case "not_received":
+            return "✗ Vincentt received no version from this vincentt CLI, so it refused it.";
+        case "too_old":
+            return "✗ This vincentt CLI is too old for Vincentt.";
+    }
+}
+function notDone(arm) {
+    switch (arm.kind) {
+        case "generic":
+            return ["  Nothing was changed, and your sign-in is fine."];
+        case "create":
+            return wrap(arm.dir
+                ? `The project is in ${arm.dir} and runs locally. No address was reserved, and your sign-in is fine.`
+                : "The project is in this folder and runs locally. No address was reserved, and your sign-in is fine.");
+        case "login":
+            return ["  No sign-in was created, and no other machine was signed out."];
+        case "login_saved":
+            return ["  This machine is signed in, and the sign-in is saved.", ...arm.evictionLines];
+        case "publish":
+            if (arm.address === undefined) {
+                return ["  Nothing was published, and your sign-in is fine."];
+            }
+            return wrap(arm.stillServing !== undefined
+                ? `Nothing was published. ${arm.address} is still serving v${arm.stillServing}, and your sign-in is fine.`
+                : `Nothing was published. ${arm.address} is unchanged, and your sign-in is fine.`);
+        case "preview_start":
+            return ["  No preview was started, and your sign-in is fine."];
+    }
+}
+function thenLine(arm) {
+    switch (arm.kind) {
+        case "generic":
+        case "login_saved":
+            return "  Then run the same command again.";
+        case "create":
+            return arm.dir
+                ? `  Then, inside ${arm.dir}, register it:  vincentt create`
+                : "  Then register it:  vincentt create";
+        case "login":
+            return "  Then sign in again:  vincentt login";
+        case "publish":
+            return "  Then publish again:  vincentt publish";
+        case "preview_start":
+            return "  Then start it again:  vincentt preview";
+    }
+}
+function remedy(variant) {
+    if (variant === "not_received")
+        return "  Report it:  vincentt dx --send";
+    const label = variant === "own_unknown" ? "Reinstall:" : "Upgrade:";
+    return `  ${label}  ${INSTALL_COMMAND}`;
+}
+/** Flow L22: the version refusal on any verb, in the arm that knows where it landed. */
+export function upgradeRefusalLines(facts, arm = { kind: "generic" }, own = clientVersion()) {
+    const variant = variantOf(facts, own);
+    const out = [
+        "",
+        headline(variant),
+        "",
+        ...factLines(facts, own, variant),
+        ...notDone(arm),
+        "",
+        remedy(variant),
+    ];
+    if (variant !== "not_received")
+        out.push(thenLine(arm));
+    if (arm.kind === "preview_start") {
+        out.push("", `  Your local dev loop does not need an upgrade. Run \`${arm.devCommand}\` and open`, `  ${arm.localUrl} on this machine. The camera works there.`);
+    }
+    out.push("");
+    return out;
+}
+/**
+ * Flow L20 (h): a running preview the platform refused, on the heartbeat or on a
+ * reconnect dial. One screen for both arrival paths.
+ */
+export function previewTooOldLines(facts, own = clientVersion()) {
+    const variant = variantOf(facts, own);
+    const facts1 = variant === "own_unknown"
+        ? [
+            "  It couldn't read its own version, so Vincentt treats it as too old.",
+            `  ${needs(facts).replace(/\.$/, "")}, so the link no longer works.`,
+        ]
+        : variant === "not_received"
+            ? [
+                `  This is ${own}. ${needs(facts).replace(/\.$/, "")}, so upgrading will not fix this.`,
+                "  The link no longer works.",
+            ]
+            : [
+                `  This is ${own}. ${needs(facts).replace(/\.$/, "")}, so the link no longer works.`,
+            ];
+    const out = [
+        "",
+        "✗ Preview ended. This vincentt CLI is now too old for Vincentt.",
+        "",
+        ...facts1,
+        "  Nothing is wrong with your project, and your sign-in is fine.",
+        "",
+        remedy(variant),
+    ];
+    if (variant !== "not_received") {
+        out.push("  Then start a new one, which gets a new link:  vincentt preview");
+    }
+    out.push("");
+    return out;
+}

package/dist/tunnel/caps.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Capability negotiation, the client's half (f3 §2.2.2). The client offers on
+ * every dial; the edge answers the agreed set on the 101, or omits the header
+ * when it agreed nothing. The agreed set fixes this connection's decode grammar.
+ */
+import { type CapSet, type TunnelCap } from "./cbor.js";
+/** Lower-case: Node lower-cases response header names. */
+export declare const CAPS_HEADER = "x-vincentt-tunnel-caps";
+/** Every element this client understands, offered on every dial. */
+export declare const OFFERED_CAPS: readonly TunnelCap[];
+export declare const OFFERED_CAPS_VALUE: string;
+/**
+ * The agreed set from a 101, or null for a protocol violation: the header
+ * duplicated, an array, ungrammatical, or naming a token this client did not
+ * offer. Absent is the base protocol, never a violation. `rawHeaders` is
+ * consulted because Node joins a duplicated header into one comma list, which
+ * would otherwise read as a grammatical value.
+ */
+export declare function parseAgreedCaps(value: unknown, rawHeaders: readonly string[] | undefined, offered?: readonly TunnelCap[]): CapSet | null;