@wix/himalaya-cli 0.1568.0 → 0.1570.0

package/guides/app-config.md

@@ -79,6 +79,16 @@ your envelope + per-surface links), and `himi render <screen> --device mac|watch
 
 ## Splash (the launch moment)
 
+**T5 Branded Lite apps:** when the existing exact screen registry contains
+`himi_branded_splash`, its descriptor/worker owns the editable in-app appearance.
+Read `himi docs splash-screens` before editing: change its `input.showIcon`, the
+root background token and the gradient token's colours/stops/angle. CSS angles such
+as 90 (horizontal) and 135 (diagonal) are supported by that T5 layer. Preserve the
+native fallback and binary OS launch settings. Generated packages keep the descriptor
+in `dev/index.ts` and the worker in `tier5-src/`. Do not assume an older native
+host can mount a newly added screen. The following contract describes the native
+fallback and legacy apps; it is not the T5 appearance editor.
+
 `splash` is ONE declaration with TWO consumers, and only the second is OTA:
 
 - **Build time** — `splash.backgroundColor` (a color TOKEN name, never a hex) generates the

package/guides/app-icon.md

@@ -26,6 +26,7 @@ it. Offer the customer the choice — it is their brand:
 ```sh
 himi icon status                      # what would ship right now, and whether a store would take it
 himi icon from-site --book .himi/business-book   # the logo `himi site analyze` downloaded
+himi icon from-one-app --evidence-dir .himi/one-app # the verified collected app's existing logo
 himi icon set ./their-logo.png        # a file the customer supplied
 himi icon generate                    # a gradient tile + glyph, for a customer with no mark
 himi icon glyphs                      # what `generate --glyph` accepts
@@ -44,10 +45,22 @@ nobody has said what the app is. So pick one with `--glyph` when you know
 (`himi icon glyphs` lists them, `book` and `graduation` among them), and read the neutral
 tile as what it is — a placeholder, still waiting for the customer's real mark.
 
-`set`, `from-site` and `generate` all do the same finishing work: **trim** the art, centre
+`set`, `from-site`, `from-one-app` and `generate` all do the same finishing work: **trim** the art, centre
 it, **flatten it onto your app's accent colour**, write it as an exactly-1024 square with no
 alpha channel, derive the 512 Play listing icon, and record it in `himalaya.content.json`.
 
+Source images accept at most 16 MiB of encoded input and a 2048-square decoded canvas.
+SVGs use density-bounded rasterization before normalization, under the same pixel cap.
+Animated GIF/WebP marks use a composited poster with the most distinguishable artwork,
+measured against one background reference for the animation. Review the resulting mark
+against the source. Poster decoding accepts at most 256 frames, a 4-million-pixel canvas,
+64 million total frame pixels and 16 MiB of encoded input; larger animations are refused
+with advice to supply the existing static mark. Other multi-page formats retain their
+first-page behavior. `from-one-app` requires the image toolchain before downloading or
+replacing an icon, so it cannot report success without normalization and the Play rendition.
+It checks both renditions in a scratch package before installing them; a rejected source
+leaves the current master, Play icon and manifest unchanged.
+
 **The declaration is the part people miss.** An off-repo package's icon is whatever
 `himalaya.content.json` names:
 
@@ -62,6 +75,12 @@ declare is art nothing ships: the release bakes no icon, and a binary then falls
 `himi icon` writes both halves, and `himi validate` / `push` / `dist` refuse a package whose
 declared icon is missing.
 
+Customer native builds copy the contract's prepared master into the iOS and Android
+launcher resources. The shared Mac materializer resizes that same master into all ten
+`AppIcon.appiconset` renditions and writes their catalog metadata; it preserves the source
+artwork. A platform-only preparation writes only that platform's native tree. Existing
+binaries need rebuilding to pick up a changed launcher icon.
+
 ## What each store wants
 
 The two specs **conflict**, so these are two derived files and neither can serve both:

package/guides/getting-started.md

@@ -33,6 +33,11 @@ and template-preview journey below. Write the reconstruction plan, `SPEC.md`,
 same-site One App visitor binding, checks and hosted draft. Obtain the
 site owner's agreement before creating or updating an OAuth client for optional
 member flows; visitor reads and native email/password sign-in need no client.
+Before composing content, read `himi docs designing-himi-screens` and apply the
+migration guide's screen-content contract: readable detail sections, stable rail
+and image sizing, grouped icon rows for More, native bottom clearance and distinct
+loading/empty/error states. Put the relevant cases in `MOBILE-UX.md` and verify
+the generated screens; reading the guide is not layout evidence.
 Preserve the supplied layout and
 apply the user's separate optional prompt. Use `CI=1 himi init` with
 `--no-first-look`; do not execute its generic `doNow` / `doNowAgain` template-preview

