@spacefast/common 0.0.5 → 0.0.6

package/dist/utils/query-keys.js

@@ -4,8 +4,11 @@ export const qk = {
     accountSessions: () => ["account", "sessions"],
     accountConnections: () => ["account", "connections"],
     accountInvitations: () => ["account", "invitations"],
-    apiTokens: () => ["api-tokens"],
+    // Results are team-filtered, so the team lands in the key; calling with no
+    // teamId yields the bare prefix (personal scope, and invalidate-all sweeps).
+    apiTokens: (teamId) => teamId === undefined ? ["api-tokens"] : ["api-tokens", teamId],
     agentAccounts: () => ["agent-accounts"],
+    myShelf: () => ["my-shelf"],
     mcpDashboard: () => ["mcp", "dashboard"],
     mcpApproval: (id) => ["mcp", "approval", id],
     // The teams LIST gets its own leaf so invalidating it never cascades into
@@ -31,13 +34,24 @@ export const qk = {
     spaceByRef: (teamRef, spaceRef) => ["spaces", "by-ref", teamRef, spaceRef],
     spaceVersions: (id) => ["spaces", id, "versions"],
     spaceCollaboration: (id) => ["spaces", id, "collaboration"],
+    spaceCollaborationEmbedConfig: (id) => ["spaces", id, "collaboration", "embed-config"],
     spaceAnnotations: (id) => ["spaces", id, "annotations"],
     spaceActivity: (id, limit) => ["spaces", id, "activity", limit],
     spaceDeployments: (id) => ["spaces", id, "deployments"],
     spaceTags: (id) => ["spaces", id, "tags"],
-    spaceTagVersion: (id, versionId) => ["spaces", id, "tags", "versions", versionId],
+    spaceTagVersion: (id, versionId) => ["spaces", id, "tags", versionId],
+    spaceTagDiff: (id, versionId) => ["spaces", id, "tags", versionId, "diff"],
+    spaceTagReleases: (id) => ["spaces", id, "tags", "releases"],
+    // The merged (system+team+space) read-only view; never a write base — see
+    // `fetchSpaceReleasedGraph` in apps/my/src/lib/space-queries.ts.
+    spaceTagsEffective: (id) => ["spaces", id, "tags", "effective"],
     build: (id) => ["builds", id],
-    buildLogs: (id) => ["builds", id, "logs"],
+    // Observers with different limits must not share a cache entry; calling with
+    // no limit yields the bare prefix for invalidating every limit at once.
+    buildLogs: (id, limit) => limit === undefined
+        ? ["builds", id, "logs"]
+        : ["builds", id, "logs", limit],
+    spaceBuilds: (id) => ["spaces", id, "builds"],
     spaceRepositoryConnection: (id, connectionType = "connected") => ["spaces", id, "repository-connection", connectionType],
     repositoryInstallations: (spaceId) => ["repository-connections", "installations", spaceId],
     repositoryInstallationRepositories: (installationId) => ["repository-connections", "installations", installationId, "repositories"],
@@ -47,7 +61,11 @@ export const qk = {
     webhook: (webhookId) => ["webhooks", webhookId],
     webhookDeliveries: (webhookId) => ["webhooks", webhookId, "deliveries"],
     spaceVersion: (id, versionId) => ["spaces", id, "versions", versionId],
-    spaceVersionAnnotations: (id, versionId, status = "open") => ["spaces", id, "versions", versionId, "annotations", status],
+    // Calling with no status yields the bare prefix, for invalidating every
+    // status-scoped annotations list at once.
+    spaceVersionAnnotations: (id, versionId, status) => status === undefined
+        ? ["spaces", id, "versions", versionId, "annotations"]
+        : ["spaces", id, "versions", versionId, "annotations", status],
     spaceVersionFiles: (id, versionId) => ["spaces", id, "versions", versionId, "files"],
     spaceVersionFile: (id, versionId, path) => ["spaces", id, "versions", versionId, "files", path],
     spaceVersionFileDirectUrl: (id, versionId, path) => ["spaces", id, "versions", versionId, "files", path, "direct-url"],
@@ -68,6 +86,11 @@ export const qk = {
     spaceCertificates: (id) => ["spaces", id, "runtime", "certificates"],
     spaceLogs: (id, kind) => ["spaces", id, "logs", kind],
     spaceAnalytics: (id, window) => ["spaces", id, "analytics", window],
+    spaceFirewall: (id) => ["spaces", id, "access", "firewall"],
+    spaceAccessViews: (id, since) => ["spaces", id, "access", "views", since ?? ""],
+    teamServiceTokens: (teamId) => ["teams", teamId, "access", "service-tokens"],
+    teamAccessDefaults: (teamId) => ["teams", teamId, "access", "defaults"],
+    teamAccessConnections: (teamId) => ["teams", teamId, "access", "connections"],
     domain: (teamId, ref) => ["teams", teamId, "domains", ref],
     domainDiagnostics: (teamId, domainId) => ["teams", teamId, "domains", domainId, "diagnostics"],
     domainDnsCapabilities: (domainId) => ["domains", domainId, "dns", "capabilities"],

package/dist/utils/runtime-paths.d.ts

@@ -2,6 +2,5 @@ export declare const SPACEFAST_RUNTIME_NAMESPACE: "/__spacefast";
 export declare const RUNTIME_MANAGEMENT_API_PATH: "/__spacefast/api.php";
 export declare const RUNTIME_UPLOAD_API_PATH: "/__spacefast/upload.php";
 export declare const RUNTIME_HEALTH_PATH: "/__spacefast/health.php";
-export declare const RUNTIME_ACCESS_CALLBACK_PATH: "/__spacefast/access-callback.php";
 export declare function runtimeManagementPath(suffix: string): string;
 export declare function runtimeUploadPath(params: URLSearchParams | Record<string, string>): string;

package/dist/utils/runtime-paths.js

@@ -2,7 +2,6 @@ export const SPACEFAST_RUNTIME_NAMESPACE = "/__spacefast";
 export const RUNTIME_MANAGEMENT_API_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/api.php`;
 export const RUNTIME_UPLOAD_API_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/upload.php`;
 export const RUNTIME_HEALTH_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/health.php`;
-export const RUNTIME_ACCESS_CALLBACK_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/access-callback.php`;
 export function runtimeManagementPath(suffix) {
     const route = normalizeRuntimeRoute(suffix);
     if (route === "/") {

package/dist/utils/runtime-upload-batch.d.ts

@@ -0,0 +1,18 @@
+import { Buffer } from "node:buffer";
+import { RUNTIME_UPLOAD_BATCH_MAX_BYTES, RUNTIME_UPLOAD_BATCH_MAX_FILES } from "./runtime-upload.js";
+import { type UploadTarget } from "./upload-session.js";
+export { RUNTIME_UPLOAD_BATCH_MAX_BYTES, RUNTIME_UPLOAD_BATCH_MAX_FILES };
+export type RuntimeBatchArchiveEntry = {
+    path: string;
+    getBytes(): Buffer | Promise<Buffer>;
+};
+export declare function runtimeBatchUploadUnsupported(error: unknown): boolean;
+export declare function batchTargetForUploadTarget(uploadId: string, target: UploadTarget): UploadTarget | null;
+export declare function tarPathParts(filePath: string): {
+    name: string;
+    prefix: string;
+} | null;
+export declare function tarEndSize(): number;
+export declare function tarEntrySize(path: string, size: number): number | null;
+export declare function tarPadding(size: number): number;
+export declare function tarArchive(entries: readonly RuntimeBatchArchiveEntry[], pathTooLongError: (path: string) => Error): Promise<Buffer<ArrayBuffer>>;

package/dist/utils/runtime-upload-batch.js

@@ -0,0 +1,90 @@
+import { Buffer } from "node:buffer";
+import { RUNTIME_UPLOAD_BATCH_MAX_BYTES, RUNTIME_UPLOAD_BATCH_MAX_FILES, } from "./runtime-upload.js";
+import { UploadTargetError } from "./upload-session.js";
+// Batch planning + tar-writing wire contract shared by the CLI and the control
+// plane's inline publish path. This is the sender half of the runtime's tar
+// batch parser (runtime/engine/admin/upload.php); any change here must stay in
+// lockstep with that file.
+export { RUNTIME_UPLOAD_BATCH_MAX_BYTES, RUNTIME_UPLOAD_BATCH_MAX_FILES };
+export function runtimeBatchUploadUnsupported(error) {
+    return error instanceof UploadTargetError && (error.status === 404 || error.status === 405);
+}
+export function batchTargetForUploadTarget(uploadId, target) {
+    const url = new URL(target.url);
+    if (!url.pathname.endsWith("/upload.php")) {
+        return null;
+    }
+    url.search = new URLSearchParams({ op: "batch", upload_id: uploadId }).toString();
+    return {
+        ...target,
+        path: "__spacefast_batch.tar",
+        method: "POST",
+        url: url.toString(),
+        headers: {
+            ...target.headers,
+            "content-type": "application/x-tar",
+        },
+    };
+}
+export function tarPathParts(filePath) {
+    if (Buffer.byteLength(filePath) <= 100) {
+        return { name: filePath, prefix: "" };
+    }
+    const segments = filePath.split("/");
+    const name = segments.pop() ?? "";
+    const prefix = segments.join("/");
+    if (!name || Buffer.byteLength(name) > 100 || Buffer.byteLength(prefix) > 155) {
+        return null;
+    }
+    return { name, prefix };
+}
+export function tarEndSize() {
+    return 1024;
+}
+export function tarEntrySize(path, size) {
+    if (!tarPathParts(path)) {
+        return null;
+    }
+    return 512 + size + tarPadding(size);
+}
+export function tarPadding(size) {
+    return (512 - (size % 512)) % 512;
+}
+export async function tarArchive(entries, pathTooLongError) {
+    const chunks = [];
+    for (const entry of entries) {
+        const parts = tarPathParts(entry.path);
+        if (!parts) {
+            throw pathTooLongError(entry.path);
+        }
+        const body = Buffer.from(await entry.getBytes());
+        const header = Buffer.alloc(512);
+        header.write(parts.name, 0, Math.min(100, Buffer.byteLength(parts.name)), "utf8");
+        header.write("0000644\0", 100, 8, "ascii");
+        header.write("0000000\0", 108, 8, "ascii");
+        header.write("0000000\0", 116, 8, "ascii");
+        header.write(body.length.toString(8).padStart(11, "0") + "\0", 124, 12, "ascii");
+        header.write("00000000000\0", 136, 12, "ascii");
+        header.fill(0x20, 148, 156);
+        header[156] = "0".charCodeAt(0);
+        header.write("ustar", 257, 5, "ascii");
+        header.write("00", 263, 2, "ascii");
+        if (parts.prefix) {
+            header.write(parts.prefix, 345, Math.min(155, Buffer.byteLength(parts.prefix)), "utf8");
+        }
+        let checksum = 0;
+        for (const byte of header) {
+            checksum += byte;
+        }
+        header.write(checksum.toString(8).padStart(6, "0"), 148, 6, "ascii");
+        header[154] = 0;
+        header[155] = 0x20;
+        chunks.push(header, body);
+        const padding = tarPadding(body.length);
+        if (padding > 0) {
+            chunks.push(Buffer.alloc(padding));
+        }
+    }
+    chunks.push(Buffer.alloc(tarEndSize()));
+    return Buffer.concat(chunks);
+}

package/dist/utils/runtime-upload.d.ts

@@ -1,4 +1,6 @@
 export declare const RUNTIME_UPLOAD_METHOD: "PUT";
+export declare const RUNTIME_UPLOAD_BATCH_MAX_FILES = 500;
+export declare const RUNTIME_UPLOAD_BATCH_MAX_BYTES: number;
 export declare function runtimeUploadCanonicalPath(path: string): string;
 export declare function runtimeUploadSessionBaseUrl(input: {
     baseUrl: string;

package/dist/utils/runtime-upload.js

@@ -1,5 +1,10 @@
 import { runtimeUploadPath } from "./runtime-paths.js";
 export const RUNTIME_UPLOAD_METHOD = "PUT";
+// Mirrors STATTIC_RUNTIME_UPLOAD_BATCH_MAX_FILES/_MAX_BYTES in
+// runtime/engine/admin/upload.php (parity-guarded in
+// apps/control-plane/src/runtime/php-policy-parity.test.ts).
+export const RUNTIME_UPLOAD_BATCH_MAX_FILES = 500;
+export const RUNTIME_UPLOAD_BATCH_MAX_BYTES = 8 * 1024 * 1024;
 export function runtimeUploadCanonicalPath(path) {
     // Canonical path form (spec "Upload Contract"): UTF-8, Unicode NFC,
     // percent-encoded once. The runtime rejects non-canonical encodings.

package/dist/utils/space-config.d.ts

@@ -37,9 +37,13 @@ export type ResolvedServingConfig = {
         path: string;
         status: 200 | 404;
     } | null;
+    /** W7.1 clean URLs: serve flat `<name>.html` at its extensionless URL. */
+    cleanUrls: boolean;
     listing: boolean;
     viewer: boolean;
     meta: NonNullable<SpaceConfig["meta"]> | null;
+    /** Gate-page theme tokens (access-plan §5.7 tier 1); null when unset. */
+    pagesTheme: NonNullable<NonNullable<SpaceConfig["pages"]>["theme"]> | null;
     /** Hidden experimental build-pipeline flag; false keeps today's behavior. */
     experimentalGutenberg: boolean;
     /** Resolved inject snippets; only honored when experimentalGutenberg is true. */

package/dist/utils/space-config.js

@@ -303,7 +303,9 @@ const PRIVATE_SERVING_FILES = new Set([
     ...SPACE_CONFIG_PRIVATE_FILES,
 ]);
 function privateServingPath(path) {
-    if (PRIVATE_SERVING_FILES.has(path) || path === ".well-known/stattic-runtime") {
+    if (PRIVATE_SERVING_FILES.has(path) ||
+        path === ".well-known/spacefast-runtime" ||
+        path === ".well-known/stattic-runtime") {
         return true;
     }
     const segments = path.toLowerCase().split("/");
@@ -381,10 +383,17 @@ export function resolveEffectiveSpaceConfig(input) {
     const serving = {
         index: merged.index ?? inferredRootHtmlIndex ?? false,
         fallback,
+        // Clean URLs (runtime W7.1): an explicit config value wins; the default is
+        // ON for plain static sites and OFF when a 200-status SPA fallback owns
+        // extensionless routes (the fallback answers them instead). The runtime
+        // resolver (management.php) applies the same default for artifacts
+        // finalized without the key.
+        cleanUrls: merged.cleanUrls ?? !(fallback && fallback.status === 200),
         listing,
         // The single-file viewer rides the listing bundle (artifact-style spaces).
         viewer: listing,
         meta: merged.meta ?? null,
+        pagesTheme: merged.pages?.theme && Object.keys(merged.pages.theme).length > 0 ? merged.pages.theme : null,
         experimentalGutenberg: merged.experimental_gutenberg === true,
         inject: merged.inject ?? null,
     };

package/dist/utils/space-theme.d.ts

@@ -13,4 +13,6 @@ export type CompiledSpaceTheme = {
 };
 /** Engine-enforced ceiling for the compiled declaration block. */
 export declare const SPACE_THEME_CSS_MAX_BYTES: number;
+export declare function isSafeThemeColor(value: string): boolean;
+export declare function isSafeThemeFontFamily(value: string): boolean;
 export declare function compileSpaceTheme(theme: SpaceTheme | null | undefined): CompiledSpaceTheme;

package/dist/utils/space-theme.js

@@ -25,6 +25,15 @@ function safeValue(value, pattern) {
     const trimmed = value.trim();
     return trimmed.length > 0 && !FORBIDDEN_VALUE_PATTERN.test(trimmed) && pattern.test(trimmed);
 }
+// Exported so other compilers that consume the same preset grammar (the gate-page
+// theme cascade's `theme.json`/`sf.theme.jsonc` tiers, access-plan §8) reuse this
+// ONE allowlist instead of re-deriving it — same posture, same forbidden set.
+export function isSafeThemeColor(value) {
+    return safeValue(value, COLOR_PATTERN);
+}
+export function isSafeThemeFontFamily(value) {
+    return safeValue(value, FONT_FAMILY_PATTERN);
+}
 export function compileSpaceTheme(theme) {
     if (!theme) {
         return { css: null, warnings: [] };

package/dist/utils/static-runtime-policy.d.ts

@@ -7,27 +7,6 @@ export declare function pathExtension(filePath: string): string;
 /** Basename without its extension (the "stem"), posix semantics. */
 export declare function pathStem(filePath: string): string;
 export declare function isPhpLikeStaticPath(filePath: string): boolean;
-/**
- * Classifies a candidate hash token — the final `.`/`-`-delimited tail of a
- * filename stem (see isImmutableAssetPath) — as a real bundler content hash.
- *
- * Immutable caching is a one-year pin, so the test is asymmetric on purpose: a
- * missed hash costs a cheap 304 revalidation, a false positive serves stale
- * content for a year. When a token is ambiguous we say no. The discriminator is
- * NOT character case — modern bundlers emit BOTH lowercase-hex and mixed-case
- * base64url hashes — it is entropy plus the absence of dictionary-word shape.
- *
- * IRREDUCIBLE LIMIT: an 8-char base64url token is the same size as a short
- * CamelCase-with-version-digit human name, and every default Vite/Rollup hash we
- * must accept carries only one digit (BzeDGMM3, 4A_iFExJ). So a token like
- * `D3GeoMap`, `McKayCV2`, or `v2-WebGL` is character-for-character indistinguishable
- * from a real hash and is accepted by clause B. No filename-only rule can separate
- * these without also rejecting the bundler hashes the spec mandates. The durable
- * fix is to gate immutable caching on path convention (Vite `assets/`, Next
- * `_next/static/`, SvelteKit `_app/immutable/`, …) rather than guessing from the
- * stem; this heuristic is the best-effort fallback when that context is absent.
- */
-export declare function looksLikeBundlerFingerprint(segment: string): boolean;
 export declare function isImmutableAssetPath(filePath: string): boolean;
 /** Forced inert serving policy for a committed static file. PHP-like files are never executable. */
 export declare function runtimeFileSafety(filePath: string): {

package/dist/utils/static-runtime-policy.js

@@ -46,19 +46,17 @@ export const PLATFORM_MANAGED_RESPONSE_HEADERS = [
 export const NON_IMMUTABLE_EXTENSIONS = ["html", "htm", "php", "txt", "xml"];
 const PHP_LIKE_EXTENSION_SET = new Set(PHP_LIKE_EXTENSIONS);
 const NON_IMMUTABLE_EXTENSION_SET = new Set(NON_IMMUTABLE_EXTENSIONS);
-// Two real bundler content-hash shapes. (A) lowercase hex (git/webpack short
-// SHAs, many tools): >=7 chars of [0-9a-f]. (B) base64url (Vite/Rollup/esbuild/
-// Next): >=8 chars of [A-Za-z0-9_-]. Both forms are recognized; the entropy
-// guards in looksLikeBundlerFingerprint are what keep human names out.
-const HEX_FINGERPRINT = /^[0-9a-f]{7,}$/;
-const BASE64URL_FINGERPRINT = /^[A-Za-z0-9_-]{8,}$/;
-// Durable path-convention layer over the filename-entropy heuristic
-// (looksLikeBundlerFingerprint). These are reserved build-output directories that the
-// framework OWNS and fills exclusively with content-addressed ([contenthash]) output by
-// construction — so every asset served from under them is safe to pin immutable for a
-// year regardless of how its individual filename reads. This recovers the real hashes the
-// filename heuristic conservatively MISSES (no-digit / single-case base64url draws like
-// `oton0Guf`, `DYyuCeEr`) without loosening the heuristic itself.
+// Immutable caching is decided by DETERMINISTIC signals only — reserved framework
+// build directories below, plus user-declared `_headers` Cache-Control rules that
+// override the baked default at serve time. There is deliberately NO filename-entropy
+// heuristic: an 8-char base64url bundler hash is character-for-character
+// indistinguishable from a short human name (D3GeoMap, McKayCV2), so any guess either
+// pins a user's mutable file for a year (stale site nobody can fix — browsers have no
+// bust channel) or silently downgrades real hashes to revalidate-every-load, which
+// under the wp.cloud edge per-IP rate limiter turned dashboard page loads into 429
+// storms (2026-07-06). Unrecognized files default to the safe direction:
+// `max-age=0, must-revalidate` for browsers, long s-maxage + purge-on-publish at the
+// edge.
 //
 // Each prefix is HIGH-CONFIDENCE guaranteed-hashed:
 //   - `_next/static/`   Next.js immutable build assets (chunks/css/media), all
@@ -71,9 +69,10 @@ const BASE64URL_FINGERPRINT = /^[A-Za-z0-9_-]{8,}$/;
 //
 // DELIBERATELY EXCLUDED: generic user-writable dirs (Vite's `assets/`, CRA/Gatsby's
 // `static/`). Users drop NON-hashed files there, so widening to them would create
-// year-long false positives. Those stay gated by the filename heuristic only. This layer
-// is purely ADDITIVE: it can only turn a heuristic-`false` into `true` for assets under a
-// guaranteed-hashed dir; it never flips a `true` to `false`.
+// year-long false positives. Deployments of bundler output declare those dirs immutable
+// themselves via a `_headers` rule (e.g. `/assets/*` → `Cache-Control: public,
+// max-age=31536000, immutable`), which the publisher — a build we ran, an agent, a CI
+// deploy — writes because it KNOWS the output is content-hashed.
 export const GUARANTEED_IMMUTABLE_PREFIXES = [
     "_next/static/",
     "_app/immutable/",
@@ -109,97 +108,14 @@ export function pathStem(filePath) {
 export function isPhpLikeStaticPath(filePath) {
     return PHP_LIKE_EXTENSION_SET.has(pathExtension(filePath));
 }
-/**
- * Classifies a candidate hash token — the final `.`/`-`-delimited tail of a
- * filename stem (see isImmutableAssetPath) — as a real bundler content hash.
- *
- * Immutable caching is a one-year pin, so the test is asymmetric on purpose: a
- * missed hash costs a cheap 304 revalidation, a false positive serves stale
- * content for a year. When a token is ambiguous we say no. The discriminator is
- * NOT character case — modern bundlers emit BOTH lowercase-hex and mixed-case
- * base64url hashes — it is entropy plus the absence of dictionary-word shape.
- *
- * IRREDUCIBLE LIMIT: an 8-char base64url token is the same size as a short
- * CamelCase-with-version-digit human name, and every default Vite/Rollup hash we
- * must accept carries only one digit (BzeDGMM3, 4A_iFExJ). So a token like
- * `D3GeoMap`, `McKayCV2`, or `v2-WebGL` is character-for-character indistinguishable
- * from a real hash and is accepted by clause B. No filename-only rule can separate
- * these without also rejecting the bundler hashes the spec mandates. The durable
- * fix is to gate immutable caching on path convention (Vite `assets/`, Next
- * `_next/static/`, SvelteKit `_app/immutable/`, …) rather than guessing from the
- * stem; this heuristic is the best-effort fallback when that context is absent.
- */
-export function looksLikeBundlerFingerprint(segment) {
-    // (A) Lowercase-hex hash (git short-SHA, webpack/Vite/Gatsby `[contenthash]`):
-    // a1b2c3d, 3f9a2b7e, d41d8cd98f00b204e980. Always require >=1 hex letter and
-    // >=1 digit so all-letter words (deadbeef) and digit-only runs (1234567) are out.
-    if (HEX_FINGERPRINT.test(segment) && /[a-f]/.test(segment) && /[0-9]/.test(segment)) {
-        // A long all-hex token is unambiguous: no human authors a 16+ char hex name, so
-        // length alone is entropy proof and the anti-word guards would only lose real
-        // hashes (most 16/20-char contenthashes contain an incidental 4-run).
-        if (segment.length >= 16) {
-            return true;
-        }
-        // Short hex (7-15) overlaps with hex-spelled words/years/colors, so require >=2
-        // digits and forbid a run of 4+ hex letters (deadbeef, cafe, face, decade) or
-        // 4+ digits (2024, 1234) — low-entropy human false positives.
-        if ((segment.match(/[0-9]/g) ?? []).length >= 2 &&
-            !/[a-f]{4}/.test(segment) &&
-            !/[0-9]{4}/.test(segment)) {
-            return true;
-        }
-    }
-    // (B) Base64url hash (Vite/Rollup/esbuild/Next): BzeDGMM3, 4A_iFExJ, P1Tx-Cyu,
-    // Z-cBR0Xb, 9-ygPMte. Random base64url draws — but immutable is a one-year pin, so
-    // against the human names that mimic this shape (acronym data/UI names, version
-    // and fiscal labels, dates, resolutions) we demand the full BALANCED-entropy
-    // signature of a real hash, and accept the safe cost of missing the minority of
-    // genuine hashes that fall short (a cheap 304):
-    //   - >=2 lowercase AND >=2 uppercase letters. Real base64url hashes carry several
-    //     of each; acronym-dominant human names (USMap-AKHIORWA, Map-USA_CA_TX,
-    //     MyCSS2DUI) have at most one lowercase token and are rejected here. This also
-    //     conservatively drops single-case and no-/one-lowercase hashes (DYyuCeEr,
-    //     ChJ_j-JJ) — the safe miss direction.
-    //   - at least one digit. ~1/4 of base64url hashes lack one and become cheap 304s,
-    //     but requiring it removes the all-letter acronym names that are otherwise
-    //     indistinguishable from a hash (USMap-AKHIORWA has no digit).
-    //   - no run of 3+ lowercase letters: a dictionary-word body (MyComponent
-    //     "omponent", LoginOAuth2 "ogin", HTTPClient2 "lient"). A packed hash breaks
-    //     lowercase up with caps/digits.
-    //   - no run of 2+ digits: clustered digits are human years/resolutions/sequences/
-    //     dates (2024, 1080, Win10, 01); a hash scatters single digits between letters.
-    // <8 chars (Widget2, API2, v2) never qualifies via the regex length floor.
-    if (BASE64URL_FINGERPRINT.test(segment) &&
-        (segment.match(/[a-z]/g) ?? []).length >= 2 &&
-        (segment.match(/[A-Z]/g) ?? []).length >= 2 &&
-        /[0-9]/.test(segment) &&
-        !/[a-z]{3}/.test(segment) &&
-        !/[0-9]{2}/.test(segment)) {
-        return true;
-    }
-    return false;
-}
 export function isImmutableAssetPath(filePath) {
     if (NON_IMMUTABLE_EXTENSION_SET.has(pathExtension(filePath))) {
         return false;
     }
-    // Path-convention layer (additive): anything under a guaranteed-content-hashed
-    // framework build dir is immutable regardless of filename. The extension gate above
-    // still applies, so an `index.html` accidentally under `_next/static/` is never pinned.
-    if (isUnderGuaranteedImmutablePrefix(filePath)) {
-        return true;
-    }
-    // Fallback for assets OUTSIDE those dirs: the filename-entropy heuristic.
-    const stem = pathStem(filePath);
-    for (let index = 0; index < stem.length; index += 1) {
-        if (index > 0 && stem[index - 1] !== "." && stem[index - 1] !== "-") {
-            continue;
-        }
-        if (looksLikeBundlerFingerprint(stem.slice(index))) {
-            return true;
-        }
-    }
-    return false;
+    // Path-convention layer: anything under a guaranteed-content-hashed framework build
+    // dir is immutable regardless of filename. The extension gate above still applies,
+    // so an `index.html` accidentally under `_next/static/` is never pinned.
+    return isUnderGuaranteedImmutablePrefix(filePath);
 }
 /** Forced inert serving policy for a committed static file. PHP-like files are never executable. */
 export function runtimeFileSafety(filePath) {

package/dist/utils/upload-session.d.ts

@@ -28,7 +28,7 @@ export declare function executeUploadSession(input: {
     session: UploadSession;
     targets?: readonly UploadTarget[] | undefined;
     concurrency?: number | undefined;
-    fetch?: typeof fetch | undefined;
+    fetch?: ((...args: Parameters<typeof fetch>) => ReturnType<typeof fetch>) | undefined;
     prepareTarget?: ((target: UploadTarget) => Promise<UploadTargetBody> | UploadTargetBody) | undefined;
     onEvent?: ((event: UploadSessionEvent) => void) | undefined;
 }): Promise<void>;

package/dist/utils/wpcom-auth-redirects.d.ts

@@ -1,11 +1,41 @@
 export type LoginIntentSearch = {
     direct?: boolean | undefined;
     returnTo?: string | undefined;
+    /** Route straight to WordPress.com's signup page instead of its login page. */
+    signup?: boolean | undefined;
 };
+/**
+ * Optional query params WordPress.com's OAuth2 authorize endpoint understands
+ * (wpcom `wp-content/mu-plugins/oauth2/oauth2.php`). All are cosmetic/flow
+ * hints — dropping them never breaks the OAuth handshake.
+ */
+export type WpcomAuthorizeExtras = {
+    /** Prefills the email field on the WP.com login screen (`user_email`). */
+    userEmail?: string | undefined;
+    /** Localizes the WP.com login/consent/signup screens (`locale`). */
+    locale?: string | undefined;
+    /**
+     * `implicit=false`: WP.com signs the user out of WordPress.com and shows a
+     * fresh login instead of silently reusing the current WP.com session. The
+     * only way to let a user switch WP.com accounts — without it, sign-out on
+     * our side loops them straight back into the same account.
+     */
+    switchAccount?: boolean | undefined;
+    /** `new-user=1`: routes straight to the WP.com signup page. */
+    signup?: boolean | undefined;
+};
+export declare function decorateWpcomAuthorizeUrl(authorizeUrl: string, extras?: WpcomAuthorizeExtras): string;
 export declare function buildDashboardLoginPath(input: LoginIntentSearch): string;
-export declare function buildWpcomAuthStartPath(input: LoginIntentSearch): string;
+export declare function buildWpcomAuthStartPath(input: LoginIntentSearch & {
+    /**
+     * A signed OAuth authorize query (Better Auth's login-page redirect).
+     * Carried through the WordPress.com round trip so the auth server can
+     * resume the authorization flow the moment the session exists. Opaque
+     * here — the auth server verifies its signature.
+     */
+    oauthQuery?: string | undefined;
+}): string;
 export declare function buildPostAuthPath(input: LoginIntentSearch): string;
-export declare function buildWpcomLoginUrl(authorizeUrl: string): string;
 export declare function buildWpcomSignInOptions(input: LoginIntentSearch, dashboardOrigin: string): {
     readonly provider: "wpcom";
     readonly callbackURL: string;

package/dist/utils/wpcom-auth-redirects.js

@@ -1,4 +1,24 @@
 import { sanitizeDashboardReturnTo } from "@spacefast/common/utils/auth-redirect";
+export function decorateWpcomAuthorizeUrl(authorizeUrl, extras = {}) {
+    const url = new URL(authorizeUrl);
+    const email = extras.userEmail?.trim();
+    if (email && email.includes("@") && email.length <= 254) {
+        url.searchParams.set("user_email", email);
+    }
+    // WP.com validates locales against its own list and falls back to English,
+    // so a light shape check is enough here. English is the default — omit it.
+    const locale = extras.locale?.trim().toLowerCase().replace("_", "-");
+    if (locale && /^[a-z]{2}(-[a-z]{2})?$/.test(locale) && locale !== "en") {
+        url.searchParams.set("locale", locale);
+    }
+    if (extras.switchAccount) {
+        url.searchParams.set("implicit", "false");
+    }
+    if (extras.signup) {
+        url.searchParams.set("new-user", "1");
+    }
+    return url.toString();
+}
 export function buildDashboardLoginPath(input) {
     const url = new URL("/sign-in", "http://dashboard.local");
     if (input.direct) {
@@ -16,6 +36,12 @@ export function buildWpcomAuthStartPath(input) {
     if (returnTo) {
         url.searchParams.set("returnTo", returnTo);
     }
+    if (input.signup) {
+        url.searchParams.set("signup", "1");
+    }
+    if (input.oauthQuery) {
+        url.searchParams.set("oauth_query", input.oauthQuery);
+    }
     return `${url.pathname}${url.search}`;
 }
 export function buildPostAuthPath(input) {
@@ -27,16 +53,6 @@ export function buildPostAuthPath(input) {
     }
     return `${url.pathname}${url.search}`;
 }
-export function buildWpcomLoginUrl(authorizeUrl) {
-    const authUrl = new URL(authorizeUrl);
-    const loginUrl = new URL("https://wordpress.com/log-in");
-    const clientId = authUrl.searchParams.get("client_id");
-    if (clientId) {
-        loginUrl.searchParams.set("client_id", clientId);
-    }
-    loginUrl.searchParams.set("redirect_to", authUrl.toString());
-    return loginUrl.toString();
-}
 export function buildWpcomSignInOptions(input, dashboardOrigin) {
     const errorCallbackUrl = new URL(buildDashboardLoginPath(input), dashboardOrigin);
     errorCallbackUrl.searchParams.set("claim_error", "login");