@wix/himalaya-cli 0.1568.0 → 0.1569.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (145) hide show
  1. package/dist/cli.mjs +20988 -20825
  2. package/dist/preview-assets.generated.bin +0 -0
  3. package/guides/app-config.md +10 -0
  4. package/guides/app-icon.md +20 -1
  5. package/guides/himi-json-output.md +7 -0
  6. package/guides/one-app-to-himi-app.md +14 -0
  7. package/guides/splash-screens.md +156 -5
  8. package/package.json +2 -2
  9. package/templates/beauty-salon/config.ts +10 -0
  10. package/templates/beauty-salon/dev/index.ts +265 -0
  11. package/templates/beauty-salon/himalaya.content.json +3 -0
  12. package/templates/beauty-salon/splash.json +3 -0
  13. package/templates/beauty-salon/tier5-src/_shared/himi-copy.ts +17 -6
  14. package/templates/beauty-salon/tier5-src/_shared/rich-body.ts +44 -0
  15. package/templates/beauty-salon/tier5-src/himi-booking-service/index.ts +13 -9
  16. package/templates/beauty-salon/tier5-src/himi-branded-lite-splash/index.ts +35 -0
  17. package/templates/beauty-salon-owner/config.ts +8 -0
  18. package/templates/beauty-salon-owner/dev/index.ts +1 -0
  19. package/templates/beauty-salon-owner/tier5-src/_shared/himi-copy.ts +17 -6
  20. package/templates/beauty-salon-owner/tier5-src/_shared/rich-body.ts +44 -0
  21. package/templates/branded-lite/config.ts +10 -0
  22. package/templates/branded-lite/dev/index.ts +295 -1
  23. package/templates/branded-lite/himalaya.content.json +3 -0
  24. package/templates/branded-lite/splash.json +3 -0
  25. package/templates/branded-lite/tier5-src/_shared/himi-copy.ts +17 -6
  26. package/templates/branded-lite/tier5-src/_shared/rich-body.ts +44 -0
  27. package/templates/branded-lite/tier5-src/himi-booking-service/index.ts +13 -9
  28. package/templates/branded-lite/tier5-src/himi-branded-lite-group/index.ts +20 -3
  29. package/templates/branded-lite/tier5-src/himi-branded-lite-groups/index.ts +18 -2
  30. package/templates/branded-lite/tier5-src/himi-branded-lite-splash/index.ts +35 -0
  31. package/templates/brandy/tier5-src/_shared/himi-copy.ts +17 -6
  32. package/templates/community-club/config.ts +10 -0
  33. package/templates/community-club/dev/index.ts +267 -1
  34. package/templates/community-club/himalaya.content.json +3 -0
  35. package/templates/community-club/splash.json +3 -0
  36. package/templates/community-club/tier5-src/_shared/himi-copy.ts +17 -6
  37. package/templates/community-club/tier5-src/_shared/rich-body.ts +44 -0
  38. package/templates/community-club/tier5-src/himi-branded-lite-group/index.ts +20 -3
  39. package/templates/community-club/tier5-src/himi-branded-lite-groups/index.ts +18 -2
  40. package/templates/community-club/tier5-src/himi-branded-lite-splash/index.ts +35 -0
  41. package/templates/community-club-owner/config.ts +8 -0
  42. package/templates/community-club-owner/dev/index.ts +1 -0
  43. package/templates/community-club-owner/tier5-src/_shared/himi-copy.ts +17 -6
  44. package/templates/community-club-owner/tier5-src/_shared/rich-body.ts +44 -0
  45. package/templates/events-meetups/config.ts +10 -0
  46. package/templates/events-meetups/dev/index.ts +267 -1
  47. package/templates/events-meetups/himalaya.content.json +3 -0
  48. package/templates/events-meetups/splash.json +3 -0
  49. package/templates/events-meetups/tier5-src/_shared/himi-copy.ts +17 -6
  50. package/templates/events-meetups/tier5-src/_shared/rich-body.ts +44 -0
  51. package/templates/events-meetups/tier5-src/himi-branded-lite-group/index.ts +20 -3
  52. package/templates/events-meetups/tier5-src/himi-branded-lite-groups/index.ts +18 -2
  53. package/templates/events-meetups/tier5-src/himi-branded-lite-splash/index.ts +35 -0
  54. package/templates/events-meetups-owner/config.ts +8 -0
  55. package/templates/events-meetups-owner/dev/index.ts +1 -0
  56. package/templates/events-meetups-owner/tier5-src/_shared/himi-copy.ts +17 -6
  57. package/templates/events-meetups-owner/tier5-src/_shared/rich-body.ts +44 -0
  58. package/templates/gym-fitness/config.ts +10 -0
  59. package/templates/gym-fitness/dev/index.ts +265 -0
  60. package/templates/gym-fitness/himalaya.content.json +3 -0
  61. package/templates/gym-fitness/splash.json +3 -0
  62. package/templates/gym-fitness/tier5-src/_shared/himi-copy.ts +17 -6
  63. package/templates/gym-fitness/tier5-src/_shared/rich-body.ts +44 -0
  64. package/templates/gym-fitness/tier5-src/himi-booking-service/index.ts +13 -9
  65. package/templates/gym-fitness/tier5-src/himi-branded-lite-splash/index.ts +35 -0
  66. package/templates/gym-fitness-owner/config.ts +8 -0
  67. package/templates/gym-fitness-owner/dev/index.ts +1 -0
  68. package/templates/gym-fitness-owner/tier5-src/_shared/himi-copy.ts +17 -6
  69. package/templates/gym-fitness-owner/tier5-src/_shared/rich-body.ts +44 -0
  70. package/templates/himi-chat/dev/index.ts +1 -0
  71. package/templates/himi-chat/tier5-src/_shared/himi-copy.ts +17 -6
  72. package/templates/nonprofit-cause/config.ts +10 -0
  73. package/templates/nonprofit-cause/dev/index.ts +267 -1
  74. package/templates/nonprofit-cause/himalaya.content.json +3 -0
  75. package/templates/nonprofit-cause/splash.json +3 -0
  76. package/templates/nonprofit-cause/tier5-src/_shared/himi-copy.ts +17 -6
  77. package/templates/nonprofit-cause/tier5-src/_shared/rich-body.ts +44 -0
  78. package/templates/nonprofit-cause/tier5-src/himi-branded-lite-group/index.ts +20 -3
  79. package/templates/nonprofit-cause/tier5-src/himi-branded-lite-groups/index.ts +18 -2
  80. package/templates/nonprofit-cause/tier5-src/himi-branded-lite-splash/index.ts +35 -0
  81. package/templates/nonprofit-cause-owner/config.ts +8 -0
  82. package/templates/nonprofit-cause-owner/dev/index.ts +1 -0
  83. package/templates/nonprofit-cause-owner/tier5-src/_shared/himi-copy.ts +17 -6
  84. package/templates/nonprofit-cause-owner/tier5-src/_shared/rich-body.ts +44 -0
  85. package/templates/owner-lite/config.ts +8 -0
  86. package/templates/owner-lite/dev/index.ts +1 -0
  87. package/templates/owner-lite/tier5-src/_shared/himi-copy.ts +17 -6
  88. package/templates/owner-lite/tier5-src/_shared/rich-body.ts +44 -0
  89. package/templates/podcast-creator/config.ts +10 -0
  90. package/templates/podcast-creator/dev/index.ts +237 -0
  91. package/templates/podcast-creator/himalaya.content.json +3 -0
  92. package/templates/podcast-creator/splash.json +3 -0
  93. package/templates/podcast-creator/tier5-src/_shared/himi-copy.ts +17 -6
  94. package/templates/podcast-creator/tier5-src/_shared/rich-body.ts +44 -0
  95. package/templates/podcast-creator/tier5-src/himi-branded-lite-splash/index.ts +35 -0
  96. package/templates/podcast-creator-owner/config.ts +8 -0
  97. package/templates/podcast-creator-owner/dev/index.ts +1 -0
  98. package/templates/podcast-creator-owner/tier5-src/_shared/himi-copy.ts +17 -6
  99. package/templates/podcast-creator-owner/tier5-src/_shared/rich-body.ts +44 -0
  100. package/templates/portfolio-creative/config.ts +10 -0
  101. package/templates/portfolio-creative/dev/index.ts +237 -0
  102. package/templates/portfolio-creative/himalaya.content.json +3 -0
  103. package/templates/portfolio-creative/splash.json +3 -0
  104. package/templates/portfolio-creative/tier5-src/_shared/himi-copy.ts +17 -6
  105. package/templates/portfolio-creative/tier5-src/_shared/rich-body.ts +44 -0
  106. package/templates/portfolio-creative/tier5-src/himi-branded-lite-splash/index.ts +35 -0
  107. package/templates/portfolio-creative-owner/config.ts +8 -0
  108. package/templates/portfolio-creative-owner/dev/index.ts +1 -0
  109. package/templates/portfolio-creative-owner/tier5-src/_shared/himi-copy.ts +17 -6
  110. package/templates/portfolio-creative-owner/tier5-src/_shared/rich-body.ts +44 -0
  111. package/templates/restaurant/config.ts +10 -0
  112. package/templates/restaurant/dev/index.ts +237 -0
  113. package/templates/restaurant/himalaya.content.json +3 -0
  114. package/templates/restaurant/splash.json +3 -0
  115. package/templates/restaurant/tier5-src/_shared/himi-copy.ts +17 -6
  116. package/templates/restaurant/tier5-src/_shared/rich-body.ts +44 -0
  117. package/templates/restaurant/tier5-src/himi-branded-lite-splash/index.ts +35 -0
  118. package/templates/restaurant-owner/config.ts +8 -0
  119. package/templates/restaurant-owner/dev/index.ts +1 -0
  120. package/templates/restaurant-owner/tier5-src/_shared/himi-copy.ts +17 -6
  121. package/templates/restaurant-owner/tier5-src/_shared/rich-body.ts +44 -0
  122. package/templates/retail-store/config.ts +10 -0
  123. package/templates/retail-store/dev/index.ts +237 -0
  124. package/templates/retail-store/himalaya.content.json +3 -0
  125. package/templates/retail-store/splash.json +3 -0
  126. package/templates/retail-store/tier5-src/_shared/himi-copy.ts +17 -6
  127. package/templates/retail-store/tier5-src/_shared/rich-body.ts +44 -0
  128. package/templates/retail-store/tier5-src/himi-branded-lite-splash/index.ts +35 -0
  129. package/templates/retail-store-owner/config.ts +8 -0
  130. package/templates/retail-store-owner/dev/index.ts +1 -0
  131. package/templates/retail-store-owner/tier5-src/_shared/himi-copy.ts +17 -6
  132. package/templates/retail-store-owner/tier5-src/_shared/rich-body.ts +44 -0
  133. package/templates/surface-showcase/dev/index.ts +1 -0
  134. package/templates/yoga-studio/config.ts +10 -0
  135. package/templates/yoga-studio/dev/index.ts +265 -0
  136. package/templates/yoga-studio/himalaya.content.json +3 -0
  137. package/templates/yoga-studio/splash.json +3 -0
  138. package/templates/yoga-studio/tier5-src/_shared/himi-copy.ts +17 -6
  139. package/templates/yoga-studio/tier5-src/_shared/rich-body.ts +44 -0
  140. package/templates/yoga-studio/tier5-src/himi-booking-service/index.ts +13 -9
  141. package/templates/yoga-studio/tier5-src/himi-branded-lite-splash/index.ts +35 -0
  142. package/templates/yoga-studio-owner/config.ts +8 -0
  143. package/templates/yoga-studio-owner/dev/index.ts +1 -0
  144. package/templates/yoga-studio-owner/tier5-src/_shared/himi-copy.ts +17 -6
  145. package/templates/yoga-studio-owner/tier5-src/_shared/rich-body.ts +44 -0