package/guides/himi-json-output.md

@@ -32,6 +32,13 @@ keeps its existing fields and adds the code:
 }
 ```
 
+## `himi icon from-one-app` codes
+
+| Code | Meaning |
+| --- | --- |
+| `source_icon_unavailable` | Verified source evidence or its logo is missing, unreadable, unavailable, over the download/decoding budget, or cannot be normalized. |
+| `source_icon_unusable` | The prepared source mark fails mechanical launcher/store checks. Existing icon files and metadata are left unchanged. |
+
 ## Push codes
 
 | Code | Meaning |

package/guides/himi-skill.md

@@ -56,6 +56,11 @@ and template-preview journey below. Write the reconstruction plan, `SPEC.md`,
 same-site One App visitor binding, checks and hosted draft. Obtain the
 site owner's agreement before creating or updating an OAuth client for optional
 member flows; visitor reads and native email/password sign-in need no client.
+Before composing content, read `himi docs designing-himi-screens` and apply the
+migration guide's screen-content contract: readable detail sections, stable rail
+and image sizing, grouped icon rows for More, native bottom clearance and distinct
+loading/empty/error states. Put the relevant cases in `MOBILE-UX.md` and verify
+the generated screens; reading the guide is not layout evidence.
 Preserve the supplied layout and
 apply the user's separate optional prompt. Use `CI=1 himi init` with
 `--no-first-look`; do not execute its generic `doNow` / `doNowAgain` template-preview

package/guides/one-app-to-himi-app.md

@@ -195,10 +195,13 @@ Apply these interpretation rules:
 - Before publishing, run the migration-only top-bar coverage check:
   `himi one-app validate-topbar --evidence-dir .himi/one-app --content .`.
   It verifies the collected raw and platform-enriched evidence hashes, then checks
-  authored cart/chat settings and the resolved platform top-bar button definitions
+  authored cart/chat/Invite settings and the resolved platform top-bar button definitions
   against tappable `navigation.topBarDefault.actions` or mapped
   `ScreenDescriptor.topBar.actions` when a screen replaces the default. A dynamic
-  bar that cannot be inspected is reported as unverified. Platform definitions establish
+  bar that cannot be inspected is reported as unverified. The maintained `inviteAction`
+  builder is recognized; its conditional ID and hidden binding must also appear in
+  `topBarDefault.actions` with a configured `navLogicBundle`, even when the screen
+  overrides its bar. A screen-only binding is not subscribed. Platform definitions establish
   a feature to account for; they do not alone prove visibility or access for every
   visitor or member. Resolve those rules separately. This check is specific to this
   migration workflow; it does not change the behavior of `himi validate`.
@@ -250,6 +253,32 @@ Apply these interpretation rules:
   `CollapsingHeader` hero/card above the page. This target adaptation supersedes
   the older instruction to reproduce the source cover header; the source
   research still explains how to interpret its settings.
+- **Business contact is shared content.** For native contact sections
+  `platform_general_contact_section` / `platform_general_contact_section_bp`, use
+  `businessContactSection` and `createBusinessContactService` from
+  `@wix/himalaya/screens`, rather than hand-authoring phone/URL/map rows. Pass
+  `businessContext.contact` as normalized public business evidence, retaining
+  `isPhysical` and numeric coordinates; combine the separate source website URL
+  and legacy phoneNumber only when the corresponding contact value is absent.
+  Pass source visibility/get-in-touch settings; mark BP settings with
+  `isBusinessProfile: true`. Empty normal settings receive source defaults,
+  while nonempty settings leave omitted visibility flags off. Map visibility
+  still follows source settings. An address-only business can offer external
+  directions, but invalid/incomplete/virtual points never become guessed
+  coordinates. Message opens the existing `himi_business_chat` route with its
+  normal auth behavior. The Branded app's source builder accepts the same data through
+  provisioning `businessContact: { contact, settings, showMemberCount, memberCount }`;
+  `himi_business_contact` is inherited by generated starters; adopt the same SDK
+  builder with normalized source inputs when authoring their baked descriptors.
+  Do not route business
+  contact to `himi_app_info`, which describes the app's support and release details.
+  Preserve member-count content outside obsolete custom header chrome when the
+  source requests it. Set the section's `showMemberCount` and pass the optional
+  public `businessContext.memberCount` through typed onAppear `args`. Omit an
+  unknown count, and show unavailable/error states; avatar/page lengths are not
+  totals. A collected total is a source snapshot. Only use an injected live
+  count reader when its public, site-bound permission path has been verified.
+  See the screens SDK's downloadable business-contact guide for the full recipe.
 - Emit resolved native actions in `navigation.topBarDefault` or a complete
   per-screen `topBar` override. The shell owns back/menu controls. Per-screen
   actions support `hiddenPath` when `navigation.topBarDefault.actions` declares
@@ -268,12 +297,78 @@ Apply these interpretation rules:
   access rules. Report unsupported avatar/logo/action behavior as a gap; do not
   invent member data, drop a configured CTA silently, or add an in-page toolbar
   to imitate a missing native control.
+- **Invite is behavior, independent of the custom cover.** When the source header's
+  `settings.showInviteButton` is true, use the reusable `inviteAction`, `inviteScreen`
+  and service recipes from `@wix/himalaya/screens`. The source opens an Invite modal;
+  the target uses a native screen whose explicit Share button owns creation and login.
+  For each source screen, use the corresponding generated
+  `.himi/one-app/invite-plan.json` metadata: its flag comes from the referenced
+  header and `businessId` from collected `manifest.source.metaSiteId`. Do not use
+  a public website as an invitation or copy an example business ID.
+
+  In the nav worker, mount `createInviteAvailabilityService({ source })` and
+  declare `share` and `app_info`. It only reads availability. Register
+  `inviteAction({ id: "source.invite", screenId: "source_invite" })` with the same
+  ID and hidden binding in `topBarDefault.actions` and every complete screen
+  override that needs it. A source screen with `showInviteButton: false` must
+  exclude Invite from its effective actions (use a complete screen override if
+  the default includes it). Unresolved top-bar visibility paths remain visible
+  under the current native resolver policy; the screen always rechecks source
+  availability and authorization before acting. The validator refuses opaque
+  action entries, including nested handlers/parameters and computed helper options.
+  Literal actions need literal `id`, `icon`, `label`, and `accessibilityLabel` values
+  when supplied so classification cannot silently discard an unknown Invite;
+  use native path bindings for live labels. If a disabled header flag conflicts with a collected native
+  Invite action, resolve that source-policy conflict before authoring the target.
+  Declare the Invite and existing member sign-in screens
+  in `navigation.linkableScreens`. Add
+  `inviteScreen({ screenId: "source_invite", bundleUrl: "/v1/bundles/source-invite" })`
+  to the screen registry. Its separate screen worker mounts:
+
+  ```ts
+  import { createInviteService } from "@wix/himalaya/screens";
+  export const invite = createInviteService({
+    source: () => sourceInvite, // this migration's bound flag/businessId or verified URL
+    signInScreenId: existingMemberSignInScreenId,
+  });
+  ```
+
+  The descriptor declares `share`, `wix_api` and `app_info`. `inviteButton` is also
+  available for ordinary page content owned by this screen service. Bind the same
+  current source metadata in both workers; never take the target from route params.
+  The reusable screen recipes include an Invite integration example.
+  The native nav worker stays alive across account switches, so it must not own
+  a fresh-load login continuation. The screen service uses shared confirmed
+  consumer auth continuation: its Share tap begins
+  an opaque host intent, opens the app's existing sign-in screen as a modal, and
+  a fresh screen load rechecks source, sharing availability and member identity
+  before atomically consuming the confirmed intent once. The sign-in worker must
+  forward that token with its existing credential action. Cancellation, expiry,
+  another account, bare routes and ordinary loads do not authorize an invitation.
+  Unsupported hosts show an update-required message without starting a guest write.
+  This requires the updated host continuation/auth SDK in rebuilt native binaries
+  or the updated web host; OTA content alone cannot supply it.
+
+  Business resolution additionally requires the explicit native host signal
+  `oneAppInviteAvailable === true`, supplied by the updated native core.
+  Old binaries and web fail closed for this resolver. A verified, already resolved
+  source invite URL can use sharing on web, including guest login continuation
+  on a supported host. An already signed-in member can share without a continuation.
+  On web, an expired browser activation is resumed by a host-owned Share/Copy
+  confirmation; this requires the updated web host and does not repeat the Invite
+  action or create another invitation. A cancelled or degraded share retains
+  incomplete-sharing feedback; it never reports a completed share.
+  Only a validated HTTPS URL from bound metadata or the source Invite response is
+  shared. No invitation is created while migrating or just loading the screen.
+  Source Invite produces an `interaction` coverage row requiring behavioral proof;
+  unresolved transport or permissions remain gaps, never silent omission.
 - Verify the migrated app's native top bar, bottom tabs, back navigation and
   configured actions on the affected devices, including RTL. A web screenshot
   alone does not prove native navigation or control availability. Record any
   unavailable device check as unverified.
-- Business context contains only `phoneNumber`, `website`, and `services`, with
-  their permitted nested values. Structure wins on authored phone/URL/design.
+- Business context contains `phoneNumber`, `website`, `services`, optional public
+  `contact`, and an optional validated public `memberCount`, with their permitted
+  nested values. Structure wins on authored phone/URL/design.
   Installed services do not add features. Installation IDs are not record IDs.
   Do not restore excluded Business titles, colors, identity or member fields.
 - Referenced editor-authored documents, such as Pages rich text, are presentation
@@ -349,6 +444,13 @@ those operations with fixtures, not real transactions. `MOBILE-UX.md` needs its
 acceptance states with one `Primary CTA` per cell and actual render widths under
 `## Evidence`.
 
