@vincentt-xr/cli 0.18.3 → 0.19.0

package/MIGRATION.md

@@ -3,12 +3,26 @@
 Per version, newest first. Read by the platform's own version surface and served to
 creators' agents. Accurate or absent, never speculative (B-F5-2).
 
+## 0.19.0
+
+required: false
+No action required for a project made from the Vincentt template. Behaviour that changed:
+- The platform caps how many previews one person runs at once (5 by default, across every workspace; a preview that is still connecting counts, viewers never do). Re-running `vincentt preview` in a folder that already has a preview is never refused by the cap.
+- `vincentt preview` past the preview cap exits 1, starts nothing and stops nothing, and says how many previews are running and how to stop one: Ctrl-C where it runs, `vincentt preview --stop` in its folder, or Stop on its project's Preview tab in the console.
+- A preview refusal the CLI does not recognise prints the platform's own message instead of "A preview is already running for this folder."
+- `vincentt preview` with no `vincentt.json`, `--port` or `--dev-command` starts the project's `dev` script on a free port, passed to it as `PORT`, instead of 5173, and never reuses a server it finds already listening. Two previews at once, or another server already on 5173, no longer share one app. The settings banner shows the chosen port. A port from `--port` or `vincentt.json` is kept, and a server already listening there is still reused.
+- A preview answers 404 for any path segment shaped like a Windows short name (one to six characters, then `~` and a digit, such as `GIT~1` or `ENVLOC~1`), on every platform. On Windows these names open the dotted files the preview already hides. Bundler chunk names such as `vendors~main` are unaffected.
+- The preview tunnel client is part of the CLI itself instead of being loaded from `@vincentt-xr/harness`. The preview behaves the same, and it works with any harness version a project has installed.
+- A preview answers 404 for files and folders named like credentials, with no opt-out: `credentials.json`, `service-account*.json`, `*firebase-adminsdk*.json`, `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.p8`, `*.ppk`, `id_rsa*`, `id_dsa*`, `id_ed25519*`, `id_ecdsa*`, `*.jks`, `*.keystore`, `*.env`, `*.tfstate`, `*.tfvars`, and their `~` or `.bak` backups, in any letter case. An app asset with one of these names (for example a `.key` file) needs a new name to load in a preview.
+- A preview also refuses a Windows stream name, a name with trailing dots or spaces, and a query or fragment carrying a parent-folder step, a backslash or an encoded slash. The 404 advisory names the path decoded, without control or bidirectional-override characters, and now ends `A preview never serves hidden or credential files from your project.`
+- `vincentt login` and the report consent prompt open a browser only for an `https:` address, or an `http:` address on `localhost`, `127.0.0.1` or `[::1]`; anything else is printed but not opened. On Windows the browser opens through `rundll32` instead of `cmd`.
+
 ## 0.18.3
 
 required: false
 No action required when the preview and the commands reading it (`logs`, `feedback`, `preview --stop`) come from the same CLI version. Behaviour that changed:
-- The local preview relay refuses web pages other than the preview itself. It answers only requests whose Host is `127.0.0.1:<port>` or `localhost:<port>`, accepts the diagnostics socket and feedback posts only from the preview's own address (or from a client that sends no Origin), and refuses a POST that is not `application/json` with 415.
-- The relay's diagnostics read and feedback long-poll now require a per-session token, which the preview writes to `.vincentt/relay.json` (now readable by the owner only). The CLI's own commands send it; a direct request to `/query` or `feedback/next` without the `x-vincentt-relay-token` header is refused with 401. A command from CLI 0.18.2 or older cannot read a preview started by this version, and the reverse still works.
+- The local preview relay refuses web pages other than the preview itself. It answers only requests whose Host is `127.0.0.1:<port>` or `localhost:<port>`, accepts the diagnostics socket and feedback posts only from the preview's own address (or from a client that sends no Origin), and refuses a POST whose content type is not JSON with 415.
+- The relay's diagnostics read and feedback long-poll now require a per-session token, which the preview writes to the project's relay record (now readable by the owner only). The CLI's own commands send it; a direct diagnostics or feedback request without the `x-vincentt-relay-token` header is refused with 401. A command from CLI 0.18.2 or older cannot read a preview started by this version, and the reverse still works.
 - `vincentt relay` prints the token it requires and accepts `--origin <url>` for a page it should accept; without it, only pages served from localhost or 127.0.0.1 can connect.
 
 ## 0.18.2