Binary file
@@ -79,6 +79,16 @@ your envelope + per-surface links), and `himi render <screen> --device mac|watch
79
79
 
80
80
  ## Splash (the launch moment)
81
81
 
82
+ **T5 Branded Lite apps:** when the existing exact screen registry contains
83
+ `himi_branded_splash`, its descriptor/worker owns the editable in-app appearance.
84
+ Read `himi docs splash-screens` before editing: change its `input.showIcon`, the
85
+ root background token and the gradient token's colours/stops/angle. CSS angles such
86
+ as 90 (horizontal) and 135 (diagonal) are supported by that T5 layer. Preserve the
87
+ native fallback and binary OS launch settings. Generated packages keep the descriptor
88
+ in `dev/index.ts` and the worker in `tier5-src/`. Do not assume an older native
89
+ host can mount a newly added screen. The following contract describes the native
90
+ fallback and legacy apps; it is not the T5 appearance editor.
91
+
82
92
  `splash` is ONE declaration with TWO consumers, and only the second is OTA:
83
93
 
84
94
  - **Build time** — `splash.backgroundColor` (a color TOKEN name, never a hex) generates the
@@ -26,6 +26,7 @@ it. Offer the customer the choice — it is their brand:
26
26
  ```sh
27
27
  himi icon status # what would ship right now, and whether a store would take it
