@wix/himalaya-cli 0.1470.0 → 0.1471.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/dev-server/src/app-config.d.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { DerivedAppMeta } from "./app-module.js";
 import { type WixCachePolicy } from "./wix-cache-policy.js";
 import type { NetMocksFile, WixMockRule } from "./wix-gateway.js";
+import { gateScreenIdProblem } from "../../ts/src/auth-gate-screen.js";
 import { type UnmappedPushDestination } from "../../ts/src/wix-push-links.js";
 import type { PushConfig, FlagConfig, AppControl, TabBarConfig, DrawerConfig, SidebarConfig, SplashConfig, LocaleConfig, NavKind, OrientationConfig, StreamPolicy } from "@wix/himalaya/core";
 export type { PushConfig, FlagConfig, AppControl, TabBarConfig, DrawerConfig, SidebarConfig, SplashConfig, LocaleConfig, NavKind, OrientationConfig, StreamPolicy };
@@ -37,6 +38,7 @@ export interface TelemetryConfig {
 export interface AuthConfigBlock {
     providerId: string;
     required: boolean;
+    gateScreenId?: string;
     config: Record<string, unknown>;
 }
 /** RFC 0010 (nav-modes amendment) — OTA back-affordance config. `enabled` gates
@@ -195,13 +197,19 @@ export interface DevGatewayConfig {
      *  answers a miss with the same 404 and never calls the real capability. */
     unmatched?: "passthrough" | "fail";
 }
+/** #4651 — the gate-screen existence rule lives import-free in core (the auth bake shares it). */
+export { gateScreenIdProblem };
 /** Derive the OTA authConfig block from a defineApp auth block
  *  ({ providerId, config }). `required` is read from `config.required === true`
- *  and lifted to the top level; secret-ish keys are scrubbed. */
+ *  and lifted to the top level, as is `config.gateScreenId` (#4651); secret-ish
+ *  keys are scrubbed. When the app's screens are given, a `gateScreenId` naming none
+ *  of them is DROPPED (the shell falls back to the stock login) and warned about —
+ *  never thrown: this runs on every app-config serve and hot reload, and
+ *  `himalaya-dev app validate` is where a bad id fails ([gateScreenIdProblem]). */
 export declare function deriveAuthConfig(auth: {
     providerId: string;
     config: Record<string, unknown>;
-} | undefined): AuthConfigBlock | undefined;
+} | undefined, screenIds?: readonly string[]): AuthConfigBlock | undefined;
 /** Derive a baseline NavigationConfig from the loaded app's derived meta. */
 /** What `deriveNavigationConfig` needs to finish an app-level nav bundle ref.
  *

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/sdk/wix-platform/src/index.d.ts

@@ -94,8 +94,16 @@ export declare const auth: {
     isAuthenticated(): Promise<boolean>;
     /** The current access/member token (or null when anonymous). */
     getAccessToken(): Promise<string | null>;
