tileflow 0.1.0-alpha.19 → 0.1.0-alpha.20

package/README.md

@@ -211,6 +211,30 @@ for CI, provide an appropriately scoped key through the secret environment varia
 `TILEFLOW_API_KEY`. CI does not fall back to a saved personal login. Never put a key in a config,
 browser bundle, copied prompt, or command-line argument.
 
+If `login` finds the older local file containing an API key and API URL, it replaces that file only
+after a new account login succeeds. The old API key is not converted into an account session.
+Unrecognized local files are left untouched and stop login before authorization begins.
+
+For commands accepting an API key, `--api-key` takes precedence over `TILEFLOW_API_KEY`;
+only an absent key allows a saved personal session. An empty, invalid, expired or revoked key
+fails without switching identities. `--api-url` takes precedence over `TILEFLOW_API_URL`.
+This selection also applies to `models`, `tileset`, Icon Set commands and Map status. Keys
+never appear in help output. When a personal account can manage several Teams, pass an
+explicit `--team @team`; a Team key already selects its Team.
+
+`login` always authorizes a personal session through the dashboard, even when an API key is
+configured. `--no-browser` prints the URL without prompting to open it. Polling retries temporary
+connection/server failures with bounded backoff and honors rate-limit waits until the authorization
+expires. Denied or invalid authorizations stop immediately. A new session is validated and saved
+before the previous session for that API origin is revoked. Failed validation or persistence
+attempts to revoke the newly issued session and preserves the saved login. If cleanup cannot
+reach the server, the CLI explains that the session must be revoked in Dashboard settings.
+
+`logout` revokes only the saved personal session for the selected API origin. If server revocation
+fails, local access is preserved so logout can be retried. API keys remain independent: an API key
+in the environment still authorizes resource commands after logout. Personal session tokens stay
+in the local auth file with restricted permissions; this CLI does not use an OS credential store.
+
 ```sh
 npx tileflow login
 npx tileflow whoami --json
@@ -226,6 +250,11 @@ with `--origin`, or `--any-website`. It prints the Map ID to use for later deplo
 credential or the portable `id` in your config. CI always deploys an existing Map with a deploy key
 for that destination. `logout` removes the saved personal session.
 
+Deploy sends compact web cartography and data requirements, retaining concrete native artifacts.
+The web budget is 2,000,000 UTF-8 bytes for the whole family; icon receipts and native payloads
+have separate bounds.
+Oversized maps fail before uploads with their size and limit; no automatic simplification occurs.
+
 Deploy publishes the compiled concrete-theme family and managed icon assets; it does not ask the
 server to compile TypeScript. Repeating an unchanged deployment reuses its version. Build writers
 refuse to overwrite hosted manifests by default, and deploy refuses to replace a self-hosted
@@ -245,6 +274,9 @@ and uploads a managed dataset using Team data authority, not a map-only deploy k
 uploads are resumable; a completed version becomes current at stable delivery URLs. Purge is
 explicit, requires confirmation, and can be blocked by retained deployment dependencies.
 
+Administratively disabled uploads return `TF_TILESET_UPLOAD_DISABLED` without retrying.
+Temporary service failures retain bounded retries.
+
 `inspect features` samples bounded vector-source features. `icons list` and `icons diff` inspect
 prepared icon identities; they do not turn package directories into a separate hosted library.
 Use the installed command's help for exact arguments and supported JSON output.

package/dist/index.js

@@ -18,6 +18,7 @@ import {
   tileflowMapIdSchema as tileflowMapIdSchema2
 } from "@tileflow/core";
 import {
+  compactTileflowDeploymentArtifact as compactTileflowDeploymentArtifact3,
   createTileflowMapBuildManifest as createTileflowMapBuildManifest2
 } from "@tileflow/core/build";
 import {
@@ -101,6 +102,17 @@ var authConfigSchema = z.object({
     }
   }
 });
+var legacyAuthConfigSchema = z.object({
+  apiKey: z.string().min(1).max(4096),
+  apiUrl: z.url().max(2048).refine((value) => {
+    try {
+      normalizeApiOrigin(value);
+      return true;
+    } catch {
+      return false;
+    }
+  })
+}).strict();
 function emptyAuthConfig() {
   return Object.freeze({ sessions: Object.freeze({}), version: 2 });
 }
@@ -119,12 +131,35 @@ async function readAuthFile(path = authConfigPath()) {
     return { kind: "invalid" };
   }
   const config = authConfigSchema.safeParse(parsed);
-  return config.success ? { config: freezeConfig(config.data), kind: "sessions" } : { kind: "invalid" };
+  if (config.success) return { config: freezeConfig(config.data), kind: "sessions" };
+  return legacyAuthConfigSchema.safeParse(parsed).success ? { kind: "legacy" } : { kind: "invalid" };
+}
+async function prepareAccountLogin(path = authConfigPath()) {
+  const state = await readAuthFile(path);
+  if (state.kind === "invalid") {
+    throw new Error("Tileflow auth state is invalid; no changes were made.");
+  }
+  const directory = dirname(path);
+  const probePath = `${path}.tmp-${process.pid}-${randomBytes(8).toString("hex")}`;
+  await mkdir(directory, { mode: 448, recursive: true });
+  const handle = await open(probePath, "wx", 384);
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+    await unlink(probePath);
+  }
+  return state;
 }
 async function loadAuthConfig(path = authConfigPath()) {
   const state = await readAuthFile(path);
   if (state.kind === "empty") return emptyAuthConfig();
   if (state.kind === "sessions") return state.config;
+  if (state.kind === "legacy") {
+    throw new Error(
+      "Tileflow CLI login uses an older format. Run tileflow login to sign in again."
+    );
+  }
   throw new Error("Tileflow auth state is invalid; no changes were made.");
 }
 async function installAccountSession(session, path = authConfigPath()) {
@@ -4129,6 +4164,7 @@ function printFeatureInspectError(error) {
 
 // src/hosted-client.ts
 import { serializeTileflowFontBundleManifest } from "@tileflow/core";
+import { compactTileflowDeploymentArtifact, tileflowDeploymentWebBytes } from "@tileflow/core/build";
 
 // src/hosted-response.ts
 import { z as z2 } from "zod";
@@ -4145,6 +4181,7 @@ var hostedStyleDeploymentResponseSchema = z2.object({
   changed: z2.boolean().optional(),
   deploymentId: safeIdentifierSchema.optional(),
   mapId: z2.string().regex(/^map_[A-Za-z0-9_-]{16}$/u),
+  familyUrl: publicHttpUrlSchema.optional(),
   themes: z2.record(
     safeIdentifierSchema,
     z2.object({
@@ -4238,17 +4275,23 @@ function apiProfileCanTargetMap(profile, mapId) {
 }
 async function requestHostedJson(apiUrl, path, init = {}, options = {}) {
   return withHostedResponse(apiUrl, path, init, options, async (response) => {
+    const retryAfter = response.headers.get("retry-after");
+    const retryAfterMs = retryAfter === null ? void 0 : /^\d+$/u.test(retryAfter) ? Number(retryAfter) * 1e3 : Math.max(0, Date.parse(retryAfter) - Date.now());
+    const metadata = {
+      ok: response.ok,
+      status: response.status,
+      ...Number.isFinite(retryAfterMs) ? { retryAfterMs } : {}
+    };
     const source = await readBoundedResponseText(response, "Hosted API");
-    if (!source) return { body: null, json: true, ok: response.ok, status: response.status };
+    if (!source) return { body: null, json: true, ...metadata };
     try {
       return {
         body: JSON.parse(source),
         json: true,
-        ok: response.ok,
-        status: response.status
+        ...metadata
       };
     } catch {
-      return { body: null, json: false, ok: response.ok, status: response.status };
+      return { body: null, json: false, ...metadata };
     }
   });
 }
@@ -4272,24 +4315,57 @@ async function startDeviceAuthorization(appUrl, body, options = {}) {
   return response.body;
 }
 async function pollDeviceToken(appUrl, authorization, input, options = {}) {
-  const expiresAt = Date.now() + authorization.expiresIn * 1e3;
-  const intervalMs = Math.max(authorization.interval, 1) * 1e3;
+  const now = input.now ?? Date.now;
+  const expiresAt = input.expiresAt ?? now() + authorization.expiresIn * 1e3;
+  let intervalMs = Math.max(authorization.interval, 1) * 1e3;
+  let delayMs = intervalMs;
   const wait = input.sleep ?? ((milliseconds) => new Promise((resolve13) => setTimeout(resolve13, milliseconds)));
-  while (Date.now() < expiresAt) {
-    await wait(intervalMs);
-    const response = await requestHostedJson(
-      appUrl,
-      "/api/cli/device/token",
-      jsonRequest("POST", {
-        codeVerifier: input.codeVerifier,
-        deviceCode: authorization.deviceCode
-      }),
-      options
-    );
+  while (now() < expiresAt) {
+    options.signal?.throwIfAborted();
+    await wait(Math.min(delayMs, expiresAt - now()));
+    options.signal?.throwIfAborted();
+    if (now() >= expiresAt) break;
+    let response;
+    try {
+      response = await requestHostedJson(
+        appUrl,
+        "/api/cli/device/token",
+        jsonRequest("POST", {
+          codeVerifier: input.codeVerifier,
+          deviceCode: authorization.deviceCode
+        }),
+        {
+          ...options,
+          timeoutMs: Math.min(
+            options.timeoutMs ?? defaultHostedRequestTimeoutMs,
+            expiresAt - now()
+          )
+        }
+      );
+    } catch (error2) {
+      options.signal?.throwIfAborted();
+      if (!(error2 instanceof TypeError) && !(error2 instanceof Error && error2.name === "TimeoutError"))
+        throw error2;
+      delayMs = Math.min(Math.max(delayMs * 2, intervalMs), 6e4);
+      continue;
+    }
     if (response.ok && isDeviceToken(response.body)) return response.body;
     const error = asRecord(response.body).error;
-    if (error === "authorization_pending") continue;
     if (error === "access_denied") throw new Error("CLI authorization was denied.");
+    if (error === "expired_token") break;
+    if (error === "slow_down" || response.status === 429) {
+      intervalMs += 5e3;
+      delayMs = Math.max(intervalMs, response.retryAfterMs ?? 0);
+      continue;
+    }
+    if (error === "authorization_pending") {
+      delayMs = intervalMs;
+      continue;
+    }
+    if ([408, 500, 502, 503, 504].includes(response.status)) {
+      delayMs = Math.max(Math.min(delayMs * 2, 6e4), response.retryAfterMs ?? 0);
+      continue;
+    }
     throw new Error(`CLI authorization failed (${response.status}).`);
   }
   throw new Error("CLI authorization expired. Run `tileflow login` again.");
@@ -4530,11 +4606,14 @@ function isMapSetupTeam(value) {
   );
 }
 async function publishHostedStyle(api, body, responseLabel, options = {}) {
+  const input = body;
+  const compactBody = { ...input, artifact: compactTileflowDeploymentArtifact(input.artifact) };
+  assertHostedStyleBudget(compactBody);
   const response = await requestHostedJson(
     api.apiUrl,
     "/v1/styles",
     {
-      ...jsonRequest("POST", body),
+      ...jsonRequest("POST", compactBody),
       headers: { ...authorizationHeaders(api.apiKey, api.mapId), "Content-Type": "application/json" }
     },
     options
@@ -4545,6 +4624,15 @@ async function publishHostedStyle(api, body, responseLabel, options = {}) {
     value: parseResponse(response, hostedStyleDeploymentResponseSchema, responseLabel)
   };
 }
+function assertHostedStyleBudget(body) {
+  const observedBytes = tileflowDeploymentWebBytes(body);
+  const limitBytes = 2e6;
+  if (observedBytes > limitBytes)
+    throw Object.assign(
+      new Error(`Style content is ${observedBytes} bytes; the limit is ${limitBytes} bytes.`),
+      { code: "STYLE_DEPLOYMENT_TOO_LARGE", scope: "web", observedBytes, limitBytes }
+    );
+}
 async function uploadHostedIconPackage(api, iconPackage, options = {}) {
   const formData = new FormData();
   const fieldNames = {
@@ -4792,6 +4880,7 @@ import {
   serializeCanonicalJson as serializeCanonicalJson3
 } from "@tileflow/core";
 import {
+  compactTileflowDeploymentArtifact as compactTileflowDeploymentArtifact2,
   createTileflowMapBuildManifest,
   parseTileflowRendererDeploymentArtifact,
   tileflowRendererDeploymentResponseSchema
@@ -4978,7 +5067,11 @@ async function prepareNativeHostedDeploy(options) {
       ])
     )
   };
-  const styles = createTileflowStyles(project, { apiBaseUrl: apiOrigin, mapAssets });
+  const styles = createTileflowStyles(project, {
+    apiBaseUrl: apiOrigin,
+    mapAssets,
+    runtimeColors: true
+  });
   const local = await prepareTileflowLocalTilesets(project, styles, {
     assetBaseUrl: apiOrigin,
     baseDirectory,
@@ -5074,6 +5167,21 @@ async function runHostedNativeDeploy(options, ports) {
     const preflight = await parseTileflowRendererDeploymentArtifact(prepared.artifact);
     if (preflight.mapId !== prepared.mapName)
       throw failure("The prepared map does not match its artifact.");
+    const requestBody = (artifact2) => ({
+      artifact: compactTileflowDeploymentArtifact2(artifact2),
+      environment: prepared.mapName,
+      managedMapId: mapId,
+      usageMode: "session",
+      source: ports.source,
+      ...prepared.iconBinding ? {
+        iconPackage: {
+          contentHash: prepared.iconBinding.packageHash,
+          label: prepared.iconBinding.label
+        }
+      } : {},
+      ...prepared.iconComposition ? { iconComposition: prepared.iconComposition } : {}
+    });
+    assertHostedStyleBudget(requestBody(preflight));
     const existing = await ports.loadManifest(options.manifest, {
       overwriteSelfHosted: options.overwriteSelfHostedManifest === true
     });
@@ -5109,6 +5217,8 @@ async function runHostedNativeDeploy(options, ports) {
     if (prepared.iconComposition && prepared.iconComposition.packageHash !== iconPackage?.contentHash)
       throw failure("Icon composition does not match the confirmed effective package.");
     let response;
+    const body = requestBody(artifact);
+    assertHostedStyleBudget(body);
     try {
       response = await requestHostedJson(
         apiOrigin,
@@ -5120,20 +5230,7 @@ async function runHostedNativeDeploy(options, ports) {
             "X-Tileflow-Map-Id": mapId,
             "Content-Type": "application/json"
           },
-          body: serializeCanonicalJson3({
-            artifact,
-            environment: prepared.mapName,
-            managedMapId: mapId,
-            usageMode: "session",
-            source: ports.source,
-            ...iconPackage && prepared.iconBinding ? {
-              iconPackage: {
-                contentHash: iconPackage.contentHash,
-                label: prepared.iconBinding.label
-              }
-            } : {},
-            ...prepared.iconComposition ? { iconComposition: prepared.iconComposition } : {}
-          })
+          body: serializeCanonicalJson3(body)
         },
         ports.request
       );
@@ -5161,13 +5258,14 @@ async function runHostedNativeDeploy(options, ports) {
     const build = artifact.renderers.web.buildManifest.maps[artifact.mapId];
     const manifest = parseTileflowRuntimeManifest({
       apiUrl: apiOrigin,
-      version: build.timeOfDay || Object.values(existing?.maps ?? {}).some((map) => map.timeOfDay) ? 2 : 1,
+      version: result.renderers.web.familyUrl || Object.values(existing?.maps ?? {}).some((map) => map.familyUrl) ? 3 : build.timeOfDay || Object.values(existing?.maps ?? {}).some((map) => map.timeOfDay) ? 2 : 1,
       maps: {
         ...existing?.maps ?? {},
         [prepared.mapName]: {
           defaultTheme: build.defaultTheme,
           environment: prepared.mapName,
           mapId,
+          ...result.renderers.web.familyUrl ? { familyUrl: result.renderers.web.familyUrl } : {},
           ...build.systemThemes ? { systemThemes: build.systemThemes } : {},
           ...build.timeOfDay ? { timeOfDay: build.timeOfDay } : {},
           ...artifact.view ? { view: artifact.view } : {},
@@ -5204,6 +5302,21 @@ async function runHostedNativeDeploy(options, ports) {
   }
 }
 
+// src/hosted-options.ts
+import { Option } from "commander";
+function hostedApiKeyOption(description = "Tileflow API key") {
+  return new Option("--api-key <key>", description).env("TILEFLOW_API_KEY");
+}
+function hostedApiUrlOption() {
+  return new Option("--api-url <url>", "Tileflow API URL").env("TILEFLOW_API_URL");
+}
+function isHostedApiKey(value) {
+  return /^tf_live_[0-9a-f]{48}$/u.test(value);
+}
+function allowsStoredAccountSession(env = process.env) {
+  return !env.CI && env.GITHUB_ACTIONS !== "true" && env.GITLAB_CI !== "true";
+}
+
 // src/icon-diff-command.ts
 import { dirname as dirname8, resolve as resolve7 } from "path";
 import { z as z3 } from "zod";
@@ -5777,7 +5890,7 @@ var tileflowIconDiffDocumentSchema = z3.object({
   hasChanges: z3.boolean()
 }).strict();
 function registerIconDiffCommand(icons, dependencies) {
-  icons.command("diff").description("Preview a local icon package against an active hosted revision").requiredOption("--against <environment>", "named map environment to compare").option("-c, --config <path>", "config path", dependencies.defaultConfigPath).option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Tileflow API key", process.env.TILEFLOW_API_KEY).requiredOption("--map-id <id>", "managed Map destination").option("--json", "print deterministic schema-version-1 JSON").option("--cache-dir <path>", "verified Icon Set artifact cache root").option("--offline", "fail a locked Icon Set cache miss instead of hydrating it").option("--report <path>", "write a self-contained HTML visual report").option("--open", "open an explicitly requested report").option("--force", "replace a different explicitly requested report").action(async (options) => {
+  icons.command("diff").description("Preview a local icon package against an active hosted revision").requiredOption("--against <environment>", "named map environment to compare").option("-c, --config <path>", "config path", dependencies.defaultConfigPath).addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Tileflow API key")).requiredOption("--map-id <id>", "managed Map destination").option("--json", "print deterministic schema-version-1 JSON").option("--cache-dir <path>", "verified Icon Set artifact cache root").option("--offline", "fail a locked Icon Set cache miss instead of hydrating it").option("--report <path>", "write a self-contained HTML visual report").option("--open", "open an explicitly requested report").option("--force", "replace a different explicitly requested report").action(async (options) => {
     try {
       await runIconDiff(options, dependencies);
     } catch (error) {
@@ -6134,8 +6247,8 @@ async function resolveTeamAuthority(options, scopes, dependencies) {
     emitFailure(options.json, "invalid_api_url", safeMessage(error));
     return null;
   }
-  if (options.apiKey) {
-    if (!/^tf_live_[0-9a-f]{48}$/u.test(options.apiKey)) {
+  if (options.apiKey !== void 0) {
+    if (!isHostedApiKey(options.apiKey)) {
       emitFailure(options.json, "invalid_team_data_key", "Team data API key is invalid.");
       return null;
     }
@@ -6149,6 +6262,14 @@ async function resolveTeamAuthority(options, scopes, dependencies) {
     }
     return { apiOrigin, credential: options.apiKey, team: null };
   }
+  if (!allowsStoredAccountSession()) {
+    emitFailure(
+      options.json,
+      "api_key_required",
+      "CI requires TILEFLOW_API_KEY or --api-key. Saved personal logins are not used in CI."
+    );
+    return null;
+  }
   let config;
   try {
     config = await dependencies.loadAuthConfig();
@@ -6589,7 +6710,7 @@ function registerIconSetCommands(program2, dependencies) {
   }
 }
 function withTeamOptions(command2) {
-  return command2.option("--team <team>", "target Team as @team").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Team data API key", process.env.TILEFLOW_API_KEY).option("--json", "print deterministic schema-version-1 JSON");
+  return command2.option("--team <team>", "target Team as @team").addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Team data API key")).option("--json", "print deterministic schema-version-1 JSON");
 }
 async function readAllPages(authority, path, query, schema, select, identify) {
   const items = [];
@@ -6949,7 +7070,7 @@ function registerIconLockCommands(program2, dependencies) {
   }
 }
 function withLockOptions(command2, dependencies) {
-  return command2.option("-c, --config <path>", "config path", dependencies.defaultConfigPath).option("--team <team>", "target Team as @team").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Team data API key", process.env.TILEFLOW_API_KEY).option("--json", "print deterministic schema-version-1 JSON");
+  return command2.option("-c, --config <path>", "config path", dependencies.defaultConfigPath).option("--team <team>", "target Team as @team").addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Team data API key")).option("--json", "print deterministic schema-version-1 JSON");
 }
 function collectDeclaredReferences(project) {
   const references = [];
@@ -7532,7 +7653,7 @@ function registerModelCommands(program2, dependencies) {
   });
 }
 function withTeamOptions2(command2) {
-  return command2.option("--team <team>", "Team, as @team, when the account has several").option("--api-key <key>", "Team data API key with the 3D models permission").option("--api-url <url>", "Tileflow API origin").option("--json", "machine-readable output");
+  return command2.option("--team <team>", "Team, as @team, when the account has several").addOption(hostedApiKeyOption("Team data API key with the 3D models permission")).addOption(hostedApiUrlOption()).option("--json", "machine-readable output");
 }
 async function readDetail(authority, name, json2) {
   const response = await authorizedTeamRequest(
@@ -8439,7 +8560,9 @@ function createHostedTeamTilesetUploadTransport(input) {
         }
       }
       if (response?.ok) return response.body;
-      if (response && !isRetryableStatus(response.status)) throw responseError(response);
+      if (response && (asRecord3(response.body).code === "TF_TILESET_UPLOAD_DISABLED" || !isRetryableStatus(response.status))) {
+        throw responseError(response);
+      }
       if (attempt === maximumControlAttempts) {
         if (response) throw responseError(response);
         break;
@@ -8707,6 +8830,7 @@ function invalidRemoteResponse() {
   );
 }
 function failureMessage(code) {
+  if (code === "TF_TILESET_UPLOAD_DISABLED") return "New tileset uploads are disabled.";
   if (code === "TF_TILESET_SCHEMA_INCOMPATIBLE") {
     return "Tileset schema is incompatible with retained Map deployments.";
   }
@@ -8863,7 +8987,7 @@ function registerTilesetInspectCommand(parent, name = "inspect") {
 function registerTilesetCommands(program2, dependencies) {
   const tileset = program2.command("tileset").description("Inspect and manage geospatial tilesets");
   registerTilesetInspectCommand(tileset);
-  tileset.command("publish").description("Register and publish one PMTiles archive to a Team").argument("<archive>", "repository-local PMTiles archive").requiredOption("--id <id>", "Team-local logical tileset ID").option("--name <name>", "display name").option("--attribution <text>", "data attribution").option("--team <team>", "target Team as @team").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Team data API key", process.env.TILEFLOW_API_KEY).option("--json", "print deterministic schema-version-2 JSON").action(
+  tileset.command("publish").description("Register and publish one PMTiles archive to a Team").argument("<archive>", "repository-local PMTiles archive").requiredOption("--id <id>", "Team-local logical tileset ID").option("--name <name>", "display name").option("--attribution <text>", "data attribution").option("--team <team>", "target Team as @team").addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Team data API key")).option("--json", "print deterministic schema-version-2 JSON").action(
     async (archive, options) => {
       let uploadFile = null;
       try {
@@ -8954,7 +9078,7 @@ function registerTilesetCommands(program2, dependencies) {
       }
     }
   );
-  tileset.command("list").description("List tilesets owned by one Team").option("--team <team>", "target Team as @team").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Team data API key", process.env.TILEFLOW_API_KEY).option("--json", "print deterministic schema-version-1 JSON").action(async (options) => {
+  tileset.command("list").description("List tilesets owned by one Team").option("--team <team>", "target Team as @team").addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Team data API key")).option("--json", "print deterministic schema-version-1 JSON").action(async (options) => {
     try {
       const authority = await resolveTeamAuthority(options, ["tilesets:read"], dependencies);
       if (!authority) return;
@@ -8969,7 +9093,7 @@ function registerTilesetCommands(program2, dependencies) {
       emitFailure(options.json, "tileset_list_failed", "Tileset list failed.");
     }
   });
-  tileset.command("status").description("Show one Team tileset").argument("<id>", "Team-local logical ID or opaque resource ID").option("--team <team>", "target Team as @team").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Team data API key", process.env.TILEFLOW_API_KEY).option("--json", "print deterministic schema-version-1 JSON").action(async (id, options) => {
+  tileset.command("status").description("Show one Team tileset").argument("<id>", "Team-local logical ID or opaque resource ID").option("--team <team>", "target Team as @team").addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Team data API key")).option("--json", "print deterministic schema-version-1 JSON").action(async (id, options) => {
     try {
       if (!isTilesetId(id))
         return emitFailure(options.json, "invalid_tileset_id", "Tileset ID is invalid.");
@@ -8998,7 +9122,7 @@ function registerTilesetCommands(program2, dependencies) {
       emitFailure(options.json, "tileset_status_failed", "Tileset status failed.");
     }
   });
-  tileset.command("purge").description("Permanently purge one unreferenced Team tileset").argument("<id>", "Team-local logical ID or opaque resource ID").requiredOption("--confirm <id>", "repeat the exact tileset ID").option("--team <team>", "target Team as @team").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Team data API key", process.env.TILEFLOW_API_KEY).option("--json", "print deterministic schema-version-1 JSON").action(async (id, options) => {
+  tileset.command("purge").description("Permanently purge one unreferenced Team tileset").argument("<id>", "Team-local logical ID or opaque resource ID").requiredOption("--confirm <id>", "repeat the exact tileset ID").option("--team <team>", "target Team as @team").addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Team data API key")).option("--json", "print deterministic schema-version-1 JSON").action(async (id, options) => {
     try {
       if (!isTilesetId(id) || options.confirm !== id) {
         return emitFailure(
@@ -10014,7 +10138,7 @@ program.command("init").description("Create a starter tileflow.config.ts").optio
     `Validate the config with ${command("tileflow validate")}.`
   ]);
 });
-program.command("login").description("Authorize this machine for your Tileflow account").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option(
+program.command("login").description("Authorize this machine for your Tileflow account").addOption(hostedApiUrlOption()).option(
   "--app-url <url>",
   "Tileflow Dashboard URL",
   process.env.TILEFLOW_APP_URL ?? defaultAppUrl
@@ -10025,7 +10149,7 @@ program.command("login").description("Authorize this machine for your Tileflow a
     await loginWithDeviceFlow({
       expectedApiUrl: apiUrl,
       appUrl,
-      noBrowser: Boolean(options.noBrowser)
+      noBrowser: options.browser === false
     });
   } catch (error) {
     const message = error instanceof Error ? error.message : "Login failed.";
@@ -10033,7 +10157,7 @@ program.command("login").description("Authorize this machine for your Tileflow a
     process.exitCode = 1;
   }
 });
-program.command("logout").description("Revoke this origin's Tileflow account session").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).action(async (options) => {
+program.command("logout").description("Revoke this origin's Tileflow account session").addOption(hostedApiUrlOption()).action(async (options) => {
   const apiUrl = normalizeApiOrigin(options.apiUrl ?? defaultApiUrl);
   const config = await loadAuthConfig().catch((error) => {
     logError(safeAuthError(error));
@@ -10061,7 +10185,7 @@ program.command("logout").description("Revoke this origin's Tileflow account ses
   }
   logSuccess("Signed out of this Tileflow origin.");
 });
-program.command("whoami").description("Show the authenticated Tileflow account").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--json", "print deterministic schema-version-1 JSON").action(async (options) => {
+program.command("whoami").description("Show the authenticated Tileflow account").addOption(hostedApiUrlOption()).option("--json", "print deterministic schema-version-1 JSON").action(async (options) => {
   const config = await loadAuthConfig().catch((error) => {
     logAuthCommandError(options.json, safeAuthError(error));
     return null;
@@ -10580,7 +10704,7 @@ addMapSetupOptions(
   program.command("deploy").description(
     "Deploy maps to Tileflow and write the frontend manifest; without --map-id, create the Map first"
   )
-).option("-c, --config <path>", "config path", defaultConfigPath).option("--manifest <path>", "manifest path written for frontend bundlers", defaultManifestPath).option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Tileflow API key", process.env.TILEFLOW_API_KEY).option("--map-id <id>", "managed Map destination; omit it to create a new Map").option("--with-native", "publish web and native-v1 together for the selected managed Map").option("--map <name>", "configured map to connect when the repository contains multiple maps").option(
+).option("-c, --config <path>", "config path", defaultConfigPath).option("--manifest <path>", "manifest path written for frontend bundlers", defaultManifestPath).addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Tileflow API key")).option("--map-id <id>", "managed Map destination; omit it to create a new Map").option("--with-native", "publish web and native-v1 together for the selected managed Map").option("--map <name>", "configured map to connect when the repository contains multiple maps").option(
   "--overwrite-self-hosted-manifest",
   "explicitly replace an existing self-hosted manifest at --manifest"
 ).option("--cache-dir <path>", "verified Icon Set artifact cache root").option("--offline", "fail a locked Icon Set cache miss instead of hydrating it").action(
@@ -10653,6 +10777,7 @@ addMapSetupOptions(
       mapAssetsWithBuildingModels(modelAssets, { hosted: true })
     );
     const compiledPreflightStyles = createTileflowStyles2(deploymentProject, {
+      runtimeColors: true,
       apiBaseUrl: apiUrl,
       mapAssets: preflightMapAssets
     });
@@ -10684,6 +10809,56 @@ addMapSetupOptions(
       process.exitCode = 1;
       return;
     }
+    for (const mapName of mapNames) {
+      const map = deploymentProject.maps[mapName];
+      const family = prepareTileflowHostedThemeFamily(
+        mapName,
+        map,
+        preflightFonts.styles[mapName]
+      );
+      const binding = bindingsByMap.get(mapName);
+      const iconPackage = binding && packagesByHash.get(binding.packageHash);
+      const manifest = await createTileflowMapBuildManifest2(
+        {
+          [mapName]: {
+            map,
+            lineage: deploymentProject.mapMetadata?.[mapName]?.lineage ?? [
+              { id: map.id, mapVersion: map.version }
+            ],
+            assets: (iconPackage?.files ?? []).map((file) => ({
+              contentType: file.contentType,
+              fileName: `icons/${mapName}/${file.fileName}`,
+              source: file.source
+            })),
+            sourceAssets: {
+              fonts: preflightFonts.sourceIdentities[mapName] ?? [],
+              icons: compiledIcons.sourceIdentities[mapName] ?? [],
+              ...compiledIcons.compositions[mapName] ? { iconComposition: compiledIcons.compositions[mapName] } : {},
+              ...hostedModelSourceIdentities(modelAssets, mapName) ? { models: hostedModelSourceIdentities(modelAssets, mapName) } : {}
+            },
+            styles: family.styles
+          }
+        },
+        { provenance: await createTileflowBuildProvenance2(process.cwd()) }
+      );
+      assertHostedStyleBudget({
+        artifact: compactTileflowDeploymentArtifact3({
+          kind: "tileflow-map-deployment",
+          schemaVersion: 1,
+          mapId: mapName,
+          buildManifest: manifest,
+          styles: family.styles,
+          teamSources: family.teamSources
+        }),
+        environment: mapName,
+        managedMapId: options.mapId ?? "map_preflight0000000",
+        usageMode: "session",
+        source,
+        ...iconPackage ? { iconPackage: { contentHash: iconPackage.contentHash, label: binding.label } } : {},
+        ...compiledIcons.compositions[mapName] ? { iconComposition: compiledIcons.compositions[mapName] } : {},
+        ...teamModelSources(modelAssets, mapName) ? { teamModelSources: teamModelSources(modelAssets, mapName) } : {}
+      });
+    }
     let outputManifest = null;
     try {
       outputManifest = await loadExistingDeployManifest(options.manifest, {
@@ -10749,6 +10924,7 @@ addMapSetupOptions(
       mapAssetsWithBuildingModels(modelAssets, { hosted: true })
     );
     const compiledHostedStyles = createTileflowStyles2(deploymentProject, {
+      runtimeColors: true,
       apiBaseUrl: api.apiUrl,
       mapAssets: hostedMapAssets
     });
@@ -10956,6 +11132,7 @@ addMapSetupOptions(
         environment: mapName,
         mapId: body.mapId,
         ...resolvedMap.systemThemes ? { systemThemes: resolvedMap.systemThemes } : {},
+        ...body.familyUrl ? { familyUrl: body.familyUrl } : {},
         ...resolvedMap.timeOfDay && Object.keys(resolvedMap.timeOfDay).length ? { timeOfDay: resolvedMap.timeOfDay } : {},
         themes: Object.fromEntries(
           themeNames.map((themeName) => {
@@ -10994,8 +11171,8 @@ addMapSetupOptions(
       apiUrl: api.apiUrl,
       maps: { ...existingManifest?.maps ?? {}, ...deployedMaps },
       version: Object.values({ ...existingManifest?.maps, ...deployedMaps }).some(
-        (map) => map.timeOfDay
-      ) ? 2 : 1
+        (map) => map.familyUrl
+      ) ? 3 : Object.values({ ...existingManifest?.maps, ...deployedMaps }).some((map) => map.timeOfDay) ? 2 : 1
     });
     logSuccess("Deployed Tileflow maps.");
     printKeyValue("Manifest", pathLabel(manifestPath));
@@ -11009,7 +11186,7 @@ addMapSetupOptions(
     }
   }
 );
-program.command("status").description("Show deployed compiled styles").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Tileflow API key", process.env.TILEFLOW_API_KEY).option("--map-id <id>", "managed Map destination").option("--json", "print raw JSON").action(async (options) => {
+program.command("status").description("Show deployed compiled styles").addOption(hostedApiUrlOption()).addOption(hostedApiKeyOption("Tileflow API key")).option("--map-id <id>", "managed Map destination").option("--json", "print raw JSON").action(async (options) => {
   if (!options.mapId || !/^map_[A-Za-z0-9_-]{16}$/u.test(options.mapId)) {
     if (options.json) console.error("Status requires a valid --map-id.");
     else logError("Status requires a valid --map-id.");
@@ -11389,13 +11566,23 @@ function closeNodeServer(server) {
   return new Promise((resolveClose) => server.close(() => resolveClose()));
 }
 async function loginWithDeviceFlow(options) {
+  const authState = await prepareAccountLogin();
+  if (authState.kind === "legacy") {
+    logWarning("An older Tileflow CLI login will be replaced after authorization.");
+  }
   const codeVerifier = randomBase64Url(32);
   const codeChallenge = createPkceChallenge(codeVerifier);
   printTitle("Tileflow login", "Authorize this machine from the Tileflow dashboard.");
+  const authorizationStartedAt = Date.now();
   const authorization = await startDeviceAuthorization(options.appUrl, {
     codeChallenge,
     deviceName: hostname()
   });
+  const apiUrl = normalizeApiOrigin(options.expectedApiUrl);
+  if (normalizeApiOrigin(authorization.apiUrl) !== apiUrl) {
+    throw new Error("The dashboard returned an unexpected Tileflow API origin.");
+  }
+  const previousSession = authState.kind === "sessions" ? authState.config.sessions[apiUrl] : void 0;
   printKeyValue("Code", pc9.bold(authorization.userCode));
   printKeyValue("URL", link(authorization.verificationUriComplete));
   if (options.noBrowser) {
@@ -11416,12 +11603,9 @@ async function loginWithDeviceFlow(options) {
   }
   logInfo("Waiting for authorization...");
   const token = await pollDeviceToken(options.appUrl, authorization, {
-    codeVerifier
+    codeVerifier,
+    expiresAt: authorizationStartedAt + authorization.expiresIn * 1e3
   });
-  const apiUrl = normalizeApiOrigin(token.apiUrl);
-  if (apiUrl !== normalizeApiOrigin(options.expectedApiUrl)) {
-    throw new Error(`The dashboard returned an unexpected Tileflow API origin: ${apiUrl}.`);
-  }
   const session = {
     account: token.account,
     accountSession: token.accountSession,
@@ -11430,13 +11614,30 @@ async function loginWithDeviceFlow(options) {
     expiresAt: token.expiresAt,
     sessionId: token.sessionId
   };
-  const profile = await validateAccountSession(session);
-  if (!profile.ok) {
-    throw new Error(profile.error);
+  let account = session.account;
+  try {
+    if (normalizeApiOrigin(token.apiUrl) !== apiUrl) {
+      throw new Error("The dashboard returned an unexpected Tileflow API origin.");
+    }
+    const profile = await validateAccountSession(session);
+    if (!profile.ok) throw new Error(profile.error);
+    account = profile.value.account;
+    await installAccountSession({ ...session, account });
+  } catch (error) {
+    if (!await revokeHostedAccountSession(apiUrl, session.accountSession)) {
+      logWarning(
+        "Could not revoke the new account session after login failed. Revoke it in Dashboard settings."
+      );
+    }
+    throw error;
+  }
+  if (previousSession && previousSession.accountSession !== session.accountSession && !await revokeHostedAccountSession(apiUrl, previousSession.accountSession)) {
+    logWarning(
+      "The new login was saved, but the previous session could not be revoked. Revoke it in Dashboard settings."
+    );
   }
-  await installAccountSession({ ...session, account: profile.value.account });
   logSuccess("Signed in to Tileflow.");
-  printAccountDetails({ ...session, account: profile.value.account });
+  printAccountDetails({ ...session, account });
   printKeyValue("Dashboard", link(options.appUrl));
 }
 function createPkceChallenge(verifier) {
@@ -11529,7 +11730,7 @@ function validateMapSetupTarget(options, source) {
   }
   const createFirst = `Create the Map with ${command("tileflow maps create")} after ${command("tileflow login")}, then pass --map-id.`;
   if (options.withNative) return fail("--with-native requires one valid --map-id.", [createFirst]);
-  if (options.apiKey || !allowsStoredDeployCredential(source)) {
+  if (options.apiKey !== void 0 || !allowsStoredDeployCredential(source)) {
     return fail("Managed deploy with a Tileflow credential or in CI requires --map-id.", [
       createFirst
     ]);
@@ -11597,7 +11798,12 @@ async function requireApiOptions(options, behavior = {}) {
     process.exitCode = 1;
     return null;
   }
-  if (options.apiKey) {
+  if (options.apiKey !== void 0) {
+    if (!isHostedApiKey(options.apiKey)) {
+      if (!behavior.silent) logError("Tileflow API key is invalid.");
+      process.exitCode = 1;
+      return null;
+    }
     if (behavior.assertExplicitKeyMap) {
       const profile = await validateApiKey(apiUrl, options.apiKey);
       if (!profile.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tileflow",
-  "version": "0.1.0-alpha.19",
+  "version": "0.1.0-alpha.20",
   "license": "Apache-2.0",
   "description": "CLI-only tools for Tileflow config, capture, visual testing, and deploy.",
   "type": "module",
@@ -35,12 +35,12 @@
   },
   "dependencies": {
     "@hono/node-server": "2.1.3",
-    "@tileflow/capture": ">=0.1.0-alpha.36 <0.1.0-beta.0",
+    "@tileflow/capture": ">=0.1.0-alpha.37 <0.1.0-beta.0",
     "@tileflow/coordinates": ">=0.1.0-alpha.3 <0.1.0-beta.0",
     "@tileflow/coordinates-runtime": ">=0.1.0-alpha.6 <0.1.0-beta.0",
-    "@tileflow/core": ">=0.1.0-alpha.43 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.39 <0.1.0-beta.0",
-    "@tileflow/maps": ">=0.1.0-alpha.17 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.45 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.41 <0.1.0-beta.0",
+    "@tileflow/maps": ">=0.1.0-alpha.18 <0.1.0-beta.0",
     "commander": "^15.0.0",
     "hono": "4.13.14",
     "picocolors": "^1.1.1",
@@ -55,7 +55,7 @@
     "cli": "tsx src/index.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx --test test/*.test.ts",
+    "test": "tsx --test --test-concurrency=2 test/*.test.ts",
     "verify": "pnpm run typecheck && pnpm run test"
   }
 }