28
28
  himi icon from-site --book .himi/business-book # the logo `himi site analyze` downloaded
29
+ himi icon from-one-app --evidence-dir .himi/one-app # the verified collected app's existing logo
29
30
  himi icon set ./their-logo.png # a file the customer supplied
30
31
  himi icon generate # a gradient tile + glyph, for a customer with no mark
31
32
  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
44
45
  (`himi icon glyphs` lists them, `book` and `graduation` among them), and read the neutral
45
46
  tile as what it is — a placeholder, still waiting for the customer's real mark.
46
47
 
47
- `set`, `from-site` and `generate` all do the same finishing work: **trim** the art, centre
48
+ `set`, `from-site`, `from-one-app` and `generate` all do the same finishing work: **trim** the art, centre
48
49
  it, **flatten it onto your app's accent colour**, write it as an exactly-1024 square with no
49
50
  alpha channel, derive the 512 Play listing icon, and record it in `himalaya.content.json`.
50
51
 
52
+ Source images accept at most 16 MiB of encoded input and a 2048-square decoded canvas.
53
+ SVGs use density-bounded rasterization before normalization, under the same pixel cap.
54
+ Animated GIF/WebP marks use a composited poster with the most distinguishable artwork,
55
+ measured against one background reference for the animation. Review the resulting mark
56
+ against the source. Poster decoding accepts at most 256 frames, a 4-million-pixel canvas,
57
+ 64 million total frame pixels and 16 MiB of encoded input; larger animations are refused
58
+ with advice to supply the existing static mark. Other multi-page formats retain their
59
+ first-page behavior. `from-one-app` requires the image toolchain before downloading or
60
+ replacing an icon, so it cannot report success without normalization and the Play rendition.
61
+ It checks both renditions in a scratch package before installing them; a rejected source
62
+ leaves the current master, Play icon and manifest unchanged.
63
+
51
64
  **The declaration is the part people miss.** An off-repo package's icon is whatever
52
65
  `himalaya.content.json` names:
53
66
 
@@ -62,6 +75,12 @@ declare is art nothing ships: the release bakes no icon, and a binary then falls
62
75
  `himi icon` writes both halves, and `himi validate` / `push` / `dist` refuse a package whose
63
76
  declared icon is missing.
64
77
 
78
+ Customer native builds copy the contract's prepared master into the iOS and Android
79
+ launcher resources. The shared Mac materializer resizes that same master into all ten
80
+ `AppIcon.appiconset` renditions and writes their catalog metadata; it preserves the source
81
+ artwork. A platform-only preparation writes only that platform's native tree. Existing
82
+ binaries need rebuilding to pick up a changed launcher icon.
83
+
65
84
  ## What each store wants