package/dist/cli/index.js

@@ -37,13 +37,14 @@ import { USAGE_TEXT } from "./usage-text.js";
 import { PreviewUi } from "../preview/command.js";
 import { httpRelayClient } from "../lib/diagnostics.js";
 import { readLivePreview, relayInfoDir } from "../lib/relayInfo.js";
-import { attachedToRunning, mintRateLimited, noDiagnosticsStatic, notSignedIn, previewConflict, settingsBanner, startBlock, } from "../preview/copy.js";
+import { attachedToRunning, mintRateLimited, noDiagnosticsStatic, notSignedIn, previewConflict, previewUserLimitRefused, settingsBanner, startBlock, } from "../preview/copy.js";
+import { chooseDevPort } from "../preview/devPort.js";
 import { isPortListening } from "../preview/net.js";
 import { readSettings, resolveSettings, SettingsError, TEMPLATE_DEFAULTS, validateField, } from "../lib/settings.js";
 import { settingsRefusal, sourceWords } from "../lib/settingsCopy.js";
 import { listsHarness } from "../lib/template.js";
 import { renderTerminalQr, shouldRenderQr } from "../preview/qr.js";
-import { PreviewConflictError, PreviewLimitError, PreviewRateLimitedError, } from "../preview/api.js";
+import { PreviewConflictError, PreviewLimitError, PreviewRateLimitedError, PreviewUserLimitError, } from "../preview/api.js";
 import { previewLimitRefused, resolveCountLimit, } from "../shared/countLimit.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
 import * as feedbackCopy from "../lib/feedbackCopy.js";
@@ -531,14 +532,16 @@ async function preview() {
         return;
     }
     const devCommand = settings.devCommand.value;
-    const devPort = settings.devPort.value;
+    const { port: devPort, fresh: devPortFresh } = await chooseDevPort(settings);
+    // What the creator gets running the dev command by hand, without PORT.
+    const handRunUrl = `http://localhost:${settings.devPort.value}`;
     const localUrl = `http://localhost:${devPort}`;
     for (const l of settingsBanner({
         devCommand,
         devCommandSource: sourceWords(settings.devCommand),
         devPort,
         devPortSource: sourceWords(settings.devPort),
-        reused: await isPortListening(devPort),
+        reused: devPortFresh ? false : await isPortListening(devPort),
     })) {
         console.log(l);
     }