+Before composing or adapting content, read `himi docs designing-himi-screens`.
+Apply the **Screen-content contract** in step 3 below to the
+reconstruction plan and its `MOBILE-UX.md` acceptance cases. Keep the source's
+content, order, actions and access rules; this contract supplies layout choices
+where a source section needs a native composition. It does not replace the
+native-navigation policy above or authorize a different business feature.
+
 Keep `.himi/one-app/migration-report.md` throughout the run. For every in-scope
 placement and interaction, record supported, adapted, conditional or unresolved
 status, the implementation and evidence, and intentional prompt-driven differences.
@@ -362,6 +464,20 @@ Rows cover source graph warnings and app-wide design values as well as routes an
 controls. This is an inventory of migration obligations, not proof that their target
 actions work.
 
+Preserve the existing app mark after scaffolding: run `himi icon from-one-app
+--content . --evidence-dir .himi/one-app`. This reads the hash-verified collected
+`settings.logoImageUrl`, downloads that mark and uses the existing icon normalizer
+to produce the opaque launcher master and Play listing icon. Animated marks use
+their fullest composited frame within bounded decoding limits. It does not run
+site analysis or generate new artwork. If the source mark is absent or unavailable,
+keep that migration obligation unresolved; obtain the existing mark and use
+`himi icon set <file>`. An already collected site's logo may be used with
+`himi icon from-site --book <dir>` only when it is the intended source identity.
+Run `himi icon check --content .` and visually compare the result with the source.
+For a marked One App migration, `himi validate --strict` fails when the icon is
+missing, still byte-identical to a bundled template, or its pixel checks cannot run. A passing mechanical check
+cannot establish ownership of arbitrary custom artwork; compare the real mark too.
+
 Map each row to a target screen and, for interactions or top-bar controls, a
 target control. A `design` row is app-wide, so it needs no screen or control: it is
 satisfied by the design check instead. Set its `status` to `supported`, `adapted`, `conditional`, or