66
85
 
67
86
  The two specs **conflict**, so these are two derived files and neither can serve both:
@@ -32,6 +32,13 @@ keeps its existing fields and adds the code:
32
32
  }
33
33
  ```
34
34
 
35
+ ## `himi icon from-one-app` codes
36
+
37
+ | Code | Meaning |
38
+ | --- | --- |
39
+ | `source_icon_unavailable` | Verified source evidence or its logo is missing, unreadable, unavailable, over the download/decoding budget, or cannot be normalized. |
40
+ | `source_icon_unusable` | The prepared source mark fails mechanical launcher/store checks. Existing icon files and metadata are left unchanged. |
41
+
35
42
  ## Push codes
36
43
 
37
44
  | Code | Meaning |
@@ -362,6 +362,20 @@ Rows cover source graph warnings and app-wide design values as well as routes an
362
362
  controls. This is an inventory of migration obligations, not proof that their target
363
363
  actions work.
364
364
 
365
+ Preserve the existing app mark after scaffolding: run `himi icon from-one-app
366
+ --content . --evidence-dir .himi/one-app`. This reads the hash-verified collected
367
+ `settings.logoImageUrl`, downloads that mark and uses the existing icon normalizer
368
+ to produce the opaque launcher master and Play listing icon. Animated marks use
369
+ their fullest composited frame within bounded decoding limits. It does not run
370
+ site analysis or generate new artwork. If the source mark is absent or unavailable,
371
+ keep that migration obligation unresolved; obtain the existing mark and use
372
+ `himi icon set <file>`. An already collected site's logo may be used with
373
+ `himi icon from-site --book <dir>` only when it is the intended source identity.
374
+ Run `himi icon check --content .` and visually compare the result with the source.
375
+ For a marked One App migration, `himi validate --strict` fails when the icon is
376
+ missing, still byte-identical to a bundled template, or its pixel checks cannot run. A passing mechanical check
377
+ cannot establish ownership of arbitrary custom artwork; compare the real mark too.
378
+
365
379
  Map each row to a target screen and, for interactions or top-bar controls, a
366
380
  target control. A `design` row is app-wide, so it needs no screen or control: it is
367
381
  satisfied by the design check instead. Set its `status` to `supported`, `adapted`, `conditional`, or
@@ -364,13 +364,165 @@ Note that the `splash` accessibility id / `testTag` on some apps today belongs t
364
364
 
365
365
  ### Branded-lite logo and handoff
366
366
 
367
+ #### Branded-lite T5 splash (iOS, Android and macOS)
368
+
369
+ When `splash.enabled` is true, the standalone Branded Lite native hosts can render
370
+ `himi_branded_splash` above the existing native in-app splash. The system launch
371
+ screen stays binary-owned. After seeding and artwork readiness, the hosts mount
372
+ the T5 region first. Home mounts after the T5 presentation animation finishes, so
373
+ its startup work cannot consume the entrance animation's first frames
374
+ (JavaScriptCore on iOS and WebView construction/rendering on Android).
375
+ Dismissal then waits for Home's first content.
376
+ `maxHoldMs` always takes priority, including a missing or unresponsive worker.
377
+ A failed descriptor/bundle keeps the native fallback and releases the T5 wait.
378
+ The splash worker never marks Home ready.
379
+
380
+ On Android the OS exit provider stays above Compose until the native splash
381
+ has actually drawn. Composition alone is too early and can expose a blank icon gap.
382
+ The pre-draw keep condition is released at composition so this cannot deadlock drawing.
383
+ Before mounting the worker screens, the host awaits removal of the OS exit provider.
384
+ Otherwise WebView startup can block Android's splash transfer past its deadline and
385
+ trigger the default 20dp window-shift animation, even with identical icon bounds.
386
+ The wait ends immediately on removal, skips Activity recreation, and has a one-second
387
+ ceiling for launches with no system splash callback.
388
+ The native surface remains visible while the region loads and if its descriptor
389
+ or bundle fails. Set `splash.logoAsset: "branded_lite_app_icon"`, `logoWidth: 192`
390
+ and `minVisibleMs: 0` for an immediate native icon that matches Android's OS crop.
391
+ Once the worker is ready, the T5 screen paints its own opaque background and content.
392
+ The native artwork cannot leak through when T5 hides its icon. The native hosts
393
+ suppress the region's default spinner. The region tears its worker down on dismissal
394
+ and does not occupy a warm-worker pool slot. The standalone macOS host uses the
395
+ same T5 handoff. The web host keeps its existing startup surface and resolves the
396
+ `branded_lite_app_icon` alias through the current app's web icon URL; it does not
397
+ mount the native T5 handoff.
398
+
399
+ #### Editing from an agent or Containers
400
+
401
+ First check the app's screen registry. A T5-capable Branded Lite app contains the exact
402
+ `himi_branded_splash` descriptor and the `himi-branded-lite-splash` worker. For this app,
403
+ edit that descriptor and its referenced design tokens. Do not use the legacy native `splash`
404
+ block as the primary appearance editor: it controls the underlying native fallback.
405
+ Do not assume an older binary can mount a newly added T5 screen. Without the descriptor or
406
+ T5 host support, retain the legacy contract and state the required native upgrade.
407
+
408
+ In a generated content package, the descriptor lives in `SCREENS` in `dev/index.ts`.
409
+ Its editable contract is:
410
+
411
+ - `input.showIcon`: `true` shows the app icon; `false` fades it out. Preserve the existing
412
+ worker bindings, the 192-point native handoff icon, presentation marker and motion wiring.
413
+ - Root node `splash_t5`: `modifiers.background.token` names an opaque colour token.
414
+ - Node `splash_t5_gradient`: `modifiers.backgroundGradient.token` names a gradient in
415
+ `tokens.json`. Its `colors` are colour-token names; `angle` uses CSS degrees (`180`
416
+ top-to-bottom, `90` left-to-right, `135` diagonal); optional `locations` place its stops.
417
+ More than two colours are supported. Unlike the legacy native fallback, the T5 renderers
418
+ honour the gradient angle. Preserve light/dark token values that were not requested to change.
419
+
420
+ An orientation-only request changes the gradient angle, preserving the colours and icon.
421
+ An icon-visibility request changes `input.showIcon`, preserving background tokens. Keep
422
+ `splash.enabled: true` for the native host and preserve the native launch/fallback colour
423
+ and icon for ordinary T5 edits. In particular, hiding the T5 icon does not empty native
424
+ `logoAsset`: Android's OS launch icon stays in the binary and the T5 icon fades away at handoff.
425
+ A newly generated home-screen app icon is a different operation and still requires a native build.
426
+ Generated Branded Lite templates also include `splash.json` with an `iconUrl` field. Set it to
427
+ the app's approved public HTTPS image URL; AppSmith supplies the Plan's app icon when scaffolding
428
+ under the splash experiment. Each app owns this source. Publishing a later URL change updates
429
+ the T5 image without rebuilding or changing `config.ts` native splash settings. An empty URL
430
+ keeps the bundled fallback. In source apps, `splashAppearance.iconUrl` reads the same file.
431
+ The hosted icon uses the same `splash_t5_icon` circle and inner `splash_t5_icon_image` as the
432
+ bundled icon: a 192-point frame with the central two-thirds crop. The native hosts prewarm its URL
433
+ before presentation. Containers reads that same crop and size. Image fetch failure keeps the native
434
+ fallback within the boot deadline. Neither this source nor a T5 update changes the launcher
435
+ icon or the very first OS splash. Existing binaries require the T5 splash host to use it.
436
+
437
+ A custom T5 splash logo can use a public HTTPS Media Manager/generated-image URL without replacing
438
+ that home-screen icon. Source apps use `logoUrl` and `logoSize` (48–240 points) in `splashAppearance`.
439
+ The builder keeps the initial 192-point app icon as `splash_t5_handoff_icon`, then cross-fades to the
440
+ requested `splash_t5_icon` at the same centre. `input.customLogo: true` enables that worker path:
441
+ `customLogoHidden` starts true and changes to the inverse of `showIcon` on `present`, while
442
+ `iconHidden` hides the handoff icon. Keep the custom logo node while hidden so it can be restored.
443
+ In raw descriptors, update the custom Image and wrapper dimensions together, and preserve the
444
+ existing worker/motion wiring. Old splash workers need the matching content update.
445
+
446
+ `backgroundImageUrl` adds a full-canvas layer above the gradient. Use a VStack containing a
447
+ Spacer, with `fillMaxWidth: true` and `backgroundImagePath: "$service:splash.backgroundImageUrl"`.
448
+ The worker exposes `input.backgroundImageUrl` as that state field. This existing bound-background
449
+ renderer fills the canvas on iOS and Android. Do not size an Image with `onMeasure`, `$measure:`
450
+ or `widthPath`/`heightPath`: those size bindings are decode-only on native. Image > gradient >
451
+ colour remains the precedence. URLs must be public HTTPS without embedded credentials. The host
452
+ keeps native launch artwork visible until remote splash images are cached; failed artwork leaves
453
+ the native fallback within the original boot deadline. Neither URL changes the OS splash.
454
+
455
+ For a solid T5 background, use the root colour token and omit the gradient layer. When adding
456
+ one back, retain the existing fade transition and presentation marker's motion contract.
457
+ Build and validate the content package, inspect the built splash descriptor and referenced
458
+ gradient, then render `himi_branded_splash` in the requested colour scheme. Ship the change
459
+ through the normal authorized draft release so Containers reads the descriptor and tokens
460
+ from that same release. A chat acknowledgement alone is not evidence of an applied edit.
461
+
462
+ In source apps, edit `splashAppearance` in the splash descriptor builder:
463
+
464
+ ```ts
465
+ export const splashAppearance: SplashAppearance = {
466
+ showIcon: false, // true shows the app icon; false fades it out
467
+ backgroundColor: "accentPrimary", // opaque fallback underneath the gradient
468
+ backgroundGradient: "brand", // key in tokens.json's gradients registry
469
+ // Optional: logoSize: 120, logoUrl: "https://static.wixstatic.com/media/logo.png",
470
+ // Optional: backgroundImageUrl: "https://static.wixstatic.com/media/background.jpg",
471
+ };
472
+ ```
473
+
474
+ Remove `backgroundGradient` for a solid background. To change gradient colors, edit
475
+ the selected gradient's `colors` array in `tokens.json` (color token names), or add
476
+ a dedicated gradient there and select its name above. Use a dark gradient with
477
+ `textOnAccent` so the copy stays readable. The default is the `brand` gradient with
478
+ the icon visible. The visible icon keeps the native fallback's 192-point circle,
479
+ center and central-two-thirds crop. The copy stays in place when the icon hides.
480
+
481
+ The gradient fades in over the opaque solid color using the existing `appearSoft`
482
+ motion token (500 ms by default). Hiding the icon uses the same token for an
483
+ exit fade. The copy stays still. A small presentation marker appears after the
484
+ worker commits visibility and tells the host which motion to wait for. Once T5
485
+ is presented, the host cross-fades the entire native surface directly into the T5
486
+ appearance using the T5 motion duration (400 ms when none is specified). There is no
487
+ intermediate solid-color stage or icon disappearance. Both icons keep the same
488
+ 192-point centre and crop; matching artwork stays steady, and changed artwork
489
+ cross-fades in place. Home starts after the background handoff so its worker boot
490
+ and first paint cannot cut across the animation. It then dismisses the splash
491
+ when its content is ready. The initial color
492
+ comes from the installed build's resources; the target appearance and motion
493
+ come from T5. This handoff requires one host build; subsequent T5 edits use OTA
494
+ content. The native cover cannot reappear during the final fade to Home.
495
+ Native Reduced Motion skips these fades and the
496
+ presentation wait. A solid-color splash has no gradient layer. These animations
497
+ can delay an otherwise-ready Home, but never extend the hard startup deadline.
498
+
499
+ These settings affect only the T5 layer. A new color or hidden icon becomes visible
500
+ at the single native-to-T5 handoff. They do not change Android's OS launch screen or
501
+ the native fallback; those keep their existing settings. The fallback can still be
502
+ configured separately through the existing `splash` app-config. Changing the OS
503
+ launch screen requires a native build.
504
+
505
+ The descriptor and its `himi-branded-lite-splash` worker
506
+ use existing components, tokens and `splash.title` / `splash.caption` copy keys. The
507
+ worker makes no network or native capability calls. The exact-screen seed includes
508
+ it for release/offline builds. Host integration requires one initial native build;
509
+ later appearance, token and worker changes use the ordinary app release/OTA path.
510
+
511
+ For local previews, enable `splash` through the local preview service's ephemeral
512
+ `PUT /v1/admin/app-config`. Preview alternate descriptors with
513
+ `PUT /v1/admin/screens/himi_branded_splash` and token changes with
514
+ `PUT /v1/admin/tokens`; these overrides are not saved. A temporary
515
+ `minVisibleMs: 2000` makes capture easier but adds a one-second native logo fade.
516
+ Run the phone `splash/startup.yaml` flows to check the handoff to navigation.
517
+
367
518
  Use the baked branded-lite app icon as the in-app logo:
368
519
 
369
520
  ```ts