@@ -549,7 +552,7 @@ async function preview() {
     // The gate is LOCAL and NOTHING IS ATTEMPTED: no spinner, no partial mint, no
     // session left in `pending`. The command stops before it touches the network.
     if (!(await currentToken())) {
-        for (const l of notSignedIn(devCommand, localUrl))
+        for (const l of notSignedIn(devCommand, handRunUrl))
             console.log(l);
         process.exitCode = EXIT.NOT_AUTHENTICATED;
         return;
@@ -607,6 +610,7 @@ async function preview() {
     try {
         const started = await previewStart(cwd, (m) => console.error(`[preview] ${m}`), {
             appPort: devPort,
+            appPortFresh: devPortFresh,
             devCommand,
             onHiddenPath: (p) => ui.hiddenPath(p),
             appStdio: has("--verbose") ? "inherit" : "ignore",
@@ -842,6 +846,8 @@ function previewFailureLines(err, local) {
     if (err instanceof PreviewLimitError) {
         return previewLimitRefused(resolveCountLimit(err.detail, local));
     }
+    if (err instanceof PreviewUserLimitError)
+        return previewUserLimitRefused(err.detail);
     if (err instanceof PreviewConflictError)
         return previewConflict();
     if (err instanceof ProjectUnreachableError) {

package/dist/cli/usage-text.js

@@ -58,7 +58,7 @@ export const USAGE_TEXT = `Vincentt CLI: the local-first AR dev loop\n\n` +
     `                       [--port <n>] [--dev-command <cmd>] [--tester <id>]\n` +
     `                       [--no-qr] [--stop]\n` +
     `                       Runs dev.command and forwards dev.port from vincentt.json,\n` +
-    `                       else npm run dev on 5173.\n` +
+    `                       else npm run dev on a free port (passed as PORT).\n` +
     `                       Re-running prints the live link; --restart mints a new one.\n\n` +
     // f16. HELP TEACHES THE CANONICAL VERBS ONLY: `add` and `remove` are accepted
     // as silent aliases and are deliberately ABSENT here, because help, docs and

package/dist/lib/terminalText.d.ts

@@ -1,3 +1,5 @@
 export declare const CONTROL_CHARS: RegExp;
 /** Each C0/C1 control character as a visible `\uXXXX`, so nothing is hidden or redrawn. */
 export declare function escapeControl(text: string): string;
+/** Text with every C0/C1 control and bidi override or isolate removed. */
+export declare function terminalSafe(text: string): string;

package/dist/lib/terminalText.js

@@ -8,3 +8,10 @@ const CONTROL_CHARS_G = /[\u0000-\u001f\u007f-\u009f]/g;
 export function escapeControl(text) {
     return text.replace(CONTROL_CHARS_G, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
 }
+// U+202A..U+202E (embeddings, overrides) and U+2066..U+2069 (isolates) can
+// reorder a terminal line, so a crafted name could disguise what it says.
+const BIDI_CONTROLS_G = /[\u202a-\u202e\u2066-\u2069]/g;
+/** Text with every C0/C1 control and bidi override or isolate removed. */
+export function terminalSafe(text) {
+    return text.replace(CONTROL_CHARS_G, "").replace(BIDI_CONTROLS_G, "");
+}

package/dist/login/pkceLogin.d.ts

@@ -29,11 +29,17 @@ export declare class LoginTimeoutError extends Error {
 export declare class LoginCallbackError extends Error {
     constructor(message: string);
 }
-/** The platform command + args to open `url` in the default browser. */
+/**
+ * The platform command + args to open `url` in the default browser. On win32
+ * the URL goes to `rundll32` as one argument, so no command interpreter parses
+ * it and `&` cannot split the command.
+ */
 export declare function browserOpenCommand(url: string, platform?: string): {
     cmd: string;
     args: string[];
 };
+/** Only `https:`, or `http:` on a loopback host, is ever handed to the OS opener. */
+export declare function isLaunchableUrl(url: string): boolean;
 type SpawnLike = (cmd: string, args: string[], opts: {
     stdio: "ignore";
     detached: boolean;

package/dist/login/pkceLogin.js

@@ -30,14 +30,35 @@ export class LoginCallbackError extends Error {
         this.name = "LoginCallbackError";
     }
 }
-/** The platform command + args to open `url` in the default browser. */
+/**
+ * The platform command + args to open `url` in the default browser. On win32
+ * the URL goes to `rundll32` as one argument, so no command interpreter parses
+ * it and `&` cannot split the command.
+ */
 export function browserOpenCommand(url, platform = process.platform) {
-    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
-    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-    return { cmd, args };
+    if (platform === "win32") {
+        return { cmd: "rundll32", args: ["url.dll,FileProtocolHandler", url] };
+    }
+    return { cmd: platform === "darwin" ? "open" : "xdg-open", args: [url] };
+}
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "localhost"]);
+/** Only `https:`, or `http:` on a loopback host, is ever handed to the OS opener. */
+export function isLaunchableUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === "https:")
+        return true;
+    return parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname);
 }
 /** Launch the browser via an injected spawn; a throw is swallowed (fallback = the printed URL). */
 export function launchBrowser(url, spawn, platform) {
+    if (!isLaunchableUrl(url))
+        return;
     const { cmd, args } = browserOpenCommand(url, platform);
     try {
         const child = spawn(cmd, args, { stdio: "ignore", detached: true });

package/dist/preview/api.d.ts

@@ -46,6 +46,21 @@ export declare class PreviewLimitError extends BackendError {
     readonly detail: CountLimitDetail;
     constructor(message: string, detail: CountLimitDetail);
 }
+/** The refusal body's detail on `preview_user_limit`. */
+export interface PreviewUserLimitDetail {
+    limit?: string;
+    count?: number;
+    ceiling?: number;
+}
+/**
+ * The caller already runs as many previews as one person may, across every
+ * workspace (`409 preview_user_limit`). A THIRD 409 on the mint route, told
+ * apart by its code. Nothing was ended; the remedy is stopping a preview.
+ */
+export declare class PreviewUserLimitError extends BackendError {
+    readonly detail: PreviewUserLimitDetail;
+    constructor(message: string, detail: PreviewUserLimitDetail);
+}
 /**
  * The session is gone — `preview_session_ended`, the CLI's terminal branch.
  *

package/dist/preview/api.js

@@ -47,6 +47,19 @@ export class PreviewLimitError extends BackendError {
         this.name = "PreviewLimitError";
     }
 }
+/**
+ * The caller already runs as many previews as one person may, across every
+ * workspace (`409 preview_user_limit`). A THIRD 409 on the mint route, told
+ * apart by its code. Nothing was ended; the remedy is stopping a preview.
+ */
+export class PreviewUserLimitError extends BackendError {
+    detail;
+    constructor(message, detail) {
+        super(message, 409);
+        this.detail = detail;
+        this.name = "PreviewUserLimitError";
+    }
+}
 /**
  * The session is gone — `preview_session_ended`, the CLI's terminal branch.
  *
@@ -130,7 +143,20 @@ export async function mintPreviewSession(cfg, projectId, key, fetchImpl = apiFet
             if (body.code === "preview_limit") {
                 throw new PreviewLimitError(body.message ?? "this organization is at its preview limit", body.detail ?? {});
             }
-            throw new PreviewConflictError(body.message ?? "a preview is already running for this folder");
+            if (body.code === "preview_user_limit") {
+                const d = body.detail ?? {};
+                throw new PreviewUserLimitError(body.message ?? "you already have the most previews one person can run at once", {
+                    limit: typeof d.limit === "string" ? d.limit : undefined,
+                    count: typeof d.count === "number" ? d.count : undefined,
+                    ceiling: typeof d.ceiling === "number" ? d.ceiling : undefined,
+                });
+            }
+            if (body.code === "preview_session_conflict" || body.code === undefined) {
+                throw new PreviewConflictError(body.message ?? "a preview is already running for this folder");
+            }
+            // An unrecognised refusal prints the server's own words rather than the
+            // folder-conflict screen, so a future 409 is never misread as a conflict.
+            throw new BackendError(body.message ?? `could not start a preview (409)`, 409);
         }
         throw new BackendError(body.message ?? `could not start a preview (${res.status})`, res.status);
     }

package/dist/preview/command.d.ts

@@ -1,5 +1,5 @@
 import type { DiagEvent } from "@vincentt-xr/harness/events";
-import type { TunnelState, UAClass } from "@vincentt-xr/harness/tunnel";
+import type { TunnelState, UAClass } from "../tunnel/index.js";
 import type { EventTags } from "../relay/server.js";
 import type { PreviewEndReason } from "./runner.js";
 export interface PreviewUiDeps {

package/dist/preview/copy.d.ts

@@ -51,7 +51,7 @@ export declare function deviceArrived(descriptor: string): string;
  * The window's length is deliberately not printed.
  */
 export declare function noDiagnosticsRuntime(descriptor: string): string[];
-/** Flow P1 — the proxy refused a hidden path. Once per preview, naming the first. */
+/** Flow P1 — the proxy refused a hidden or credential path. Once per preview, naming the first. */
 export declare function hiddenPathRefused(requestPath: string): string;
 /** Flow L16 — `--viewer`, a second terminal, not a second preview. */
 export declare function followingBlock(label: string, descriptor: string): string[];
@@ -267,3 +267,16 @@ export declare function mintRateLimited(retryAfterSec: number): string[];
 export declare function approxWait(seconds: number): string;
 /** The conflict a supersede lost (409). Rare: the mint supersedes first. */
 export declare function previewConflict(): string[];
+/**
+ * The per-person preview cap, refused at mint (`409 preview_user_limit`, B-F3-9).
+ *
+ * The count and the cap come only from the refusal body, never from a number
+ * compiled in: the cap is an operator setting. It names no workspace, plan or
+ * price, because no plan raises it. "Still running" comes first among the facts
+ * for the same reason as the org-ceiling screen: the command that refused is the
+ * one that starts previews, so a creator assumes it took something down.
+ */
+export declare function previewUserLimitRefused(d: {
+    count?: number;
+    ceiling?: number;
+}): string[];

package/dist/preview/copy.js

@@ -17,7 +17,7 @@
 // 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.
 /** Flow L13 — the start block. */
-import { escapeControl } from "../lib/terminalText.js";
+import { escapeControl, terminalSafe } from "../lib/terminalText.js";
 export function startBlock(i) {
     const out = [
         "",
@@ -128,9 +128,9 @@ export function noDiagnosticsRuntime(descriptor) {
         "  stopped before that line ran.",
     ];
 }
-/** Flow P1 — the proxy refused a hidden path. Once per preview, naming the first. */
+/** Flow P1 — the proxy refused a hidden or credential path. Once per preview, naming the first. */
 export function hiddenPathRefused(requestPath) {
-    return `! Answered 404 for ${requestPath}. A preview never serves hidden files from your project.`;
+    return `! Answered 404 for ${terminalSafe(requestPath)}. A preview never serves hidden or credential files from your project.`;
 }
 /** Flow L16 — `--viewer`, a second terminal, not a second preview. */
 export function followingBlock(label, descriptor) {
@@ -572,3 +572,37 @@ export function previewConflict() {
         "",
     ];
 }
+/**
+ * The per-person preview cap, refused at mint (`409 preview_user_limit`, B-F3-9).
+ *
+ * The count and the cap come only from the refusal body, never from a number
+ * compiled in: the cap is an operator setting. It names no workspace, plan or
+ * price, because no plan raises it. "Still running" comes first among the facts
+ * for the same reason as the org-ceiling screen: the command that refused is the
+ * one that starts previews, so a creator assumes it took something down.
+ */
+export function previewUserLimitRefused(d) {
+    const { count, ceiling } = d;
+    const known = typeof count === "number" && typeof ceiling === "number" && ceiling > 0;
+    let first = "✗ You already have the most previews one person can run at once.";
+    if (known && count > ceiling) {
+        first = `✗ You already have ${count} previews running. One person can run ${ceiling} at once.`;
+    }
+    else if (known && count === ceiling) {
+        first = `✗ You already have ${count} previews running, the most one person can run at once.`;
+    }
+    return [
+        "",
+        first,
+        "",
+        "  Every preview that was running is still running. This one did not start.",
+        "  A preview that is still connecting counts too. Viewers never count.",
+        "",
+        "  To start this one, stop a preview you no longer need:",
+        "    press Ctrl-C where it runs, or run  vincentt preview --stop  in its folder,",
+        "    or press Stop on its project's Preview tab in the console.",
+        "",
+        "  Nothing was started.",
+        "",
+    ];
+}

package/dist/preview/devPort.d.ts

@@ -0,0 +1,17 @@
+import type { ResolvedSettings } from "../lib/settings.js";
+export interface DevPortChoice {
+    port: number;
+    /**
+     * The port was picked for this preview. Nothing else may answer there, so a
+     * listener found on it is never reused as the app.
+     */
+    fresh: boolean;
+}
+/**
+ * The port the preview's dev server runs on. Only the template default is
+ * replaced with a free port (passed to the dev command as PORT), so two
+ * previews never share one. A port from `--port` or `vincentt.json`, or any
+ * port paired with a custom dev command, is kept: many outside dev servers
+ * ignore PORT and listen where they were told.
+ */
+export declare function chooseDevPort(settings: Pick<ResolvedSettings, "devCommand" | "devPort">, pickPort?: () => Promise<number>): Promise<DevPortChoice>;

package/dist/preview/devPort.js

@@ -0,0 +1,14 @@
+import { getFreePort } from "./net.js";
+/**
+ * The port the preview's dev server runs on. Only the template default is
+ * replaced with a free port (passed to the dev command as PORT), so two
+ * previews never share one. A port from `--port` or `vincentt.json`, or any
+ * port paired with a custom dev command, is kept: many outside dev servers
+ * ignore PORT and listen where they were told.
+ */
+export async function chooseDevPort(settings, pickPort = getFreePort) {
+    if (settings.devPort.source === "default" && settings.devCommand.source === "default") {
+        return { port: await pickPort(), fresh: true };
+    }
+    return { port: settings.devPort.value, fresh: false };
+}

package/dist/preview/proxy.d.ts

@@ -36,17 +36,24 @@ export declare function proxyWs(req: IncomingMessage, socket: Duplex, head: Buff
 export declare function relayRoute(url: string, harnessPath: string, kind: "http" | "upgrade"): "relay" | "refuse" | "app";
 /**
  * Whether the front proxy must answer 404 itself for this app-route URL, so a
- * file-server dev tool serving the repo root cannot hand `/.env`, `/.git/config`
- * or the binding to any holder of a preview link.
+ * file-server dev tool serving the repo root cannot hand `/.env`, `/.git/config`,
+ * the binding or a credential file to any holder of a preview link.
  *
  * The path is decoded once, and an encoded `/` or `\` is refused outright (a
- * separator the dev server would split on and this check would not). A segment
- * still carrying an encoded dot after that one decode is judged as the dev
- * server would read it after a second decode, so `%252eenv` cannot slip past.
- * `.` and `..` segments are always refused, which is what makes the `/@fs/`
- * text containment below real containment.
+ * separator the dev server would split on and this check would not). The query
+ * and fragment may not carry a traversal or a separator either, because some
+ * dev servers resolve a file from a query parameter. A segment still carrying
+ * an encoded character after that one decode is judged as the dev server would
+ * read it after a second decode, so `%252eenv` cannot slip past; a second decode
+ * that throws is done leniently, never treated as "not hidden". `.` and `..`
+ * segments are always refused, which is what makes the `/@fs/` text containment
+ * below real containment.
  *
- * `projectRoot` is the realpath of the binding directory, taken once at preview
- * start; inside-ness is a segment-aligned text prefix, with no disk call.
+ * Three rules read the checked segments: the dot rule (raw name), and the
+ * short-name and credential-name rules (normalized name, see `normalizedName`).
+ *
+ * `projectRoot` is the realpath of the binding directory with forward slashes,
+ * taken once at preview start; inside-ness is a segment-aligned text prefix,
+ * with no disk call.
  */
 export declare function isHiddenAppPath(url: string, projectRoot: string): boolean;

package/dist/preview/proxy.js

@@ -138,23 +138,34 @@ export function relayRoute(url, harnessPath, kind) {
 }
 /**
  * Whether the front proxy must answer 404 itself for this app-route URL, so a
- * file-server dev tool serving the repo root cannot hand `/.env`, `/.git/config`
- * or the binding to any holder of a preview link.
+ * file-server dev tool serving the repo root cannot hand `/.env`, `/.git/config`,
+ * the binding or a credential file to any holder of a preview link.
  *
  * The path is decoded once, and an encoded `/` or `\` is refused outright (a
- * separator the dev server would split on and this check would not). A segment
- * still carrying an encoded dot after that one decode is judged as the dev
- * server would read it after a second decode, so `%252eenv` cannot slip past.
- * `.` and `..` segments are always refused, which is what makes the `/@fs/`
- * text containment below real containment.
+ * separator the dev server would split on and this check would not). The query
+ * and fragment may not carry a traversal or a separator either, because some
+ * dev servers resolve a file from a query parameter. A segment still carrying
+ * an encoded character after that one decode is judged as the dev server would
+ * read it after a second decode, so `%252eenv` cannot slip past; a second decode
+ * that throws is done leniently, never treated as "not hidden". `.` and `..`
+ * segments are always refused, which is what makes the `/@fs/` text containment
+ * below real containment.
  *
- * `projectRoot` is the realpath of the binding directory, taken once at preview
- * start; inside-ness is a segment-aligned text prefix, with no disk call.
+ * Three rules read the checked segments: the dot rule (raw name), and the
+ * short-name and credential-name rules (normalized name, see `normalizedName`).
+ *
+ * `projectRoot` is the realpath of the binding directory with forward slashes,
+ * taken once at preview start; inside-ness is a segment-aligned text prefix,
+ * with no disk call.
  */
 export function isHiddenAppPath(url, projectRoot) {
-    const raw = (url.split("#")[0] ?? "").split("?")[0] ?? "";
+    const [beforeHash = "", ...hash] = url.split("#");
+    const [raw = "", ...query] = beforeHash.split("?");
     if (/%(2f|5c)/i.test(raw) || raw.includes("\\"))
         return true;
+    const tail = [...query, ...hash].join("?");
+    if (/%(2f|5c)/i.test(tail) || tail.includes("\\") || tail.includes("/.."))
+        return true;
     let decoded;
     try {
         decoded = decodeURIComponent(raw);
@@ -168,22 +179,93 @@ export function isHiddenAppPath(url, projectRoot) {
     const checked = checkedSegmentIndexes(segments, projectRoot);
     for (const i of checked) {
         const seg = segments[i];
-        if (!startsWithDot(seg))
-            continue;
-        if (isAllowedDotSegment(segments, i))
-            continue;
-        return true;
+        const spellings = [seg, secondDecode(seg)];
+        if (spellings.some((s) => s.startsWith(".")) && !isAllowedDotSegment(segments, i)) {
+            return true;
+        }
+        for (const s of spellings) {
+            const name = normalizedName(s);
+            if (name === REFUSE)
+                return true;
+            if (SHORT_NAME.test(name) || isCredentialName(name))
+                return true;
+        }
     }
     return false;
 }
-function startsWithDot(segment) {
-    if (segment.startsWith("."))
-        return true;
+/** The segment as a second decode would read it; lenient when that decode throws. */
+function secondDecode(segment) {
+    if (!/%[0-9a-f]{2}/i.test(segment))
+        return segment;
     try {
-        return decodeURIComponent(segment).startsWith(".");
+        return decodeURIComponent(segment);
     }
     catch {
-        return false;
+        return segment.replace(/(?:%[0-9a-f]{2})+/gi, (run) => {
+            try {
+                return decodeURIComponent(run);
+            }
+            catch {
+                return run.replace(/%([0-9a-f]{2})/gi, (_, h) => String.fromCharCode(parseInt(h, 16)));
+            }
+        });
+    }
+}
+const REFUSE = Symbol("refuse");
+/**
+ * The name a Windows or case-insensitive file system would open for this
+ * segment: a stream suffix (`:$`) is refused outright, the rest is cut at the
+ * first colon (so `/@fs/C:/...` and `virtual:` modules still work), trailing
+ * dots and spaces are dropped (Windows resolves `server.pem. .` to `server.pem`),
+ * and compatibility and case forms are folded.
+ */
+function normalizedName(segment) {
+    if (segment.includes(":$"))
+        return REFUSE;
+    const beforeColon = segment.split(":")[0] ?? "";
+    return beforeColon.replace(/[. ]+$/, "").normalize("NFKC").toUpperCase().toLowerCase();
+}
+/**
+ * A Windows 8.3 short name (`GIT~1`, `CREDEN~1.JSO`) opens the long-named file
+ * it stands for, and its short form carries no leading dot, so `/GIT~1/config`
+ * would read `.git/config` past the dot rule. Refused on every platform: the
+ * proxy can front a Windows file system from any client.
+ */
+const SHORT_NAME = /^[^~]{1,6}~[0-9]/;
+/** D-Preview-hides-credential-files: hard-coded, no opt-out. `*` is any run of characters. */
+const CREDENTIAL_NAMES = Object.freeze([
+    "credentials.json",
+    "service-account*.json",
+    "*firebase-adminsdk*.json",
+    "*.pem",
+    "*.key",
+    "*.p12",
+    "*.pfx",
+    "*.p8",
+    "*.ppk",
+    "id_rsa*",
+    "id_dsa*",
+    "id_ed25519*",
+    "id_ecdsa*",
+    "*.jks",
+    "*.keystore",
+    "*.env",
+    "*.tfstate",
+    "*.tfvars",
+].map((glob) => new RegExp(`^${glob
+    .split("*")
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join(".*")}$`, "s")));
+/** A listed name, or one with backup endings (`~`, `.bak`) added, any number of times. */
+function isCredentialName(name) {
+    let candidate = name;
+    for (;;) {
+        if (CREDENTIAL_NAMES.some((re) => re.test(candidate)))
+            return true;
+        const stripped = candidate.replace(/(?:~|\.bak)$/, "");
+        if (stripped === candidate)
+            return false;
+        candidate = stripped;
     }
 }
 function checkedSegmentIndexes(segments, projectRoot) {

package/dist/preview/runner.d.ts

@@ -1,9 +1,15 @@
-import { type ControlKind, type TunnelState, type UAClass } from "@vincentt-xr/harness/tunnel";
+import { type ControlKind, type TunnelState, type UAClass } from "../tunnel/index.js";
 import type { DiagEvent } from "@vincentt-xr/harness/events";
 import { type EventTags } from "../relay/server.js";
 import { type ResolvedConfig } from "../shared/config.js";
 /** The path a 404 advisory names: the request's own path, without its query. */
 export declare function requestPathOf(url: string | undefined): string;
+/**
+ * The project root as the `/@fs/` check compares it: Vite writes `/@fs/C:/...`
+ * with forward slashes, so a Windows root holding backslashes would never match
+ * as inside, and a project under a dotted parent folder would get false 404s.
+ */
+export declare function hiddenPathRoot(realRoot: string): string;
 /** Why a preview ended. Each maps to exactly one screen (Flow L20/L21). */
 export type PreviewEndReason = "stopped"
 /**
@@ -57,8 +63,10 @@ export interface StartPreviewOptions {
     /** The API host + PAT. Resolved by the caller so the runner makes no policy. */
     config: ResolvedConfig;
     projectId: string;
-    /** App dev-serve port (default 5173). A server already here is REUSED. */
+    /** App dev-serve port (default 5173). A server already here is REUSED unless `appPortFresh`. */
     appPort?: number;
+    /** appPort was picked for this preview, so the dev command always starts there. */
+    appPortFresh?: boolean;
     relayPort?: number;
     frontPort?: number;
     /** Path routed to the relay instead of the app (default /__harness). */