@@ -482,6 +598,45 @@ not share mutable filters accidentally. Keep static authored content in the app,
 and products, services, availability, posts and member records live on the same site.
 Refresh data after operations without reconnecting layout to the One App editor.
 
+### Screen-content contract
+
+Use the current [screen design guide](https://apps.wix.com/_api/himi-serve/docs/designing-himi-screens.md) and the app's
+actual tokens and component reference. Do not copy dimensions or a card wrapper
+from an unrelated template. Choose these patterns before building the screens:
+
+| Content case | Compose | Check in the generated app |
+|---|---|---|
+| Page rhythm | Use one consistent content gutter and the app's spacing scale. Separate headings, body copy and sections through type and spacing. Use logical leading/trailing insets. | Short and long localized copy remain readable on a narrow phone and in RTL; a missing optional section leaves no extra gap. |
+| Program, group and other detail sections | Keep the main description and facts in a readable page column. Use a `Section` or ordinary stack for hierarchy; use `Card` only for a related cluster that needs a separate surface. Do not put every paragraph or section inside another bordered box. Retain authored borders when they convey meaning. | The loaded page and its empty/error states have deliberate hierarchy, without repeated decorative borders or nested card padding. Rich descriptions retain their supported formatting. |
+| Horizontal content rails | Give each card an explicit consistent width and reserve its image area using the supported `width`/`height` or `aspectRatio` modifiers. Reserve the same text/action area across neighboring cards; use `Text.maxLines` for bounded previews and keep full content reachable. Match the loading placeholder and missing-image fallback to those slots. Keep horizontal worker-backed lists bounded, as described in the design guide. | A delayed image, failed image and loaded image keep the card and following section in place. Long titles and larger text do not clip controls; adjust the rail's shared size when necessary instead of cutting off content. |
+| More / overflow destinations | Keep every source destination and its routing. Group related destinations under meaningful headings; use consistent icon-and-label rows such as `ListItem`, with one row owning the navigation action. Use a shared group surface when appropriate instead of giving every row its own border. | Every overflow destination is reachable, its icon and label describe its content, and the last group remains reachable. Do not add a second in-page top bar. |
+| Bottom clearance | Keep scrolling content inside the shell's native navigation and safe-area layout. Put a persistent screen action in `stickyFooter`, outside the scrolling body. Add intentional content-end spacing using the app's tokens; do not guess a universal tab-bar height or copy a web-only spacer. | Scroll to the actual last row and activate its control on each affected native device, with tabs and any footer visible. The row and tap target sit above the chrome, including after content or text-size changes. |
+| Empty content | Render an `EmptyState` that explains the current result and offers a real next step only when one exists. Loading, sign-in, permission and failed reads keep their own states. | An empty response is understandable, a failed read is not presented as an empty success, and an unavailable source section is recorded as a gap rather than replaced with sample records or a blank tab. |
+
+These are composition instructions, not a new renderer feature or an automatic
+layout guarantee. Reuse existing live-data workers and supported components;
+retain customer-authored copy and the chosen locale. A missing platform feature
+remains an explicit gap.
+
+Include the relevant cases in `MOBILE-UX.md` before implementation. Verify the
+actual generated screens after implementation, rather than signing off from the
+guide or an unchanged template screenshot:
+
+- Drive More and a representative detail screen, including every overflow
+  destination and the final row below the fold.
+- Capture a rail before images resolve, after they resolve and with a failed
+  image. Use controlled delayed responses in test fixtures; keep fixture data and
+  scenario switches out of the published app.
+- Check loaded, loading, empty and failed-read states at the recorded narrow
+  width, with long copy, larger text and the target layout direction. Check
+  native bottom tabs and a persistent footer where present; web rendering alone
+  cannot establish native clearance or tap behavior.
+- Save the observations and artifacts in `MOBILE-UX.md` and the migration report.
+  Fix layout defects and retest the affected cases before calling the migration
+  complete. Record unavailable checks as unverified.
+
+### Same-site identity
+
 Bind the app to the same site through its **One App visitor identity**. It is the
 identity a visitor of the source Branded app already has, so it needs no OAuth client
 and creates nothing on the customer's site. The `branded-lite` template does not supply `provisioning.json`:

package/guides/skill.md

@@ -27,6 +27,11 @@ and template-preview journey below. Write the reconstruction plan, `SPEC.md`,
 same-site One App visitor binding, checks and hosted draft. Obtain the
 site owner's agreement before creating or updating an OAuth client for optional
 member flows; visitor reads and native email/password sign-in need no client.
+Before composing content, read `himi docs designing-himi-screens` and apply the
+migration guide's screen-content contract: readable detail sections, stable rail
+and image sizing, grouped icon rows for More, native bottom clearance and distinct
+loading/empty/error states. Put the relevant cases in `MOBILE-UX.md` and verify
+the generated screens; reading the guide is not layout evidence.
 Preserve the supplied layout and
 apply the user's separate optional prompt. Use `CI=1 himi init` with
 `--no-first-look`; do not execute its generic `doNow` / `doNowAgain` template-preview

package/guides/splash-screens.md

@@ -364,13 +364,165 @@ Note that the `splash` accessibility id / `testTag` on some apps today belongs t
 
 ### Branded-lite logo and handoff
 
+#### Branded-lite T5 splash (iOS, Android and macOS)
+
+When `splash.enabled` is true, the standalone Branded Lite native hosts can render
+`himi_branded_splash` above the existing native in-app splash. The system launch
+screen stays binary-owned. After seeding and artwork readiness, the hosts mount
+the T5 region first. Home mounts after the T5 presentation animation finishes, so
+its startup work cannot consume the entrance animation's first frames
+(JavaScriptCore on iOS and WebView construction/rendering on Android).
+Dismissal then waits for Home's first content.
+`maxHoldMs` always takes priority, including a missing or unresponsive worker.
+A failed descriptor/bundle keeps the native fallback and releases the T5 wait.
+The splash worker never marks Home ready.
+
+On Android the OS exit provider stays above Compose until the native splash
+has actually drawn. Composition alone is too early and can expose a blank icon gap.
+The pre-draw keep condition is released at composition so this cannot deadlock drawing.
+Before mounting the worker screens, the host awaits removal of the OS exit provider.
+Otherwise WebView startup can block Android's splash transfer past its deadline and
+trigger the default 20dp window-shift animation, even with identical icon bounds.
+The wait ends immediately on removal, skips Activity recreation, and has a one-second
+ceiling for launches with no system splash callback.
+The native surface remains visible while the region loads and if its descriptor
+or bundle fails. Set `splash.logoAsset: "branded_lite_app_icon"`, `logoWidth: 192`
+and `minVisibleMs: 0` for an immediate native icon that matches Android's OS crop.
+Once the worker is ready, the T5 screen paints its own opaque background and content.
+The native artwork cannot leak through when T5 hides its icon. The native hosts
+suppress the region's default spinner. The region tears its worker down on dismissal
+and does not occupy a warm-worker pool slot. The standalone macOS host uses the
+same T5 handoff. The web host keeps its existing startup surface and resolves the
+`branded_lite_app_icon` alias through the current app's web icon URL; it does not
+mount the native T5 handoff.
+
+#### Editing from an agent or Containers
+
+First check the app's screen registry. A T5-capable Branded Lite app contains the exact
+`himi_branded_splash` descriptor and the `himi-branded-lite-splash` worker. For this app,
+edit that descriptor and its referenced design tokens. Do not use the legacy native `splash`
+block as the primary appearance editor: it controls the underlying native fallback.
+Do not assume an older binary can mount a newly added T5 screen. Without the descriptor or
+T5 host support, retain the legacy contract and state the required native upgrade.
+
+In a generated content package, the descriptor lives in `SCREENS` in `dev/index.ts`.
+Its editable contract is:
+
+- `input.showIcon`: `true` shows the app icon; `false` fades it out. Preserve the existing
+  worker bindings, the 192-point native handoff icon, presentation marker and motion wiring.
+- Root node `splash_t5`: `modifiers.background.token` names an opaque colour token.
+- Node `splash_t5_gradient`: `modifiers.backgroundGradient.token` names a gradient in
+  `tokens.json`. Its `colors` are colour-token names; `angle` uses CSS degrees (`180`
+  top-to-bottom, `90` left-to-right, `135` diagonal); optional `locations` place its stops.
+  More than two colours are supported. Unlike the legacy native fallback, the T5 renderers
+  honour the gradient angle. Preserve light/dark token values that were not requested to change.
+
+An orientation-only request changes the gradient angle, preserving the colours and icon.
+An icon-visibility request changes `input.showIcon`, preserving background tokens. Keep
+`splash.enabled: true` for the native host and preserve the native launch/fallback colour
+and icon for ordinary T5 edits. In particular, hiding the T5 icon does not empty native
+`logoAsset`: Android's OS launch icon stays in the binary and the T5 icon fades away at handoff.
+A newly generated home-screen app icon is a different operation and still requires a native build.
+Generated Branded Lite templates also include `splash.json` with an `iconUrl` field. Set it to
+the app's approved public HTTPS image URL; AppSmith supplies the Plan's app icon when scaffolding
+under the splash experiment. Each app owns this source. Publishing a later URL change updates
+the T5 image without rebuilding or changing `config.ts` native splash settings. An empty URL
+keeps the bundled fallback. In source apps, `splashAppearance.iconUrl` reads the same file.
+The hosted icon uses the same `splash_t5_icon` circle and inner `splash_t5_icon_image` as the
+bundled icon: a 192-point frame with the central two-thirds crop. The native hosts prewarm its URL
+before presentation. Containers reads that same crop and size. Image fetch failure keeps the native
+fallback within the boot deadline. Neither this source nor a T5 update changes the launcher
+icon or the very first OS splash. Existing binaries require the T5 splash host to use it.
+
+A custom T5 splash logo can use a public HTTPS Media Manager/generated-image URL without replacing
+that home-screen icon. Source apps use `logoUrl` and `logoSize` (48–240 points) in `splashAppearance`.
+The builder keeps the initial 192-point app icon as `splash_t5_handoff_icon`, then cross-fades to the
+requested `splash_t5_icon` at the same centre. `input.customLogo: true` enables that worker path:
+`customLogoHidden` starts true and changes to the inverse of `showIcon` on `present`, while
+`iconHidden` hides the handoff icon. Keep the custom logo node while hidden so it can be restored.
+In raw descriptors, update the custom Image and wrapper dimensions together, and preserve the
+existing worker/motion wiring. Old splash workers need the matching content update.
+
+`backgroundImageUrl` adds a full-canvas layer above the gradient. Use a VStack containing a
+Spacer, with `fillMaxWidth: true` and `backgroundImagePath: "$service:splash.backgroundImageUrl"`.
+The worker exposes `input.backgroundImageUrl` as that state field. This existing bound-background
+renderer fills the canvas on iOS and Android. Do not size an Image with `onMeasure`, `$measure:`
+or `widthPath`/`heightPath`: those size bindings are decode-only on native. Image > gradient >
+colour remains the precedence. URLs must be public HTTPS without embedded credentials. The host
+keeps native launch artwork visible until remote splash images are cached; failed artwork leaves
+the native fallback within the original boot deadline. Neither URL changes the OS splash.
+
+For a solid T5 background, use the root colour token and omit the gradient layer. When adding
+one back, retain the existing fade transition and presentation marker's motion contract.
+Build and validate the content package, inspect the built splash descriptor and referenced
+gradient, then render `himi_branded_splash` in the requested colour scheme. Ship the change
+through the normal authorized draft release so Containers reads the descriptor and tokens
+from that same release. A chat acknowledgement alone is not evidence of an applied edit.
+
+In source apps, edit `splashAppearance` in the splash descriptor builder:
+
+```ts
+export const splashAppearance: SplashAppearance = {
+  showIcon: false,                  // true shows the app icon; false fades it out
+  backgroundColor: "accentPrimary", // opaque fallback underneath the gradient
+  backgroundGradient: "brand",      // key in tokens.json's gradients registry
+  // Optional: logoSize: 120, logoUrl: "https://static.wixstatic.com/media/logo.png",
+  // Optional: backgroundImageUrl: "https://static.wixstatic.com/media/background.jpg",
+};
+```
+
+Remove `backgroundGradient` for a solid background. To change gradient colors, edit
+the selected gradient's `colors` array in `tokens.json` (color token names), or add
+a dedicated gradient there and select its name above. Use a dark gradient with
+`textOnAccent` so the copy stays readable. The default is the `brand` gradient with
+the icon visible. The visible icon keeps the native fallback's 192-point circle,
+center and central-two-thirds crop. The copy stays in place when the icon hides.
+
+The gradient fades in over the opaque solid color using the existing `appearSoft`
+motion token (500 ms by default). Hiding the icon uses the same token for an
+exit fade. The copy stays still. A small presentation marker appears after the
+worker commits visibility and tells the host which motion to wait for. Once T5
+is presented, the host cross-fades the entire native surface directly into the T5
+appearance using the T5 motion duration (400 ms when none is specified). There is no
+intermediate solid-color stage or icon disappearance. Both icons keep the same
+192-point centre and crop; matching artwork stays steady, and changed artwork
+cross-fades in place. Home starts after the background handoff so its worker boot
+and first paint cannot cut across the animation. It then dismisses the splash
+when its content is ready. The initial color
+comes from the installed build's resources; the target appearance and motion
+come from T5. This handoff requires one host build; subsequent T5 edits use OTA
+content. The native cover cannot reappear during the final fade to Home.
+Native Reduced Motion skips these fades and the
+presentation wait. A solid-color splash has no gradient layer. These animations
+can delay an otherwise-ready Home, but never extend the hard startup deadline.
+
+These settings affect only the T5 layer. A new color or hidden icon becomes visible
+at the single native-to-T5 handoff. They do not change Android's OS launch screen or
+the native fallback; those keep their existing settings. The fallback can still be
+configured separately through the existing `splash` app-config. Changing the OS
+launch screen requires a native build.
+
+The descriptor and its `himi-branded-lite-splash` worker
+use existing components, tokens and `splash.title` / `splash.caption` copy keys. The
+worker makes no network or native capability calls. The exact-screen seed includes
+it for release/offline builds. Host integration requires one initial native build;
+later appearance, token and worker changes use the ordinary app release/OTA path.
+
+For local previews, enable `splash` through the local preview service's ephemeral
+`PUT /v1/admin/app-config`. Preview alternate descriptors with
+`PUT /v1/admin/screens/himi_branded_splash` and token changes with
+`PUT /v1/admin/tokens`; these overrides are not saved. A temporary
+`minVisibleMs: 2000` makes capture easier but adds a one-second native logo fade.
+Run the phone `splash/startup.yaml` flows to check the handoff to navigation.
+
 Use the baked branded-lite app icon as the in-app logo:
 
 ```ts
 splash: { enabled: true, logoAsset: "branded_lite_app_icon", logoWidth: 192 }
 ```
 
-Hide the logo on both Android splash layers with an **explicit empty string**:
+Hide the logo on Android's OS and native fallback layers with an **explicit empty
+string** (the T5 icon is controlled separately by `showIcon` above):
 
 ```ts
 splash: { enabled: true, logoAsset: "" }
@@ -408,10 +560,9 @@ within the same deadline. Once dismissed, the iOS splash stays dismissed even if
 OTA timing settings change. Branded-lite Android image splashes use translucent dark system-bar
 scrims with light icons for legibility; color and gradient splashes remain full-bleed.
 Web retains its current transitions and readiness.
-The standalone branded-lite macOS shell currently does not mount a boot splash
-overlay; `splash.enabled` does not enable one there. The shared SwiftUI background
-renderer is available on macOS, but this host handoff integration covers Android
-and iOS. macOS shell integration requires a separate change.
+The standalone branded-lite macOS shell mounts the same T5 splash with its native fallback,
+artwork readiness and bounded exit. AppKit has no OS launch splash. The shared artwork gate is
+used by the iOS and Mac shells; the Android host warms the same URLs through its renderer cache.
 
 Branded-lite builds expose the launcher artwork as the regular iOS image asset
 `branded_lite_app_icon`, so the same logo configuration works on Android and iOS.

package/guides/tier-5-add-a-screen.md

@@ -35,6 +35,26 @@ the runtime staged inside it, so neither is a build error. The snippets below us
 `himi init` scaffolds `@wix/himalaya/*`, which is also the form your editor and `tsc` resolve
 off-repo. Full mapping: `himi docs wix-api-usage`.
 
+### Look up descriptor names before authoring
+
+Use `himi docs component-reference` as the reference for your installed CLI's component
+props, modifiers and allowed enum values. `himi components Text` or `himi components EmptyState`
+narrows the prop lookup to one component. Props belong in `body.props`; the reference's
+**Modifiers** section describes the separate `modifiers` bag beside `body`.
+
+Typography names come from your app's `tokens.json` → `typography`, rather than a universal
+component enum. Use the names declared there; [Design tokens](../tools/himi-cli/guides/tokens.md) explains their shape.
+For example, a template may declare `pageTitle` and `bodyEmphasis` without declaring `largeTitle`
+or `headline`.
+
+Run `himi validate --strict` after editing. Name diagnostics suggest close spellings within
+the correct component or modifier vocabulary: `Text.lineLimit` points to `maxLines`, and
+`EmptyState.message` points to `subtitle`. They report the rejected key at root and nested
+nodes. These are hints; validation does not rewrite your descriptor or accept aliases.
+Unsupported layout options need an authored decision: `maxHeight` has no maximum-height
+modifier equivalent, and `clipped` is not a boolean modifier. A fixed `height` or a particular
+`clipShape` can change the layout or clipping behavior, so consult the reference before using it.
+
 Author the worker in `tier5-src/<name>/index.ts` and bind it from a screen in `dev/index.ts`,
 exactly as the walkthrough below shows.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1568.0",
+  "version": "0.1570.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": "c098ae02840c1a3393199b2b6a265dd3f41ddafe769490763d9f7f7e"
+  "falconPackageHash": "6d016296db51d313f3d18d71aa7f7937e8a5119832948c7722bd3bda"
 }

package/templates/beauty-salon/config.ts

@@ -52,6 +52,16 @@ export default defineApp({
     ]
   },
   designTokensPath: "./tokens.json",
+  // Native fallback; the T5 splash descriptor owns the editable launch appearance.
+  splash: {
+    "enabled": true,
+    "backgroundColor": "accentPrimary",
+    "logoAsset": "branded_lite_app_icon",
+    "logoWidth": 192,
+    "layout": "logoOnly",
+    "minVisibleMs": 0,
+    "maxHoldMs": 5000
+  },
   navigation: {
     "navKind": "responsive",
     "scheme": "himalaya-__HIMI_APP_SLUG__",
@@ -71,6 +81,13 @@ export default defineApp({
         "parentScreenId": "himi_account",
         "tabId": "profile"
       },
+      {
+        "screenId": "himi_business_contact",
+        "isPublic": true,
+        "paramKeys": [],
+        "parentScreenId": "himi_account",
+        "tabId": "profile"
+      },
       {
         "screenId": "himi_appearance",
         "isPublic": true,