370
521
  splash: { enabled: true, logoAsset: "branded_lite_app_icon", logoWidth: 192 }
371
522
  ```
372
523
 
373
- Hide the logo on both Android splash layers with an **explicit empty string**:
524
+ Hide the logo on Android's OS and native fallback layers with an **explicit empty
525
+ string** (the T5 icon is controlled separately by `showIcon` above):
374
526
 
375
527
  ```ts
376
528
  splash: { enabled: true, logoAsset: "" }
@@ -408,10 +560,9 @@ within the same deadline. Once dismissed, the iOS splash stays dismissed even if
408
560
  OTA timing settings change. Branded-lite Android image splashes use translucent dark system-bar
409
561
  scrims with light icons for legibility; color and gradient splashes remain full-bleed.
410
562
  Web retains its current transitions and readiness.
411
- The standalone branded-lite macOS shell currently does not mount a boot splash
412
- overlay; `splash.enabled` does not enable one there. The shared SwiftUI background
413
- renderer is available on macOS, but this host handoff integration covers Android
414
- and iOS. macOS shell integration requires a separate change.
563
+ The standalone branded-lite macOS shell mounts the same T5 splash with its native fallback,
564
+ artwork readiness and bounded exit. AppKit has no OS launch splash. The shared artwork gate is
565
+ used by the iOS and Mac shells; the Android host warms the same URLs through its renderer cache.
415
566
 