-    /** Sign in (hosted Wix login → member token). Resolves with the new identity. */
-    signIn(): Promise<WixIdentity>;
+    /** Sign in, resolving with the new identity. With a real provider bound to the app's session
+     *  gate this presents the real sign-in as a full-screen cover over the current screen — the
+     *  app's `auth.config.gateScreenId` screen if set, else the stock login, opened on `intent`
+     *  (default `"login"`) — and resolves once the user is signed in. Dismissing it rejects with
+     *  `err.code === "cancelled"`; a second call while one is up rejects `"sign_in_in_progress"`.
+     *  The calling worker survives the sign-in. Before the provider is bound it rejects
+     *  `sign_in_unavailable`, as on web; only a shell with no session gate keeps the dev seam. */
+    signIn(opts?: {
+        intent?: "login" | "signup";
+    }): Promise<WixIdentity>;
     /** Sign out — clears the member token (visitor session may persist). */
     signOut(): Promise<WixIdentity>;
     /** Mint/return a per-business signed instance for authorized Wix REST calls —
@@ -106,8 +114,8 @@ export declare const auth: {
      *
      *  When the app provisions `real.auth`, it mints through the REAL Wix endpoint
      *  (the same `one-app-session-web` mint the Owner/Spaces bundles used ad-hoc),
-     *  so the dev gateway records it; otherwise (and on any failure) it uses the
-     *  native dev seam. */
+     *  so it is observed like any other Wix call; otherwise (and on any failure) it
+     *  uses the native dev seam. */
     signedInstance(businessId: string, type?: WixSignedInstanceType): Promise<string | null>;
 };
 /** One business's scope, as `site.forSite(msid)` returns it.
@@ -177,7 +185,7 @@ export declare const site: {
      *  Only reaches businesses the signed-in user owns: the header names a business, and
      *  Wix refuses to mint an instance for one they do not. A consumer app (one Headless
      *  clientId, one site) does not mint per-site at all, so this is inert there — see
-     *  docs/branded-lite-site-binding.md. */
+     *  the branded-lite-site-binding guide. */
     forSite(msid: string): WixSiteScope;
 };
 export declare const monitoring: {

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/ts/src/auth-gate-screen.d.ts

@@ -0,0 +1,10 @@
+/** Why a `gateScreenId` value is not a usable screen id, or null when it is (or is absent). */
+export declare function gateScreenIdShapeProblem(id: unknown): string | null;
+/** Why `auth.config.gateScreenId` is not one of the app's exact screens, or null when it is (or is
+ *  absent). One rule for every path — the served OTA authConfig, `app validate` and the auth bake:
+ *  a release serves the exact screens (a templated route only for its build-time seed ids), and the
+ *  OTA value overrides the baked one, so a templated gate id would mount a 404 gate in a release. */
+export declare function gateScreenIdProblem(auth: {
+    providerId: string;
+    config: Record<string, unknown>;
+} | undefined, screenIds: readonly string[]): string | null;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/ts/src/define-app.d.ts

@@ -819,9 +819,24 @@ export interface ProdEnvironment {
 export interface AuthProvider {
     /** Stable id, e.g. "wix", "generic-oauth", "google", "<custom>". */
     providerId: string;
-    /** Provider-specific configuration, opaque to core. */
+    /**
+     * Provider-specific configuration, opaque to core — except two keys core lifts to the top of
+     * the baked `auth.json` and the OTA `authConfig`:
+     *
+     * - `required: true` gates the app's root on an authenticated session.
+     * - `gateScreenId: "<screen id>"` (#4651) names a screen the app ships as its own auth gate. A
+     *   required-auth launch shows it, rendered by the ordinary screen host as a full-screen root,
+     *   instead of the stock login, and a worker's mid-session `wixPlatform.auth.signIn()` presents
+     *   it as a cover. It drives sign-in through the `auth.*` actions (`auth.signIn` with
+     *   `params.intent: "login" | "signup"` opens the provider's own login UI in that mode); the
+     *   credential still never passes through app code, the floor `screens` documents.
+     */
     config: Record<string, unknown>;
 }
+/** Validate the SHAPE of `auth.config.gateScreenId` (#4651): a non-empty string when present.
+ *  Whether it names a screen the app ships is `gateScreenIdProblem`'s rule (the dev-server's app
+ *  config, `himalaya-dev app validate` and the auth bake), which knows the app's screens. */
+export declare function validateAuthGateScreen(auth: AuthProvider | undefined): void;
 export interface TelemetrySink {
     sinkId: string;
     emit(event: TelemetryEvent): void | Promise<void>;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/core.mjs

@@ -7143,6 +7143,15 @@ function validateDistribution(d, where = "distribution") {
   }
 }
 
+// ../../core/ts/src/auth-gate-screen.ts
+function gateScreenIdShapeProblem(id) {
+  if (id === void 0) return null;
+  if (typeof id !== "string" || id.trim().length === 0) {
+    return `defineApp: auth.config.gateScreenId must be a non-empty screen id string, got ${JSON.stringify(id)}.`;
+  }
+  return null;
+}
+
 // ../../core/data-resources/src/base44/schema.ts
 var BASE44_FIELD_TYPES = ["string", "number", "integer", "boolean", "array", "object"];
 var BASE44_STRING_FORMATS = ["date", "date-time", "time", "email", "uri", "uuid", "file", "richtext"];
@@ -7462,6 +7471,10 @@ function resolveOrientationEnvelope(env) {
     tablet: env?.tablet?.length ? env.tablet : DEFAULT_ORIENTATION_ENVELOPE.tablet
   };
 }
+function validateAuthGateScreen(auth) {
+  const problem = gateScreenIdShapeProblem(auth?.config?.gateScreenId);
+  if (problem) throw new Error(problem);
+}
 function dataSchemaScopeOf(entity) {
   if (entity.scope === "app" || entity.scope === "principal") return entity.scope;
   return entity.encrypted ? "principal" : "app";
@@ -7702,6 +7715,7 @@ function validateConfigShape(config) {
     validateDistribution(config.distribution, "defineApp: distribution");
   }
   validateLadderConfig(config);
+  validateAuthGateScreen(config.auth);
   if (config.tier5Cap) {
     const c = config.tier5Cap;
     if (c.percentageOfActiveScreens < 0 || c.percentageOfActiveScreens > 100) {
@@ -14687,6 +14701,7 @@ export {
   tonalElevationAlpha,
   validate,
   validateAll,
+  validateAuthGateScreen,
   validateBase44Entities,
   validateDistribution,
   validateLaunchManifest,

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/wix-platform.mjs

@@ -200,9 +200,24 @@ var session = {
     return { present: r?.present ?? false, msid: r?.msid ?? null };
   }
 };
-async function authTransition(method) {
-  await call2(method);
+var AUTH_REFUSAL_CODES = /* @__PURE__ */ new Set(["cancelled", "sign_in_in_progress", "sign_in_unavailable"]);
+async function authTransition(method, params) {
+  const r = await call2(method, params).catch((e) => {
+    const message = e instanceof Error ? e.message : String(e);
+    throw AUTH_REFUSAL_CODES.has(message) ? Object.assign(e instanceof Error ? e : new Error(message), { code: message }) : e;
+  });
+  if (typeof r?.error === "string" && r.error.length > 0) {
+    throw Object.assign(new Error(r.error), { code: r.error });
+  }
   dropConductFlights();
+  if (method === "authSignIn" && typeof r?.authenticated === "boolean") {
+    return {
+      authenticated: r.authenticated,
+      type: r.type ?? (r.authenticated ? "member" : "anonymous"),
+      userId: r.userId || null,
+      email: r.email || null
+    };
+  }
   return auth.getIdentity();
 }
 var auth = {
@@ -225,9 +240,15 @@ var auth = {
     const r = await call2("authAccessToken");
     return r?.token && r.token.length > 0 ? r.token : null;
   },
-  /** Sign in (hosted Wix login → member token). Resolves with the new identity. */
-  signIn() {
-    return authTransition("authSignIn");
+  /** Sign in, resolving with the new identity. With a real provider bound to the app's session
+   *  gate this presents the real sign-in as a full-screen cover over the current screen — the
+   *  app's `auth.config.gateScreenId` screen if set, else the stock login, opened on `intent`
+   *  (default `"login"`) — and resolves once the user is signed in. Dismissing it rejects with
+   *  `err.code === "cancelled"`; a second call while one is up rejects `"sign_in_in_progress"`.
+   *  The calling worker survives the sign-in. Before the provider is bound it rejects
+   *  `sign_in_unavailable`, as on web; only a shell with no session gate keeps the dev seam. */
+  signIn(opts) {
+    return authTransition("authSignIn", { intent: opts?.intent ?? "login" });
   },
   /** Sign out — clears the member token (visitor session may persist). */
   signOut() {
@@ -241,8 +262,8 @@ var auth = {
    *
    *  When the app provisions `real.auth`, it mints through the REAL Wix endpoint
    *  (the same `one-app-session-web` mint the Owner/Spaces bundles used ad-hoc),
-   *  so the dev gateway records it; otherwise (and on any failure) it uses the
-   *  native dev seam. */
+   *  so it is observed like any other Wix call; otherwise (and on any failure) it
+   *  uses the native dev seam. */
   async signedInstance(businessId, type = "User") {
     if (isMemberReal("auth")) {
       try {
@@ -341,7 +362,7 @@ var site = {
    *  Only reaches businesses the signed-in user owns: the header names a business, and
    *  Wix refuses to mint an instance for one they do not. A consumer app (one Headless
    *  clientId, one site) does not mint per-site at all, so this is inert there — see
-   *  docs/branded-lite-site-binding.md. */
+   *  the branded-lite-site-binding guide. */
   forSite(msid) {
     const scoped = (msid ?? "").trim();
     return {

package/dist/cli.mjs

@@ -8127,7 +8127,6 @@ function resolveTranslation(value, catalog3, sourceCatalog) {
 var BINDING_SIGILS, BINDING_SIGIL_RE, TRANSLATION_PREFIX, TRANSLATION_KEY_RE;
 var init_bindings = __esm({
   "../../core/ts/src/bindings.ts"() {
-    "use strict";
     BINDING_SIGILS = ["service", "flag", "item", "t"];
     BINDING_SIGIL_RE = new RegExp(
       `^\\$(?:${BINDING_SIGILS.filter((s2) => s2 !== "t").join("|")})\\b|^\\$t:`
@@ -31137,6 +31136,28 @@ var init_l10n = __esm({
   }
 });
 
+// ../../core/ts/src/auth-gate-screen.ts
+function gateScreenIdShapeProblem(id) {
+  if (id === void 0) return null;
+  if (typeof id !== "string" || id.trim().length === 0) {
+    return `defineApp: auth.config.gateScreenId must be a non-empty screen id string, got ${JSON.stringify(id)}.`;
+  }
+  return null;
+}
+function gateScreenIdProblem(auth, screenIds) {
+  const id = auth?.config?.gateScreenId;
+  if (id === void 0) return null;
+  const shape = gateScreenIdShapeProblem(id);
+  if (shape) return shape;
+  const gateId = id;
+  if (screenIds.includes(gateId)) return null;
+  return `defineApp: auth.config.gateScreenId is "${gateId}", which is not one of the app's exact screens \u2014 a required-auth launch would have no login to show (a release serves exact screens, so a templated route 404s). Name an exact screen, or drop gateScreenId to use the stock login.`;
+}
+var init_auth_gate_screen = __esm({
+  "../../core/ts/src/auth-gate-screen.ts"() {
+  }
+});
+
 // ../../core/ts/src/wix-push-links.ts
 function replacementPingFamily(name) {
   return RETIRED_PING_FAMILIES.has(name) ? DEFAULT_PING_APP_NAME : void 0;
@@ -31328,17 +31349,21 @@ function deriveTelemetryConfig(app) {
   }
   return cfg;
 }
-function deriveAuthConfig(auth) {
+function deriveAuthConfig(auth, screenIds) {
   if (!auth?.providerId) return void 0;
   const config = {};
   for (const [key3, value] of Object.entries(auth.config ?? {})) {
-    if (key3 === "required") continue;
+    if (key3 === "required" || key3 === "gateScreenId") continue;
     if (AUTH_SECRET_KEY_RE.test(key3)) continue;
     config[key3] = value;
   }
+  const gateScreenId = auth.config?.gateScreenId;
+  const problem = typeof gateScreenId === "string" && screenIds ? gateScreenIdProblem(auth, screenIds) : null;
+  if (problem) console.warn(`[app-config] ${problem} \u2014 serving the stock login instead.`);
   return {
     providerId: auth.providerId,
     required: auth.config?.required === true,
+    ...typeof gateScreenId === "string" && gateScreenId.length > 0 && !problem ? { gateScreenId } : {},
     config
   };
 }
@@ -31448,7 +31473,7 @@ function deriveNavigationConfig(app, bundleCtx) {
   if (app.homeScreenId) config.homeScreenId = app.homeScreenId;
   if (app.label) config.name = app.label;
   config.backAffordance = { enabled: true };
-  const authConfig = deriveAuthConfig(app.auth);
+  const authConfig = deriveAuthConfig(app.auth, app.screenIds);
   if (authConfig !== void 0) config.authConfig = authConfig;
   if (app.iap !== void 0) config.iapConfig = app.iap;
   if (app.cashier !== void 0) config.cashierConfig = app.cashier;
@@ -31539,6 +31564,7 @@ var init_app_config = __esm({
   "../../core/dev-server/src/app-config.ts"() {
     init_wix_cache_policy();
     init_l10n();
+    init_auth_gate_screen();
     init_preview_surfaces();
     init_wix_push_links();
     SHARED_WIX_SENTRY_DSN = "https://5dfa4f23057c43149b6219c07d177472@sentry.io/84240";
@@ -32305,6 +32331,7 @@ var init_define_app = __esm({
   "../../core/ts/src/define-app.ts"() {
     init_locale();
     init_distribution();
+    init_auth_gate_screen();
     init_schema2();
     init_base44_entities();
     init_src3();

package/guides/sdk-reference.json

@@ -5209,7 +5209,7 @@
         "name": "auth",
         "kind": "const",
         "jsdoc": "",
-        "decl": "export const auth = {\n  /** Current identity (visitor vs member vs owner) + who. */\n  async getIdentity(): Promise<WixIdentity> {\n    const r = await call<Partial<WixIdentity>>(\"authIdentity\");\n    return {\n      authenticated: r?.authenticated ?? false,\n      type: (r?.type as WixIdentityType) ?? \"anonymous\",\n      userId: r?.userId ?? null,\n      email: r?.email ?? null,\n    };\n  },\n  /** True when a member/owner is signed in. */\n  async isAuthenticated(): Promise<boolean> {\n    return (await auth.getIdentity()).authenticated;\n  },\n  /** The current access/member token (or null when anonymous). */\n  async getAccessToken(): Promise<string | null> {\n    const r = await call<{ token?: string }>(\"authAccessToken\");\n    return r?.token && r.token.length > 0 ? r.token : null;\n  },\n  /** Sign in (hosted Wix login → member token). Resolves with the new identity. */\n  signIn(): Promise<WixIdentity> { return authTransition(\"authSignIn\"); },\n  /** Sign out — clears the member token (visitor session may persist). */\n  signOut(): Promise<WixIdentity> { return authTransition(\"authSignOut\"); },\n  /** Mint/return a per-business signed instance for authorized Wix REST calls —\n   *  the ONE canonical worker-facing signed-instance accessor (RFC 0043 D3). A\n   *  worker never hand-rolls the mint HTTP; it calls this. `type` is the full Wix\n   *  identity matrix (owner=`User`, member, visitor, plus the Velo-scoped\n   *  variants) — mirrors @himalaya/wix-auth `SignedInstanceType`.\n   *\n   *  When the app provisions `real.auth`, it mints through the REAL Wix endpoint\n   *  (the same `one-app-ses\n/* … */"
+        "decl": "export const auth = {\n  /** Current identity (visitor vs member vs owner) + who. */\n  async getIdentity(): Promise<WixIdentity> {\n    const r = await call<Partial<WixIdentity>>(\"authIdentity\");\n    return {\n      authenticated: r?.authenticated ?? false,\n      type: (r?.type as WixIdentityType) ?? \"anonymous\",\n      userId: r?.userId ?? null,\n      email: r?.email ?? null,\n    };\n  },\n  /** True when a member/owner is signed in. */\n  async isAuthenticated(): Promise<boolean> {\n    return (await auth.getIdentity()).authenticated;\n  },\n  /** The current access/member token (or null when anonymous). */\n  async getAccessToken(): Promise<string | null> {\n    const r = await call<{ token?: string }>(\"authAccessToken\");\n    return r?.token && r.token.length > 0 ? r.token : null;\n  },\n  /** Sign in, resolving with the new identity. With a real provider bound to the app's session\n   *  gate this presents the real sign-in as a full-screen cover over the current screen — the\n   *  app's `auth.config.gateScreenId` screen if set, else the stock login, opened on `intent`\n   *  (default `\"login\"`) — and resolves once the user is signed in. Dismissing it rejects with\n   *  `err.code === \"cancelled\"`; a second call while one is up rejects `\"sign_in_in_progress\"`.\n   *  The calling worker survives the sign-in. Before the provider is bound it rejects\n   *  `sign_in_unavailable`, as on web; only a shell with no session gate keeps the dev seam. */\n  signIn(opts?: { intent?: \"login\" | \"signup\" }): Promise<WixIdentity> {\n    return authTransition(\"authSignIn\", { intent: opts?.intent ?? \"login\" });\n  },\n  /** Sign out — clears the member token (visitor session may persist). */\n  signOut(): Promise<WixIdentity> { return authTransition(\"authSignOut\"); },\n  /** Mint/return a per-business signed instance for authorized Wix REST calls —\n   *  the ONE canonical worker-facing signed-instance accessor (RFC 0043 D3). A\n   *  worker never hand-rolls the mint HTTP; it calls this. `type` is the full Wix\n   *  identity matrix (owner=`User`, member, visitor, plus the Velo-scoped\n   *  variants) — mirrors @himalaya/wix-auth `SignedInstanceType`.\n   *\n   *  When the app provisions `real.auth`, it mints through the REAL Wix endpoint\n   *  (the same `one-app-session-web` mint the Owner/Spaces bundles used ad-hoc),\n   *  so it is observed like any other Wix call; otherwise (and on any failure) it\n   *  uses the native dev seam. */\n  async signedInstance(businessId: string, type: WixSignedInstanceType = \"User\"): Promise<string | null> {\n    if (isMemberReal(\"auth\")) {\n      try {\n        const r = await realWix<{ signedInstance?: string }>(\n          \"GET\",\n          `https://apps.wix.com/_api/one-app-session-web/v3/businesses/${encodeURIComponent(businessId)}/signed-instance?signed_instance_type=${type}`,\n        );\n        if (typeof r?.signedInstance === \"string\" && r.signedInstance.length > 0) return r.signedInstance;\n      } catch { /* fall through to the dev seam */ }\n    }\n    const r = await call<{ signedInstance?: string }>(\"authSignedInstance\", { businessId, type });\n    return r?.signedInstance && r.signedInstance.length > 0 ? r.signedInstance : null;\n  },\n};"
       },
       {
         "name": "WixSiteScope",
@@ -5227,7 +5227,7 @@
         "name": "site",
         "kind": "const",
         "jsdoc": "",
-        "decl": "export const site = {\n  /** Scope to a business by metaSiteId; resolves after the per-site instance mints. */\n  setActiveSite(msid: string): Promise<{ ok: boolean; msid: string }> { return scopeToSite(msid); },\n  /** The metaSiteId currently scoped (\"\" if none). */\n  async activeSite(): Promise<string> {\n    const r = await call<{ msid?: string }>(\"siteActive\");\n    return r?.msid ?? \"\";\n  },\n  /** The customer's business/site info (identity + locale + contact) from Wix Site\n   *  Properties v4 (RFC 0048). Unlike bi/experiments, this is a plain REST GET: it\n   *  rides the wixApi transport — the same chokepoint the dev gateway observes /\n   *  mocks and prod binds — scoped to the active site's `User` signed instance, so\n   *  there is no native dev seam and no `real.site` flag. Returns `null` when no Wix\n   *  transport is installed (a non-Wix app) or the call fails, so callers degrade\n   *  gracefully. The ONE door for business info (RFC 0043) — a worker should call\n   *  this rather than hand-rolling `wixApi.call(\".../site-properties/...\")`. */\n  async getBusinessInfo(): Promise<WixBusinessInfo | null> {\n    if (typeof wpHost().wixApi?.call !== \"function\") return null;\n    try {\n      const res = await realWix<{ properties?: RawSiteProps } & RawSiteProps>(\n        \"GET\", \"/site-properties/v4/properties\",\n      );\n      return parseBusinessInfo(res);\n    } catch {\n      return null;\n    }\n  },\n\n  /** A handle that runs calls against ONE business, without moving the active site.\n   *\n   *  `setActiveSite` re-scopes the whole process — every later call, every worker, the\n/* … */"
+        "decl": "export const site = {\n  /** Scope to a business by metaSiteId; resolves after the per-site instance mints. */\n  setActiveSite(msid: string): Promise<{ ok: boolean; msid: string }> { return scopeToSite(msid); },\n  /** The metaSiteId currently scoped (\"\" if none). */\n  async activeSite(): Promise<string> {\n    const r = await call<{ msid?: string }>(\"siteActive\");\n    return r?.msid ?? \"\";\n  },\n  /** The customer's business/site info (identity + locale + contact) from Wix Site\n   *  Properties v4 (RFC 0048). Unlike bi/experiments, this is a plain REST GET: it\n   *  rides the wixApi transport — the same chokepoint the dev gateway observes /\n   *  mocks and prod binds — scoped to the active site's `User` signed instance, so\n   *  there is no native dev seam and no `real.site` flag. Returns `null` when no Wix\n   *  transport is installed (a non-Wix app) or the call fails, so callers degrade\n   *  gracefully. The ONE door for business info (RFC 0043) — a worker should call\n   *  this rather than hand-rolling `wixApi.call(\".../site-properties/...\")`. */\n  async getBusinessInfo(): Promise<WixBusinessInfo | null> {\n    if (typeof wpHost().wixApi?.call !== \"function\") return null;\n    try {\n      const res = await realWix<{ properties?: RawSiteProps } & RawSiteProps>(\n        \"GET\", \"/site-properties/v4/properties\",\n      );\n      return parseBusinessInfo(res);\n    } catch {\n      return null;\n    }\n  },\n\n  /** A handle that runs calls against ONE business, without moving the active site.\n   *\n   *  `setActiveSite` re-scopes the whole process — every later call, every worker, the\n   *  conducted cache and the entity cache all move with it. That is right for \"the owner\n   *  picked a business to manage\", and wrong for \"show me tonight's covers across all\n   *  three restaurants\": a rollup needs N businesses readable AT ONCE, and switching\n   *  between them to read each one serially is both slow and destructive of the scope the\n   *  user is actually in.\n   *\n   *  The returned object IS a `WixSiteScope`, so it can be handed straight to a generated\n   *  client as its options bag — `searchOrders(req, site.forSite(msid))` — and it also\n   *  carries `call` for a raw path the typed clients do not cover. Fan several out with\n   *  `Promise.all` and each one keeps its own business.\n   *\n   *  Only reaches businesses the signed-in user owns: the header names a business, and\n   *  Wix refuses to mint an instance for one they do not. A consumer app (one Headless\n   *  clientId, one site) does not mint per-site at all, so this is inert there — see\n   *  the branded-lite-site-binding guide. */\n  forSite(msid: string): WixSiteScope {\n    const scoped = (msid ?? \"\").trim();\n    return {\n      site: scoped,\n      async call<T>(method: string, path: string, body?: unknown): Promise<T> {\n        const api = wpHost().wixApi;\n        if (!api) throw new Error(\"wixApi bridge unavailable\");\n        // A blank msid would silently read the AMBIENT business, which is the one\n        // failure mode a cross-site rollup cannot tolerate: it would attribute one\n        // business's rows to another with nothing in the response to show for it.\n        if (!scoped) throw new Error(\"site.forSite: a metaSiteId is required\");\n        return (await api.call(method, path, body, { \"wix-site-id\": scoped })) as T;\n      },\n    };\n  },\n};"
       },
       {
         "name": "monitoring",

package/guides/web-page-sdk-reference.md

@@ -54,4 +54,4 @@ the SDK sources, so it matches the shipped SDKs.
 - [`ui`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fui?format=md) — Imperative popup capability. 2 methods · not in Brandy.
 - [`wix_cashier`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fwix_cashier?format=md) — Native cashier. 2 methods.
 - [`wix_chat`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fwix_chat?format=md) — Host-owned realtime Chat event subscriptions. 2 methods.
-- [`wix_platform`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fwix_platform?format=md) — Wix Platform SDK, worker-facing bindings. 30 methods · not in Brandy.
+- [`wix_platform`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fwix_platform?format=md) — Wix Platform SDK, worker-facing bindings. 27 methods · not in Brandy.

package/guides/wix-login-integration.md

@@ -58,14 +58,14 @@ can't be built (see §Fail-closed). One place; all platforms read the baked outp
 
 ## Step 2 — bake → `auth.json`
 
-`tools/auth-bake/bake-auth.ts` reads `config.ts`, lifts `required` to the top level, **scrubs any
+`tools/auth-bake/bake-auth.ts` reads `config.ts`, lifts `required` (and `gateScreenId`, below) to the top level, **scrubs any
 `secret`/`private` key**, and writes `auth.json` into the iOS bundle, Android assets, and (when
 present) the macOS bundle resources:
 
 ```
 node --import tsx tools/auth-bake/bake-auth.ts apps/<app> --ios apps/<app>/ios/<target> --android apps/<app>/android/<module> --macos apps/<app>/macos/<target>
 ```
-`auth.json` = `{ providerId, required, config }`. Read by `TemplateAppBoot.loadBakedAuth()` (iOS
+`auth.json` = `{ providerId, required, gateScreenId?, config }`. Read by `TemplateAppBoot.loadBakedAuth()` (iOS
 and macOS) / `TemplateAuth.boot()` (Android).
 
 ## Step 3 — wire the gate (per platform)
@@ -76,13 +76,16 @@ and macOS) / `TemplateAuth.boot()` (Android).
   instantiate via `AuthProviderRegistry.shared.instantiate(providerId:config:)`, `sessionGate.bind(to: provider)`,
   set `sessionGate.formMode = .emailEntry` for native, and **bind the transport**:
   `wixApiCapability = WixApiCapability(authProvider: provider, mobileContext: …)`.
-- The SwiftUI root observes `sessionGate.state` + `authRequired` → shows `AuthGateView` until authenticated.
+- The SwiftUI root wraps its content in the core `AuthGateRoot(gate:required:gateScreen:content:)`, which
+  shows the gate until `sessionGate.state` is authenticated (the stock `AuthGateView`, or the app's own gate
+  screen — below) and presents a worker's mid-session sign-in over the content.
 
 ### Android
 - Gradle: add the `:himalaya-wix-auth` module (settings + `implementation(project(":himalaya-wix-auth"))`).
 - In `Application.onCreate()`: `HimalayaWixAuth.register()` **before** `TemplateAuth.boot(applicationContext)`
   (which reads `assets/auth.json`, instantiates via the registry, and `gate.bind(provider, scope)`).
-- The root composition observes `TemplateAuth.gate` + `TemplateAuth.required` → shows `AuthGateScreen`.
+- The root composition calls the core `AuthGateRoot(gate, required, gateScreen, content)` with
+  `TemplateAuth.gate` + `TemplateAuth.required` — the stock `AuthGateScreen` or the app's own gate screen.
 - Bind the transport where you make Wix calls: `WixApiCapability(authProvider = provider)`.
 
 ### macOS
@@ -154,6 +157,55 @@ their own message; the primary button sends a new request, and the method picker
 factor at any time. Dev seam accounts: `2fa-push@himalaya.dev` (approves) and
 `2fa-push-deny@himalaya.dev` (declines), password `Passw0rd!`.
 
+## Your own gate screen and mid-session sign-in (`gateScreenId`, `auth.signIn`)
+
+Name a screen the app ships as its auth gate, and the stock login steps aside:
+
+```ts
+const native = WixNativeAuthProvider({ mode: "consumer", clientId: "…" });
+// …
+auth: { ...native, config: { ...native.config, required: true, gateScreenId: "welcome" } },
+```
+
+(The provider factories forward only their own keys, so `required` and `gateScreenId` go on the
+returned block's `config`, which is what the bake and the OTA derivation read.)
+
+`defineApp` checks the shape; the app-config derivation drops, and the auth bake refuses, a `gateScreenId`
+that is not one of the app's exact screens (a templated route is never a gate screen: a release serves
+exact screens). It is lifted next to `required` in `auth.json` and the OTA `authConfig`, read with
+`AuthBoot.gateScreenId(baked:ota:)` (Kotlin: `AuthBoot.gateScreenId(baked, ota)`) into
+`SessionGate.gateScreenId`. A required-auth launch then shows that screen — the ordinary screen host,
+worker and bindings included, as a full-screen root with no tab bar. It must be an exact screen
+(a release serves exact screens): the auth bake and the app validation gate refuse anything else.
+
+The screen drives sign-in only through `auth.*` actions, which `sessionGate.registerAuthActions()`
+installs on the dispatcher — the credential never passes through app code:
+
+| Action | Does |
+|---|---|
+| `auth.signIn` `{ intent: "login" \| "signup" }` | opens the provider's own login in that mode — wix-native: the in-app form in sign-in / register mode, over the gate screen (with a Back, `auth_gate_back`); a hosted provider: its hosted page (`intent` is a hint) |
+| `auth.cancel` | closes a mid-session sign-in (the worker's call rejects `cancelled`), else steps back to the gate screen |
+| `auth.socialSignIn`, `auth.setFormMode`, `auth.forgotPassword`, `auth.continueWithEmail`, biometric verbs | the existing set, routed to the gate |
+
+The credential-carrying actions (`auth.signInWithPassword`, `auth.register`, `auth.submit2FA`) are
+deliberately **not** routed from screens: a screen's controls can bind their params to anything, so a
+password typed into an app screen would pass through app code. A gate screen opens the provider's own
+form with `auth.signIn`, and only that native form supplies a credential. The gate actions accept a
+dispatch from a screen's own controls only — not from a worker, an agent, or a WebView page.
+
+**Mid-session sign-in.** With a real provider bound to the gate, a worker's
+`wixPlatform.auth.signIn({ intent })` presents the sign-in as a full-screen cover over the current screen —
+the `gateScreenId` screen if set, else the stock gate — and resolves with the new identity once the gate is
+authenticated. Closing it (`auth_signin_cover_close`) rejects with `err.code === "cancelled"`; a second
+call while one is up rejects `sign_in_in_progress`. The calling worker survives. The cover is part of
+`AuthGateRoot`, and while it is mounted it is what `capability.wix_platform.authSignIn` routes to: with no
+provider bound to the gate (yet, on a cold launch, or at all) it rejects `sign_in_unavailable` — never the
+dev seam's demo member. Only a shell with no `AuthGateRoot` keeps the dev seam; on web, so does a host
+with no live Wix member bridge.
+
+Shells are copied when an app is scaffolded: a new app's shell calls `AuthGateRoot`, while an app
+scaffolded before keeps its inline stock gate until its root switches to the helper.
+
 ## Fail-closed (`required: true`)
 
 If a required-auth app can't build its provider (unknown `providerId`, missing config key), boot sets a

package/guides/wix-platform-usage.md

@@ -2,7 +2,7 @@
 
 `@himalaya/wix-platform` is the T5-worker-facing surface of the Wix Platform SDK. It is
 **platform-agnostic** — the same JS runs on iOS, Android, macOS and web, with **one documented
-exception**: on web, `auth.signIn()` rejects rather than resolving (see
+exception**: `auth.signIn()` can reject, with an `err.code`, on every platform (see
 [Real vs dev seam](#real-vs-dev-seam-and-best-effort) below). Each
 member dispatches to the native `wix_platform` capability (with an on-device dev seam);
 `bi`, `monitoring`, `session` and `auth` take their real backend when the app enables them
@@ -76,22 +76,37 @@ await monitoring.captureError("thing failed", { code: "E1" });
   `real.deeplink` are ignored.
 - `bi`, `monitoring`, and `auth` route through their native backends (Frog sink, Sentry
   sink, `WixNativeAuthProvider`) rather than raw `wixApi`, but the calling contract is
-  identical — **except `auth.signIn()` on web**, below.
+  identical — **except `auth.signIn()`, which can reject on every platform**, below.
 
-### `auth.signIn()` on web is the one member that rejects
+### `auth.signIn({ intent })` on a real provider
 
-`auth.signIn()` is the **native** hosted-login path. On web it starts no session and
-**rejects with `sign_in_unavailable`** in both of the cases you will actually meet: when no
-member session can be started, and when the member bridge is unreachable. It resolves only
-when that bridge already holds a member, in which case it reports who.
+On iOS, macOS and Android, when the shell has a real provider bound to its session gate (an app on the
+core `AuthGateRoot`), `auth.signIn({ intent: "login" | "signup" })` presents the real sign-in as a
+full-screen cover over the current screen and resolves with the signed-in identity. Closing it rejects with
+`err.code === "cancelled"`, and a second concurrent call rejects `sign_in_in_progress` — so handle the
+rejection. Before the boot has bound the provider (or in such a shell with none) it rejects
+`sign_in_unavailable`; only a shell with no core `AuthGateRoot` keeps the dev seam's demo member. See
+[wix-login-integration](wix-login-integration.md#your-own-gate-screen-and-mid-session-sign-in-gatescreenid-authsignin).
 
-So this is the one member where the "never throws" rule above does not hold, and a worker
-must handle it:
+### `auth.signIn()` is the one member that rejects
+
+`auth.signIn()` is the one member where the "never throws" rule above does not hold — on
+native and on web alike, and always with an `err.code`:
+
+- `cancelled` — the user closed the sign-in (native).
+- `sign_in_in_progress` — another sign-in is already up (native).
+- `sign_in_unavailable` — no sign-in can be shown: on native, before the provider is bound or
+  where the shell cannot present one; on web, always unless the member bridge already holds a
+  member (then it resolves and reports who). Web starts no session itself: it rejects both
+  when no member session can be started and when the member bridge is unreachable.
+
+So a worker must handle it, and can branch on the code:
 
 ```js
 try {
-  await auth.signIn();
-} catch {
+  await auth.signIn({ intent: "login" });
+} catch (err) {
+  if (err.code === "cancelled") return; // the user said no — leave the screen as it was
   // "sign-in isn't available here" — render a real state, not a dead button.
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1470.0",
+  "version": "0.1471.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "e9bd938455d5133edf89ef9ba48bc6e52cc885a2d0cf82d2a56ea5bb"
+  "falconPackageHash": "cd4d5ceeaf1823831031129d85d33f4d35a9aa4e5bfd8804fe964fe1"
 }