@wix/himalaya-cli 0.1469.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

@@ -18675,7 +18675,6 @@ function resolveIdiom(tokens2, ctx = {}) {
 var IDIOM_CONTEXTS, UNSAFE_KEYS;
 var init_idiom = __esm({
   "../../core/ts/src/idiom.ts"() {
-    "use strict";
     IDIOM_CONTEXTS = {
       ios: { native: ["ios"] },
       android: { native: ["material"] },
@@ -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();
@@ -162443,33 +162470,33 @@ var init_preview_assets_generated = __esm({
   "../../packages/serve/src/preview-assets.generated.ts"() {
     init_preview_assets_format();
     PREVIEW_ASSET_MANIFEST = [
-      { key: "assets/DashboardHost-C8q83QJ2.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 2916, sha256: "144b7dc6e3662aa62ea0e8e03e9aae7762dc3dc2f63da56e8b04b1bb70db89ad" },
-      { key: "assets/DevDrawer-DsUG7Nml.js", contentType: "application/javascript; charset=utf-8", offset: 2924, length: 16744, sha256: "7bcc9801a17aa2ba526fb0983ea315581e3ac2d4c45f625b719df716be0cd9c0" },
-      { key: "assets/IdiomCompare-Cthh0ISj.js", contentType: "application/javascript; charset=utf-8", offset: 19668, length: 1892, sha256: "eab302721e7b8202f10d0c622d57b0dc28b3ab9ae3fe07b20a2563198ffd88d1" },
-      { key: "assets/LightboxViewer-ASOCRp41.js", contentType: "application/javascript; charset=utf-8", offset: 21560, length: 8132, sha256: "46ab57a241855a13a17f94fec2a70ce9b45c1a4c3e54801c8c679328256edb33" },
-      { key: "assets/PhonePreviewControl-B6cU9zp5.js", contentType: "application/javascript; charset=utf-8", offset: 29692, length: 37729, sha256: "c5550c028620913776998cf8818e8f9f794c02f5d234b7aeaf71671bf9080373" },
-      { key: "assets/SchemeCompare--If17_u5.js", contentType: "application/javascript; charset=utf-8", offset: 67421, length: 1824, sha256: "66285df0006380de22ced18317a59c08ba318788d73d717a321ff1e5460c1fa0" },
-      { key: "assets/index-CKaODCvf.js", contentType: "application/javascript; charset=utf-8", offset: 69245, length: 1280616, sha256: "6a91080524cebb84370c0fb3c04d74c99b2d704cb003a21f2e01912e7f47c0b2" },
-      { key: "assets/pdf-B2304dXw.js", contentType: "application/javascript; charset=utf-8", offset: 1349861, length: 488199, sha256: "b284e54724b9ac6fd9b9dbddaf42c4a564d9ea1cb8ec0d78ea5b3c132c20cb41" },
-      { key: "assets/pdf.worker.min-BQa_JDET.js", contentType: "application/javascript; charset=utf-8", offset: 1838060, length: 73, sha256: "41bcfda4f3c8c0a81c785ea87c69afc8e7d0ed8c333324aee94c273d881bb6aa" },
-      { key: "assets/pdf.worker.min-BmVo14Nb.mjs", contentType: "application/javascript; charset=utf-8", offset: 1838133, length: 1317034, sha256: "a33cfe728c584fdba4fcc1fd54bcdc2f9f2f13889ddbb5b2bd1d0f8cbe49b84e" },
-      { key: "assets/pdfDocument-C5bi6q0r.js", contentType: "application/javascript; charset=utf-8", offset: 3155167, length: 3379, sha256: "ac6eff0d1c637a70fade3bd860a7dc531b1b1b4301012d3daf120b7a3ea9b7e6" },
-      { key: "assets/pdfFetch-Cc8i1I1h.js", contentType: "application/javascript; charset=utf-8", offset: 3158546, length: 2266, sha256: "1d21ad008921942217c9eac0c35b1713773b9d89c71e3ab4412781f7bb88f463" },
-      { key: "fonts/Roboto-LICENSE.txt", contentType: "application/octet-stream", offset: 3160812, length: 4610, sha256: "994062dd7af4186a739de55dd9e151c63b6301f8e2cbafc608d35c2e87da0cd2" },
-      { key: "fonts/Roboto-Variable.ttf", contentType: "font/ttf", offset: 3165422, length: 488584, sha256: "d7598e12c5dbef095ff8272cfc55da0250bd07fbdecbac8a530b9b277872a134" },
-      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 3654006, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
-      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 3744930, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
-      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 3835914, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
-      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 3926894, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
-      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 4017766, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
-      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 4108746, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
-      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 4217382, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
-      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 4326466, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
-      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 4435514, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
-      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 4543214, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
-      { key: "himi-sw.js", contentType: "application/javascript; charset=utf-8", offset: 4631322, length: 6748, sha256: "4a92459977d7cefa1a6a7e020c3a63509737f083b3f2773557c1a5771665811a" },
-      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 4638070, length: 4947, sha256: "8a3f524b30f25db213d2458d71a38298f4fbdcc8989bd0eee91428809bf45832" },
-      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 4643017, length: 17786, sha256: "084107ca997628c248f1b0ba3a7494744850df39fad813546ab8bdb82a6058da" }
+      { key: "assets/DashboardHost-V5OQ2K0K.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 2916, sha256: "51ffc72d485d4ef05c15c2da0d9435512721fa7b01334bd732ec1b65f19a165f" },
+      { key: "assets/DevDrawer-nAjavZLQ.js", contentType: "application/javascript; charset=utf-8", offset: 2924, length: 16744, sha256: "6fc1ae053f7f867093be7edd0cbc65121817adf72eb334af01c460bbdc4242d7" },
+      { key: "assets/IdiomCompare-CBKM_S6c.js", contentType: "application/javascript; charset=utf-8", offset: 19668, length: 1892, sha256: "55cbee8a082eb538f24cce371cd8cb86cf65dfbf7529e0ca2950507025627879" },
+      { key: "assets/LightboxViewer-d79GF3xc.js", contentType: "application/javascript; charset=utf-8", offset: 21560, length: 8132, sha256: "da5c8e29fa275b18467b2fc2793b74ebafead3357b1279f4465c0a2c3aab2a2d" },
+      { key: "assets/PhonePreviewControl-Cucnf6Lt.js", contentType: "application/javascript; charset=utf-8", offset: 29692, length: 37729, sha256: "ffb76986217eda36654aee1f77d9a69161fb38fda429becc35fa50603863c1ff" },
+      { key: "assets/SchemeCompare-Dj7pGZhQ.js", contentType: "application/javascript; charset=utf-8", offset: 67421, length: 1824, sha256: "61a467006401d83c9a168ccc3a7451d214d626a2bf85e1e3804a4dfe58985128" },
+      { key: "assets/index-hGM0n8mX.js", contentType: "application/javascript; charset=utf-8", offset: 69245, length: 1280687, sha256: "7dccbf4a3a5df57f59626ecee1e5a91b83e4626aea676212e6113a556b8a8c63" },
+      { key: "assets/pdf-BBk86PYz.js", contentType: "application/javascript; charset=utf-8", offset: 1349932, length: 488199, sha256: "8f41e595d8318953e766d0d4286e385f1d4053bfdd66981eb35b2ff3dacc3f5f" },
+      { key: "assets/pdf.worker.min-BQa_JDET.js", contentType: "application/javascript; charset=utf-8", offset: 1838131, length: 73, sha256: "41bcfda4f3c8c0a81c785ea87c69afc8e7d0ed8c333324aee94c273d881bb6aa" },
+      { key: "assets/pdf.worker.min-BmVo14Nb.mjs", contentType: "application/javascript; charset=utf-8", offset: 1838204, length: 1317034, sha256: "a33cfe728c584fdba4fcc1fd54bcdc2f9f2f13889ddbb5b2bd1d0f8cbe49b84e" },
+      { key: "assets/pdfDocument-DPaMY0jZ.js", contentType: "application/javascript; charset=utf-8", offset: 3155238, length: 3379, sha256: "f33b3711fc1c56bbf3dd45b013bb05e1d5bdca8843d975ce8a7c058025963b13" },
+      { key: "assets/pdfFetch-Cc8i1I1h.js", contentType: "application/javascript; charset=utf-8", offset: 3158617, length: 2266, sha256: "1d21ad008921942217c9eac0c35b1713773b9d89c71e3ab4412781f7bb88f463" },
+      { key: "fonts/Roboto-LICENSE.txt", contentType: "application/octet-stream", offset: 3160883, length: 4610, sha256: "994062dd7af4186a739de55dd9e151c63b6301f8e2cbafc608d35c2e87da0cd2" },
+      { key: "fonts/Roboto-Variable.ttf", contentType: "font/ttf", offset: 3165493, length: 488584, sha256: "d7598e12c5dbef095ff8272cfc55da0250bd07fbdecbac8a530b9b277872a134" },
+      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 3654077, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
+      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 3745001, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
+      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 3835985, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
+      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 3926965, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
+      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 4017837, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
+      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 4108817, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
+      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 4217453, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
+      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 4326537, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
+      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 4435585, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
+      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 4543285, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
+      { key: "himi-sw.js", contentType: "application/javascript; charset=utf-8", offset: 4631393, length: 6748, sha256: "4a92459977d7cefa1a6a7e020c3a63509737f083b3f2773557c1a5771665811a" },
+      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 4638141, length: 4947, sha256: "62d2720e80f14dbdf428b7ca55b4b8ce77f5fe8db1d89ca5d1b96d1886c6ce93" },
+      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 4643088, length: 17786, sha256: "084107ca997628c248f1b0ba3a7494744850df39fad813546ab8bdb82a6058da" }
     ];
   }
 });

package/guides/hhp.md

@@ -147,10 +147,10 @@ transitions, haptics, and measurement remain explicit native modifiers.
 
 Local HTML images resolve relative to their document and must live in the app's
 declared assets directory. They use the existing content-addressed asset channel.
-The descriptor carries a host-less `/v1/asset/<sha>?app=<id>` URL. iOS and Android
-resolve it against the origin that served the screen; on web it resolves against the page,
-so it loads when the web host is served from the serve origin (`himi run`, `/app/a/<id>`)
-but not yet behind a gateway path prefix or inside an embed.
+The descriptor carries a host-less `/v1/asset/<sha>?app=<id>` URL. iOS, Android, the
+web host and the embed SDK resolve it against the serve origin, so it loads same-origin,
+behind a gateway path prefix, or inside an embed. React Native and web dashboard widget
+cards do not rebase it yet.
 
 iOS and Android have no SVG image decoder. When an `<img>` points at a package
 `.svg`, the compiler renders it to a PNG at 3x the SVG's intrinsic size, writes

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.1469.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": "e2945d7b80de52bf863696df0c6b64a9caa17dc8ad0f21e3505b1ee9"
+  "falconPackageHash": "cd4d5ceeaf1823831031129d85d33f4d35a9aa4e5bfd8804fe964fe1"
 }