416
567
  Branded-lite builds expose the launcher artwork as the regular iOS image asset
417
568
  `branded_lite_app_icon`, so the same logo configuration works on Android and iOS.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wix/himalaya-cli",
3
- "version": "0.1568.0",
3
+ "version": "0.1569.0",
4
4
  "type": "module",
5
5
  "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.",
6
6
  "keywords": [
@@ -71,5 +71,5 @@
71
71
  "artifactId": "himalaya-cli"
72
72
  }
73
73
  },
74
- "falconPackageHash": "c098ae02840c1a3393199b2b6a265dd3f41ddafe769490763d9f7f7e"
74
+ "falconPackageHash": "666ab69b9997a9eb57284df9f6b9a084eea7adcc34322d3afa349a92"
75
75
  }
@@ -52,6 +52,16 @@ export default defineApp({
52
52
  ]
53
53
  },
54
54
  designTokensPath: "./tokens.json",
55
+ // Native fallback; the T5 splash descriptor owns the editable launch appearance.
56
+ splash: {
57
+ "enabled": true,
58
+ "backgroundColor": "accentPrimary",
59
+ "logoAsset": "branded_lite_app_icon",
60
+ "logoWidth": 192,
61
+ "layout": "logoOnly",
62
+ "minVisibleMs": 0,
63
+ "maxHoldMs": 5000
64
+ },
55
65
  navigation: {
56
66
  "navKind": "responsive",
57
67
  "scheme": "himalaya-__HIMI_APP_SLUG__",
@@ -2,6 +2,7 @@
2
2
  // Raw-descriptor dialect (see `himi docs tier-5-add-a-screen`); templated routes
3
3
  // fill __HIMI_ID__ sentinels per request.
4
4
  import config from "../config.js";
5
+ import splashIcon from "../splash.json" with { type: "json" };
5
6
 
6
7
  const runtimeSetting = (value: unknown): unknown => {
7
8
  if (value === "__HIMI_PODCAST_FEED_URL__") return process.env.PODCAST_FEED_URL?.trim() || "";
@@ -13,6 +14,227 @@ const runtimeSetting = (value: unknown): unknown => {
13
14
  };
14
15
 
15
16
  const SCREENS = runtimeSetting({
17
+ "himi_branded_splash": {
18
+ "screenId": "himi_branded_splash",
19
+ "renderer": "sdui_intent",
20
+ "title": "",
21
+ "schemaVersion": 1,
22
+ "cacheControl": {
23
+ "maxAge": 0,
24
+ "staleWhileRevalidate": 0
25
+ },
26
+ "input": {
27
+ "showIcon": true,
28
+ "title": "",
29
+ "caption": ""
30
+ },
31
+ "logicBundle": {
32
+ "url": "http://localhost:8190/v1/bundles/himi-branded-lite-splash?integrity=",
33
+ "integrity": "",
34
+ "contentType": "application/javascript+ts-bundle",
35
+ "declaredCapabilities": [],
36
+ "minBinaryVersion": "0.1.0",
37
+ "bundleVersion": "0.0.1"
38
+ },
39
+ "payload": {
40
+ "id": "splash_t5",
41
+ "body": {
42
+ "package": "himalaya",
43
+ "type": "ZStack",
44
+ "props": {
45
+ "alignment": "center",
46
+ "children": [
47
+ {
48
+ "id": "splash_t5_gradient",
49
+ "body": {
50
+ "package": "himalaya",
51
+ "type": "VStack",
52
+ "props": {
53
+ "children": [
54
+ {
55
+ "id": "splash_t5_gradient_fill",
56
+ "body": {
57
+ "package": "himalaya",
58
+ "type": "Spacer",
59
+ "props": {}
60
+ }
61
+ }
62
+ ]
63
+ }
64
+ },
65
+ "modifiers": {
66
+ "fillMaxWidth": true,
67
+ "backgroundGradient": {
68
+ "token": "brand"
69
+ },
70
+ "transition": {
71
+ "enter": "fade",
72
+ "motion": {
73
+ "token": "appearSoft"
74
+ }
75
+ },
76
+ "respectReducedMotion": true
77
+ }
78
+ },
79
+ {
80
+ "id": "splash_t5_icon",
81
+ "body": {
82
+ "package": "himalaya",
83
+ "type": "ZStack",
84
+ "props": {
85
+ "alignment": "center",
86
+ "children": [
87
+ {
88
+ "id": "splash_t5_icon_image",
89
+ "body": {
90
+ "package": "himalaya",
91
+ "type": "Image",
92
+ "props": {
93
+ "asset": "branded_lite_app_icon",
94
+ "width": 192,
95
+ "height": 192,
96
+ "contentMode": "fit"
97
+ }
98
+ },
99
+ "modifiers": {
100
+ "accessibilityRole": "decorative",
101
+ "scale": 1.5
102
+ }
103
+ }
104
+ ]
105
+ }
106
+ },
107
+ "modifiers": {
108
+ "width": 192,
109
+ "height": 192,
110
+ "clipShape": "circle",
111
+ "accessibilityRole": "decorative",
112
+ "hiddenPath": "$service:splash.iconHidden",
113
+ "transition": {
114
+ "enter": "none",
115
+ "exit": "fade",
116
+ "motion": {
117
+ "token": "appearSoft"
118
+ }
119
+ },
120
+ "respectReducedMotion": true
121
+ }
122
+ },
123
+ {
124
+ "id": "",
125
+ "body": {
126
+ "package": "himalaya",
127
+ "type": "VStack",
128
+ "props": {
129
+ "alignment": "center",
130
+ "spacing": 0,
131
+ "children": [
132
+ {
133
+ "id": "splash_t5_top",
134
+ "body": {
135
+ "package": "himalaya",
136
+ "type": "Spacer",
137
+ "props": {}
138
+ },
139
+ "modifiers": {
140
+ "weight": 1
141
+ }
142
+ },
143
+ {
144
+ "id": "splash_t5_copy",
145
+ "body": {
146
+ "package": "himalaya",
147
+ "type": "VStack",
148
+ "props": {
149
+ "alignment": "center",
150
+ "spacing": 16,
151
+ "children": [
152
+ {
153
+ "id": "splash_t5_title",
154
+ "body": {
155
+ "package": "himalaya",
156
+ "type": "Text",
157
+ "props": {
158
+ "text": "$service:splash.title",
159
+ "style": "title1",
160
+ "color": "textOnAccent",
161
+ "textAlign": "center"
162
+ }
163
+ }
164
+ },
165
+ {
166
+ "id": "splash_t5_caption",
167
+ "body": {
168
+ "package": "himalaya",
169
+ "type": "Text",
170
+ "props": {
171
+ "text": "$service:splash.caption",
172
+ "style": "body",
173
+ "color": "textOnAccent",
174
+ "collapseWhenEmpty": true,
175
+ "textAlign": "center"
176
+ }
177
+ }
178
+ },
179
+ {
180
+ "id": "splash_t5_bottom",
181
+ "body": {
182
+ "package": "himalaya",
183
+ "type": "Spacer",
184
+ "props": {}
185
+ }
186
+ }
187
+ ]
188
+ }
189
+ },
190
+ "modifiers": {
191
+ "weight": 1,
192
+ "fillMaxWidth": true,
193
+ "padding": {
194
+ "top": 120,
195
+ "bottom": 24,
196
+ "leading": 24,
197
+ "trailing": 24
198
+ }
199
+ }
200
+ }
201
+ ]
202
+ }
203
+ }
204
+ },
205
+ {
206
+ "id": "splash_t5_presented",
207
+ "body": {
208
+ "package": "himalaya",
209
+ "type": "Spacer",
210
+ "props": {}
211
+ },
212
+ "modifiers": {
213
+ "width": 0,
214
+ "height": 0,
215
+ "hiddenPath": "$service:splash.presentationPending",
216
+ "onAppear": {
217
+ "actionId": "splash.presented",
218
+ "params": {
219
+ "motion": "appearSoft"
220
+ }
221
+ }
222
+ }
223
+ }
224
+ ]
225
+ }
226
+ },
227
+ "modifiers": {
228
+ "fillMaxWidth": true,
229
+ "onAppear": {
230
+ "actionId": "tier5.splash.present"
231
+ },
232
+ "background": {
233
+ "token": "accentPrimary"
234
+ }
235
+ }
236
+ }
237
+ },
16
238
  "himi_branded_home": {
17
239
  "screenId": "himi_branded_home",
18
240
  "renderer": "sdui_intent",
@@ -31528,6 +31750,21 @@ const SCREENS = runtimeSetting({
31528
31750
  },
31529
31751
  }) as Record<string, unknown>;
31530
31752
 
31753
+ // The hosted app icon is content: updating splash.json needs an OTA publish, not a native build.
31754
+ // Without a hosted image, preserve the bundled icon and its native handoff crop.
31755
+ if (splashIcon.iconUrl) {
31756
+ const url = new URL(splashIcon.iconUrl);
31757
+ if (url.protocol !== "https:" || url.username || url.password) throw new Error("Splash images require a public HTTPS URL");
31758
+ interface IconNode { id?: string; body: { package: string; type: string; props: { children?: IconNode[]; asset?: string; url?: string } } }
31759
+ const splash = SCREENS.himi_branded_splash as { input?: { customLogo?: boolean }; payload?: { body?: { props?: { children?: IconNode[] } } } };
31760
+ const icon = splash.payload?.body?.props?.children?.find((node) => node.id === "splash_t5_icon");
31761
+ const image = icon?.body.type === "ZStack" ? icon.body.props.children?.find((node) => node.id === "splash_t5_icon_image") : icon;
31762
+ if (image && !splash.input?.customLogo) {
31763
+ delete image.body.props.asset;
31764
+ image.body.props.url = splashIcon.iconUrl;
31765
+ }
31766
+ }
31767
+
31531
31768
  // The language destination stays registered for deep links and future translations. Keep its
31532
31769
  // account entry out of a single-language app; adding a locale to config.locale.translations
31533
31770
  // makes the same entry visible after the app config reloads.
@@ -36312,6 +36549,31 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
36312
36549
  }
36313
36550
  }
36314
36551
  },
36552
+ {
36553
+ "id": "himi_service.about_rich",
36554
+ "body": {
36555
+ "package": "himalaya",
36556
+ "type": "RichContent",
36557
+ "props": {
36558
+ "documentJsonPath": "$service:himiBookingService.aboutJson",
36559
+ "onLink": {
36560
+ "actionId": "tier5.himiBookingService.openLink"
36561
+ },
36562
+ "fallback": {
36563
+ "id": "",
36564
+ "body": {
36565
+ "package": "himalaya",
36566
+ "type": "Text",
36567
+ "props": {
36568
+ "text": "$service:himiBookingService.about",
36569
+ "style": "body",
36570
+ "color": "textPrimary"
36571
+ }
36572
+ }
36573
+ }
36574
+ }
36575
+ }
36576
+ },
36315
36577
  {
36316
36578
  "id": "himi_service.about",
36317
36579
  "body": {
@@ -36323,6 +36585,9 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
36323
36585
  "color": "textPrimary",
36324
36586
  "collapseWhenEmpty": true
36325
36587
  }
36588
+ },
36589
+ "modifiers": {
36590
+ "hiddenPath": "$service:himiBookingService.hasAboutJson"
36326
36591
  }
36327
36592
  }
36328
36593
  ]
@@ -37,6 +37,9 @@
37
37
  "himi_branded_home": {
38
38
  "displayName": "Home"
39
39
  },
40
+ "himi_branded_splash": {
41
+ "displayName": "Splash"
42
+ },
40
43
  "himi_cart": {
41
44
  "displayName": "Cart"
42
45
  },
@@ -0,0 +1,3 @@
1
+ {
2
+ "iconUrl": ""
3
+ }