@wix/himalaya-cli 0.1157.0 → 0.1158.0

package/dist/cli.mjs

@@ -6783,6 +6783,7 @@ function walk(node, registry, path2, out2) {
 var SYSTEM_FONT_FAMILY, TONAL_ELEVATION_ALPHA, COLOR_TOKEN_PROPS, TYPOGRAPHY_TOKEN_PROPS;
 var init_tokens = __esm({
   "../../core/ts/src/tokens.ts"() {
+    "use strict";
     SYSTEM_FONT_FAMILY = "$system";
     TONAL_ELEVATION_ALPHA = [0, 0.05, 0.08, 0.11, 0.12, 0.14];
     COLOR_TOKEN_PROPS = {
@@ -6833,6 +6834,7 @@ function resolveTranslation(value, catalog, sourceCatalog) {
 var BINDING_SIGILS, BINDING_SIGIL_RE, TRANSLATION_PREFIX, TRANSLATION_KEY_RE;
 var init_bindings = __esm({
   "../../core/ts/src/bindings.ts"() {
+    "use strict";
     BINDING_SIGILS = ["service", "flag", "item", "t"];
     BINDING_SIGIL_RE = new RegExp(
       `^\\$(?:${BINDING_SIGILS.filter((s) => s !== "t").join("|")})\\b|^\\$t:`

package/guides/himi-skill.md

@@ -450,6 +450,14 @@ I want to create a mobile app for my business. Follow this skill:
 https://apps.wix.com/_api/himi-serve/skill.md
 ```
 
+## Home-screen widgets
+
+Read `himi docs widgets` **before** you write a `defineWidget`. A widget is a frozen poster frame:
+its `render` runs once, at build time, over each service's **initial** `state`. Actions, `fetch` and
+Wix data never reach it, and there is no live-data path yet, so a widget written over fetched data
+ships its placeholder. Design it around initial state, constants or a `timeline`, and deep-link the
+tap into the screen that has the live data.
+
 ## Native UX evidence gate
 
 Before declaring a multi-screen app ready, run `himi ux audit --content . --strict` and resolve its findings. After driving each available native shell, persist the actual checks with `himi ux record`; record an unavailable platform with its reason rather than claiming coverage.

package/guides/index.json

@@ -190,6 +190,12 @@
       "category": "Workers & SDKs",
       "file": "cms-collections.md"
     },
+    {
+      "id": "widgets",
+      "title": "Home-screen widgets (what a widget can show)",
+      "category": "Workers & SDKs",
+      "file": "widgets.md"
+    },
     {
       "id": "wix-sdk-overview",
       "title": "Wix SDK overview (front door)",

package/guides/widgets.md

@@ -0,0 +1,233 @@
+# Home-screen widgets
+
+A widget is a **frozen poster frame** of your app. It is drawn by the operating system on a home
+screen, lock screen or watch face, and opened with a tap. Your worker never runs
+inside it. This page explains where a widget's content comes from, because that is the part that
+surprises people: **a widget shows what your worker's state is at build time, not what the worker
+later fetches.**
+
+## The one rule: a widget renders initial state, once
+
+You declare a widget with `defineWidget` in the same worker file as your `defineService`:
+
+```ts
+import { defineWidget } from "@wix/himalaya/widget";
+
+defineWidget("<widget id>", {
+  family: "ios_home",   // which OS surface — see the table below
+  size: "small",
+  deepLink: "<your app scheme>://screen/<screen id>",
+  refresh: { ttlSeconds: 900 },
+  render: (services) => ({ /* a component tree of literals */ }),
+});
+```
+
+When your app is built or served, the platform **produces** each widget:
+
+1. It evaluates your worker in a sandbox and records each `defineService`'s **initial `state`**.
+2. It calls `render(services)` **once, synchronously**, where `services` is
+   `{ <service name>: <its initial state> }`.
+3. It freezes the tree `render` returned and serves it as the widget's snapshot.
+
+So, inside that sandbox:
+
+| What your worker does | What the widget sees |
+|---|---|
+| `state: { … }` in `defineService` | ✅ exactly that object |
+| Constants and plain functions in the file | ✅ available to `render` |
+| An action (`load`, `refresh`, …), sync or `async` | ❌ never runs — the widget keeps the initial state |
+| `fetch`, Wix data queries, any Wix SDK call | ❌ `fetch` throws; nothing it would return arrives |
+| `setTimeout` / `setInterval` | ❌ never fire |
+| `$service:` / `$item` bindings in the tree | ❌ rejected — the snapshot must be literals |
+
+`render` must therefore be **synchronous and side-effect free**: no network, no awaiting, no
+bindings, only **resolved literal values**. Reading the clock is the one allowed dependency.
+`Date.now()` works and is evaluated at produce time, so a value computed from it is as fresh as
+the last produce (see [refresh](#refresh-taps-and-previews)). A `render` that throws, or returns a
+tree with a binding in it, makes that widget fail to produce.
+
+### There is no live-data path yet
+
+Data your worker fetches **cannot** reach a widget today. `refresh.pushTopic` exists in the type
+definitions, but nothing consumes it yet: setting it does not make the widget update when data
+changes. Plan the widget around what you know when the app is built — a call to action, a
+constant, or a schedule (see [timelines](#content-whose-future-you-know-live-time-and-timelines)) — and let the
+tap take the user into the app, where the live data is.
+
+## A widget that stays inside the contract
+
+This widget shows the studio's name and a fixed call to action, both from initial state. Tapping
+it opens the booking screen, which loads the real schedule.
+
+<!-- widget-example: within-contract -->
+```ts
+import { defineService } from "@wix/himalaya/state";
+import { defineWidget } from "@wix/himalaya/widget";
+
+defineService("studio", {
+  state: { name: "Harbor Yoga", cta: "Book your next class" },
+});
+
+defineWidget("studio.book", {
+  family: "ios_home",
+  size: "small",
+  deepLink: "harboryoga://screen/book",
+  refresh: { ttlSeconds: 86400 },
+  render: (services) => {
+    const studio = services.studio as { name: string; cta: string };
+    return {
+      id: "root",
+      body: { package: "himalaya", type: "VStack", props: { spacing: 4, children: [
+        { id: "name", body: { package: "himalaya", type: "Text", props: { text: studio.name, style: "headline" } } },
+        { id: "cta", body: { package: "himalaya", type: "Text", props: { text: studio.cta, style: "caption" } } },
+      ] } },
+    };
+  },
+});
+```
+
+It produces exactly this frozen tree:
+
+<!-- widget-example: within-contract.payload -->
+```json
+{
+  "id": "root",
+  "body": { "package": "himalaya", "type": "VStack", "props": { "spacing": 4, "children": [
+    { "id": "name", "body": { "package": "himalaya", "type": "Text", "props": { "text": "Harbor Yoga", "style": "headline" } } },
+    { "id": "cta", "body": { "package": "himalaya", "type": "Text", "props": { "text": "Book your next class", "style": "caption" } } }
+  ] } }
+}
+```
+
+## The mistake: a widget over fetched data
+
+This is the natural way to write it, and it ships the placeholder:
+
+<!-- widget-example: anti-pattern -->
+```ts
+import { defineService } from "@wix/himalaya/state";
+import { defineWidget } from "@wix/himalaya/widget";
+
+defineService("latest", {
+  state: { title: "Loading…" },
+  actions: {
+    async load(s) {
+      const res = await fetch("https://example.com/latest.json");
+      const { title } = (await res.json()) as { title: string };
+      return { ...s, title };
+    },
+  },
+});
+
+defineWidget("latest.story", {
+  family: "ios_home",
+  size: "small",
+  deepLink: "myapp://screen/home",
+  refresh: { ttlSeconds: 900 },
+  render: (services) => ({
+    id: "w",
+    body: { package: "himalaya", type: "Text", props: { text: (services.latest as { title: string }).title } },
+  }),
+});
+```
+
+`load` never runs at produce time, so `render` reads the initial state and the widget says
+"Loading…" forever:
+
+<!-- widget-example: anti-pattern.payload -->
+```json
+{ "id": "w", "body": { "package": "himalaya", "type": "Text", "props": { "text": "Loading…" } } }
+```
+
+Calling the action yourself at the top level (`svc.load()`) does not help either: at produce time
+every action resolves to the initial state.
+
+## Content whose future you know: live time and timelines
+
+**Countdowns and clock text: `Text.timeRef`.** A `Text` with
+`timeRef: { at: <epoch seconds>, style: "timer" | "relative" | "date" | "time" | "offset" }`
+shows a time value that overrides the `Text`'s `text`. How live it is depends on the platform:
+
+- **iPhone (home, lock, Live Activity)**: the OS ticks it every second, with no refresh and no worker.
+- **Android home screen**: it is formatted only when the widget is redrawn, which the OS
+  schedules (typically no more often than every 15 minutes), so do not rely on it to count seconds.
+- **`web_card`**: `timeRef` is ignored and the `Text`'s own `text` is shown, so always set a
+  `text` fallback.
+
+```ts
+{ id: "starts", body: { package: "himalaya", type: "Text",
+  props: { text: "Starts soon", timeRef: { at: Math.floor(Date.now() / 1000) + 3600, style: "timer" } } } }
+```
+
+**Discrete future states: `timeline`.** When you know in advance which *different content* the
+widget should show later — today's agenda, a streak that resets at midnight — add a `timeline`. It returns frozen frames, each with the epoch
+second it becomes current, and the OS advances through them with no network and no worker:
+
+```ts
+// frame(title, time) returns a component tree; DAY_START is today's midnight in epoch seconds.
+defineWidget("studio.agenda", {
+  family: "ios_home",
+  size: "small",
+  deepLink: "harboryoga://screen/schedule",
+  refresh: { ttlSeconds: 900 },
+  render: () => frame("Morning flow", "7:00"),            // also frame 0 for older clients
+  timeline: () => [
+    { startsAt: DAY_START + 7 * 3600, component: frame("Morning flow", "7:00") },
+    { startsAt: DAY_START + 12 * 3600, component: frame("Lunch stretch", "12:00") },
+  ],
+});
+```
+
+`timeline` follows the same rule as `render`: synchronous, no network, literals only. It is
+evaluated at produce time, so its frames are only as current as the last produce, and it keeps at
+most 48 frames — never bake a second-by-second countdown into it; that is what `timeRef` is for.
+
+## Families and sizes
+
+| `family` | Surface |
+|---|---|
+| `ios_home` | iPhone home screen |
+| `ios_lock` | iPhone lock screen |
+| `android_home` | Android home screen |
+| `web_card` | A card on the web preview |
+| `ios_live_activity` | iPhone Live Activity |
+| `watch_complication` | Watch face complication |
+
+`size` is the OS size hint: `small`, `medium` or `large` for home-screen widgets, and `inline`,
+`circular` or `rectangular` for lock-screen and complication slots.
+
+One worker can declare several widgets, one per family and size. To give a widget a *different
+layout* from your phone screen while reading the same services, use `defineView` with a
+`widget:<family>` surface instead. It is the same frozen contract, chosen per surface, and
+`size`, `deepLink`, `refresh` and `timeline` are accepted only on those frozen surfaces.
+
+**In-car screens are not a widget family.** The car display is authored with
+`defineView("<view id>", { surface: "car", deepLink, refresh, render })`: frozen like a widget,
+with the same rules for `render`. `deepLink` and `refresh` are required, as for a widget; `size` is
+not, because the car lays out its own rows. It never goes through `defineWidget`.
+
+## Refresh, taps and previews
+
+- **`refresh.ttlSeconds`** is how long a snapshot may be served before it is produced again. A new
+  produce still renders the *initial* state, so a shorter TTL only helps content that is computed
+  from the clock at produce time. It does not make fetched data appear.
+- **`refresh.preferredRefreshSeconds`** (optional) is a hint to the OS background-refresh
+  scheduler about how often to redraw the widget; when unset, `ttlSeconds` is used. The OS may
+  clamp or defer it (Android never redraws more often than every 15 minutes), so treat it as a
+  request, not a schedule.
+- **`deepLink`** is where a tap takes the user. Point it at the screen that shows the live version
+  of what the widget summarises.
+- **Preview a widget** while you work: `himi run --watch --content .` serves it at
+  `GET /v1/widget/<widget id>`, and `GET /v1/widgets` lists every widget the app produces.
+  `himi surfaces --measure-widgets` reports which families your package actually produces.
+
+## What `himi validate` checks
+
+A widget is **declared** when a worker calls `defineWidget` (or `defineView` with a `widget:`
+surface). If a declared widget fails to produce — `render` threw, returned a binding, or used a
+component its family does not allow — `himi validate` reports `widget-not-produced`. It is a
+warning by default and an **error under `--strict`**, so a package cannot ship a widget it
+declared but that renders nothing.
+
+A widget that produces the *placeholder* (the mistake above) is not an error: it renders, it just
+shows initial state. Check the snapshot at `GET /v1/widget/<widget id>` before you ship.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1157.0",
+  "version": "0.1158.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": [
@@ -67,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "3855653c89440e946466c0cb88bbc773e9933df0411400c4fbd70c04"
+  "falconPackageHash": "e2949fb643b50db7dff29f93ca7ee3235cd80cdac4a32d59ba2f89a1"
 }