@wix/himalaya-cli 0.1157.0 → 0.1159.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 = {

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.1159.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": "b894b541da6352858ee72b8651ce6c4885ab2e35c614be481fd38bd5"
 }

package/templates/beauty-salon/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/beauty-salon-owner/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/branded-lite/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/brandy/config.ts

@@ -47,7 +47,14 @@ export default defineApp({
     actions: "http://localhost:8190/v1/actions",
     sync: "http://localhost:8190/v1/sync",
   },
-  capabilities: [],
+  // `push` lets the app ask for notification permission and show the Notifications screen.
+  capabilities: ["push"],
+  // Ask for notification permission on the first launch. Tapped notifications that carry one of
+  // your site's URLs open the page's tab (`navigation.site` below).
+  push: {
+    registrar: "generic",
+    requestPermissionOnLaunch: true,
+  },
   // Your brand colours paint the NATIVE chrome (tabs, drawer, splash); the site paints its pages.
   designTokensPath: "./tokens.json",
   // "Ready" means the first page has painted, not just the app shell — otherwise the splash
@@ -66,11 +73,15 @@ export default defineApp({
     navKind: "responsive",
     scheme: "himalaya-__HIMI_APP_SLUG__",
     deepLinkPatterns: [],
-    linkableScreens: siteLinkableScreens(site),
+    linkableScreens: [
+      ...siteLinkableScreens(site),
+      { screenId: "himi_notification_settings", isPublic: true, paramKeys: [], parentScreenId: "" },
+    ],
     // A notification or app link carrying one of your site's URLs opens that page's tab.
     site: siteNavConfig(site),
     tabBar: { items: nav.tabs },
-    drawer: { items: nav.drawer },
+    // Your site's drawer pages, then the native Notifications screen.
+    drawer: { items: [...nav.drawer, { id: "drawer_notifications", screenId: "himi_notification_settings", label: "Notifications", icon: "bell" }] },
   },
   entities: {},
 });

package/templates/brandy/dev/index.ts

@@ -5,6 +5,340 @@ import { siteScreens } from "@himalaya/core";
 import config, { site } from "../config.js";
 
 const SCREENS = siteScreens(site);
+
+// The native Notifications screen (a drawer row): whether this app may notify, and the one action
+// that changes it — Turn on (the system prompt when it can still show, otherwise the device
+// settings) or Open settings. It runs on the himi-notification-settings worker in tier5-src/.
+const NOTIFICATIONS = {
+  "screenId": "himi_notification_settings",
+  "renderer": "sdui_intent",
+  "title": "",
+  "schemaVersion": 1,
+  "cacheControl": {
+    "maxAge": 0,
+    "staleWhileRevalidate": 0
+  },
+  "payload": {
+    "id": "himi_notification_settings.root",
+    "body": {
+      "package": "himalaya",
+      "type": "VStack",
+      "props": {
+        "spacing": 16,
+        "alignment": "leading",
+        "children": [
+          {
+            "id": "himi_notification_settings.title",
+            "body": {
+              "package": "himalaya",
+              "type": "Text",
+              "props": {
+                "text": "Notifications",
+                "style": "title1"
+              }
+            }
+          },
+          {
+            "id": "himi_notification_settings.status",
+            "body": {
+              "package": "himalaya",
+              "type": "HStack",
+              "props": {
+                "spacing": 12,
+                "children": [
+                  {
+                    "id": "",
+                    "body": {
+                      "package": "himalaya",
+                      "type": "Icon",
+                      "props": {
+                        "name": "bell",
+                        "size": 24,
+                        "tint": "accentPrimary"
+                      }
+                    },
+                    "modifiers": {
+                      "accessibilityRole": "decorative"
+                    }
+                  },
+                  {
+                    "id": "",
+                    "body": {
+                      "package": "himalaya",
+                      "type": "VStack",
+                      "props": {
+                        "spacing": 4,
+                        "alignment": "leading",
+                        "children": [
+                          {
+                            "id": "himi_notification_settings.status_title",
+                            "body": {
+                              "package": "himalaya",
+                              "type": "Text",
+                              "props": {
+                                "text": "$service:himiNotificationSettings.statusTitle",
+                                "style": "title2"
+                              }
+                            }
+                          },
+                          {
+                            "id": "himi_notification_settings.status_body",
+                            "body": {
+                              "package": "himalaya",
+                              "type": "Text",
+                              "props": {
+                                "text": "$service:himiNotificationSettings.statusBody",
+                                "style": "body",
+                                "color": "textSecondary",
+                                "collapseWhenEmpty": true
+                              }
+                            }
+                          }
+                        ]
+                      }
+                    }
+                  }
+                ]
+              }
+            },
+            "modifiers": {
+              "background": {
+                "token": "surfaceElevated"
+              },
+              "border": {
+                "width": 1,
+                "color": {
+                  "token": "border"
+                }
+              },
+              "cornerRadius": 16,
+              "padding": {
+                "leading": 16,
+                "trailing": 16,
+                "top": 16,
+                "bottom": 16
+              }
+            }
+          },
+          {
+            "id": "himi_notification_settings.turn_on",
+            "body": {
+              "package": "himalaya",
+              "type": "Button",
+              "props": {
+                "title": "Turn on notifications",
+                "style": "primary",
+                "fullWidth": true,
+                "action": {
+                  "actionId": "tier5.himiNotificationSettings.enable"
+                }
+              }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:himiNotificationSettings.hideTurnOn"
+            }
+          },
+          {
+            "id": "himi_notification_settings.open_settings",
+            "body": {
+              "package": "himalaya",
+              "type": "Button",
+              "props": {
+                "title": "Open settings",
+                "style": "secondary",
+                "fullWidth": true,
+                "action": {
+                  "actionId": "tier5.himiNotificationSettings.openSettings"
+                }
+              }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:himiNotificationSettings.hideOpenSettings"
+            }
+          },
+          {
+            "id": "himi_notification_settings.message",
+            "body": {
+              "package": "himalaya",
+              "type": "Text",
+              "props": {
+                "text": "$service:himiNotificationSettings.message",
+                "style": "footnote",
+                "color": "textSecondary",
+                "collapseWhenEmpty": true
+              }
+            }
+          }
+        ]
+      }
+    },
+    "modifiers": {
+      "background": {
+        "token": "surfacePrimary"
+      },
+      "padding": {
+        "leading": 16,
+        "trailing": 16,
+        "top": 18,
+        "bottom": 28
+      },
+      "onAppear": {
+        "actionId": "tier5.himiNotificationSettings.refresh"
+      }
+    }
+  },
+  "logicBundle": {
+    "url": "http://localhost:8190/v1/bundles/himi-notification-settings?integrity=",
+    "integrity": "",
+    "contentType": "application/javascript+ts-bundle",
+    "declaredCapabilities": [
+      "push"
+    ],
+    "minBinaryVersion": "0.2.0",
+    "bundleVersion": "0.0.1"
+  }
+};
+// The offline seed copy has no running worker, so it carries no buttons and no live bindings.
+const NOTIFICATIONS_SEED = {
+  "screenId": "himi_notification_settings",
+  "renderer": "sdui_intent",
+  "title": "",
+  "schemaVersion": 1,
+  "cacheControl": {
+    "maxAge": 0,
+    "staleWhileRevalidate": 0
+  },
+  "payload": {
+    "id": "himi_notification_settings.root",
+    "body": {
+      "package": "himalaya",
+      "type": "VStack",
+      "props": {
+        "spacing": 16,
+        "alignment": "leading",
+        "children": [
+          {
+            "id": "himi_notification_settings.title",
+            "body": {
+              "package": "himalaya",
+              "type": "Text",
+              "props": {
+                "text": "Notifications",
+                "style": "title1"
+              }
+            }
+          },
+          {
+            "id": "himi_notification_settings.status",
+            "body": {
+              "package": "himalaya",
+              "type": "HStack",
+              "props": {
+                "spacing": 12,
+                "children": [
+                  {
+                    "id": "",
+                    "body": {
+                      "package": "himalaya",
+                      "type": "Icon",
+                      "props": {
+                        "name": "bell",
+                        "size": 24,
+                        "tint": "accentPrimary"
+                      }
+                    },
+                    "modifiers": {
+                      "accessibilityRole": "decorative"
+                    }
+                  },
+                  {
+                    "id": "",
+                    "body": {
+                      "package": "himalaya",
+                      "type": "VStack",
+                      "props": {
+                        "spacing": 4,
+                        "alignment": "leading",
+                        "children": [
+                          {
+                            "id": "himi_notification_settings.status_title",
+                            "body": {
+                              "package": "himalaya",
+                              "type": "Text",
+                              "props": {
+                                "text": "Notifications",
+                                "style": "title2"
+                              }
+                            }
+                          },
+                          {
+                            "id": "himi_notification_settings.status_body",
+                            "body": {
+                              "package": "himalaya",
+                              "type": "Text",
+                              "props": {
+                                "text": "Connect to the internet to change notification settings.",
+                                "style": "body",
+                                "color": "textSecondary",
+                                "collapseWhenEmpty": true
+                              }
+                            }
+                          }
+                        ]
+                      }
+                    }
+                  }
+                ]
+              }
+            },
+            "modifiers": {
+              "background": {
+                "token": "surfaceElevated"
+              },
+              "border": {
+                "width": 1,
+                "color": {
+                  "token": "border"
+                }
+              },
+              "cornerRadius": 16,
+              "padding": {
+                "leading": 16,
+                "trailing": 16,
+                "top": 16,
+                "bottom": 16
+              }
+            }
+          }
+        ]
+      }
+    },
+    "modifiers": {
+      "background": {
+        "token": "surfacePrimary"
+      },
+      "padding": {
+        "leading": 16,
+        "trailing": 16,
+        "top": 18,
+        "bottom": 28
+      },
+      "onAppear": {
+        "actionId": "tier5.himiNotificationSettings.refresh"
+      }
+    }
+  },
+  "logicBundle": {
+    "url": "http://localhost:8190/v1/bundles/himi-notification-settings?integrity=",
+    "integrity": "",
+    "contentType": "application/javascript+ts-bundle",
+    "declaredCapabilities": [
+      "push"
+    ],
+    "minBinaryVersion": "0.2.0",
+    "bundleVersion": "0.0.1"
+  }
+};
 // The home screen is always the `home` page's: `site_home`. A literal on purpose — `himi init`
 // and the agent tooling read `homeScreenId` from this file as written; config.ts refuses a map
 // whose first tab is anything else, so the literal and the tab bar cannot disagree.
@@ -14,12 +348,15 @@ export default {
   homeScreenId: "site_home",
   screens: {
     // A fresh copy per build: descriptors are pure functions of the site block.
-    exact: Object.fromEntries(Object.keys(SCREENS).map((id) => [id, () => structuredClone(SCREENS[id])])),
+    exact: {
+      ...Object.fromEntries(Object.keys(SCREENS).map((id) => [id, () => structuredClone(SCREENS[id])])),
+      himi_notification_settings: () => structuredClone(NOTIFICATIONS),
+    },
     templated: [],
   },
   actions: [],
   createStore: () => ({}),
   // Every page is seeded, so the whole tab bar and drawer work on a cold offline start (each
   // WebView then shows its own offline state until the network returns).
-  seed: { screens: SCREENS, data: {} },
+  seed: { screens: { ...SCREENS, himi_notification_settings: NOTIFICATIONS_SEED }, data: {} },
 };

package/templates/brandy/tier5-src/_shared/himi-copy.ts

@@ -0,0 +1,56 @@
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
+// §"Copy is configuration"): a worker never hardcodes user-facing copy — the
+// descriptor bakes the provisioned copy-pack overrides relevant to this worker
+// into its onAppear action params as a `copy` JSON object (key → override
+// string, computed from the app contract at descriptor-build time), and the
+// worker reads every user-facing string through `copyParam(key, fallback)`.
+//
+// STASHED (the stashed appear-params idiom, himi-branded-lite-home): the
+// param-carrying onAppear dispatch updates the stash; later arg-less calls
+// (self-kick refreshes, retry buttons, pull-to-refresh) fall back to it, so
+// resolution order can never drop the pack. With no pack the param is absent
+// and every read returns `fallback` verbatim — routing a worker string through
+// copyParam is byte-for-byte behavior-preserving.
+//
+// Pure + Hermes-safe (no host globals, no Node APIs, no imports): bundled into
+// every worker that emits user-facing copy, and copied verbatim into the
+// generated templates' tier5-src/_shared/.
+
+let stashedCopy: Record<string, string> = {};
+
+/** Absorb the `copy` onAppear param (a JSON object of key → override string)
+ *  from an action arg. Call first in every action that can receive onAppear
+ *  params (load/refresh). Non-copy args and malformed packs are ignored — the
+ *  stock fallbacks keep rendering. */
+export function stashCopy(arg: unknown): void {
+  if (!arg || typeof arg !== "object") return;
+  const raw = (arg as Record<string, unknown>).copy;
+  if (typeof raw !== "string" || !raw) return;
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
+    const next: Record<string, string> = {};
+    for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+      if (typeof value === "string") next[key] = value;
+    }
+    stashedCopy = next;
+  } catch {
+    // Malformed pack param — keep the stock copy rather than dying mid-action.
+  }
+}
+
+/** The provisioned override for `key`, or `fallback` (the stock copy) when no
+ *  pack / no such key reached this worker. */
+export function copyParam(key: string, fallback: string): string {
+  const value = stashedCopy[key];
+  return typeof value === "string" && value !== "" ? value : fallback;
+}
+
+/** Interpolate `{name}` placeholders in a (possibly overridden) template:
+ *  `copyTemplate("plans.joinOnSite", "…join {name}.", { name })`. Unknown
+ *  placeholders resolve to "" so a typo'd override degrades, never crashes. */
+export function copyTemplate(key: string, fallback: string, values: Record<string, string | number>): string {
+  return copyParam(key, fallback).replace(/\{([A-Za-z0-9_]+)\}/g, (_all, name: string) =>
+    name in values ? String(values[name]) : "",
+  );
+}

package/templates/brandy/tier5-src/himi-notification-settings/index.ts

@@ -0,0 +1,130 @@
+// himi-notification-settings — the shared Tier-5 worker behind an app's Notifications
+// settings screen: a native feature an app built on its website needs (App Store guideline 4.2).
+//
+// It shows whether this app may send notifications and offers ONE action:
+//   - off → "Turn on notifications": the OS prompt when the OS can still show it, else the OS
+//     settings. Whether a prompt is still possible is not knowable up front on every platform
+//     (Android reports "denied" both before the first ask and after a second refusal), so the
+//     action asks first and falls through to the settings when the answer is not a grant.
+//   - on → "Open settings", to turn them off there.
+// While the status is loading — or cannot be read at all — neither action shows.
+//
+// The screen must refresh when the user comes BACK from the OS settings, and a worker has
+// no clock. `refresh` (the screen's onAppear) therefore arms a `_poll`: the host suspends it
+// in the background and FIRES IT IMMEDIATELY on foreground, which is exactly the return
+// from Settings; the slow cadence in between is only a backstop. Re-armed on every entry,
+// because restored state arms no timer. A tick that sees notifications newly turned on calls
+// requestPermission(), which (with no prompt, the user has already decided) registers the
+// push token for this session.
+//
+// Copy is overridable through an optional `copy` param on the onAppear action (stashCopy /
+// copyParam), like the account worker; a descriptor that passes none gets the English
+// defaults. Declares the "push" capability.
+
+import { defineService, type PollDirective } from "@himalaya/state";
+import { getPermissionStatus, openSettings, requestPermission, type PushPermission } from "@himalaya/push";
+import { stashCopy, copyParam } from "../_shared/himi-copy.js";
+
+type Status = PushPermission | "loading" | "error";
+
+interface S {
+  status: Status;
+  statusTitle: string;
+  statusBody: string;
+  /** Hide flags, true until the status is known (and in the error state), so the live
+   *  screen shows no action while loading. NOTE an unresolved `$service:` hidden path fails
+   *  OPEN on every renderer — a descriptor with no running worker would show both — which is
+   *  why a seeded, worker-less copy of the screen must not carry the buttons at all. */
+  hideTurnOn: boolean;
+  hideOpenSettings: boolean;
+  /** A one-line note after an action (e.g. settings could not be opened here). */
+  message: string;
+}
+
+const POLL: PollDirective = {
+  id: "himi-notification-settings",
+  intervalMs: 60_000,
+  action: "himiNotificationSettings.check",
+  immediate: false,
+};
+
+/** The whole view for a status. Pure, so the test pins every branch. */
+export function viewFor(status: Status): Omit<S, "message"> {
+  const on = status === "granted";
+  const off = status === "denied" || status === "undetermined";
+  const statusTitle = on
+    ? copyParam("notificationSettings.onTitle", "Notifications are on")
+    : off
+      ? copyParam("notificationSettings.offTitle", "Notifications are off")
+      : copyParam("notificationSettings.loadingTitle", "Notifications");
+  const statusBody = on
+    ? copyParam("notificationSettings.onBody", "You'll get updates from this app. You can turn them off in your device settings.")
+    : off
+      ? copyParam("notificationSettings.offBody", "Turn them on to get updates from this app.")
+      : status === "error"
+        ? copyParam("notificationSettings.unavailableBody", "Notification settings aren't available here.")
+        : "";
+  return { status, statusTitle, statusBody, hideTurnOn: !off, hideOpenSettings: !on };
+}
+
+async function readStatus(): Promise<Status> {
+  try {
+    return await getPermissionStatus();
+  } catch {
+    // A missing or failing push capability is not "undetermined": offering Turn on would
+    // lead nowhere. Say it is unavailable and offer nothing.
+    return "error";
+  }
+}
+
+async function open(): Promise<boolean> {
+  try {
+    return await openSettings();
+  } catch {
+    return false;
+  }
+}
+
+const OPEN_FAILED = () => copyParam("notificationSettings.openFailed", "Change notifications for this app in your device or browser settings.");
+
+const svc = defineService<S, {
+  refresh: (s: S, arg?: unknown) => Promise<S & { _poll: PollDirective }>;
+  check: (s: S) => Promise<S>;
+  enable: (s: S) => Promise<S>;
+  openSettings: (s: S) => Promise<S>;
+}>("himiNotificationSettings", {
+  state: { ...viewFor("loading"), message: "" },
+  actions: {
+    // onAppear: read the status and (re-)arm the foreground-refresh poll.
+    refresh: async (s, arg) => {
+      stashCopy(arg);
+      return { ...s, ...viewFor(await readStatus()), message: "", _poll: POLL };
+    },
+    // One poll tick: idempotent — the status is just re-read.
+    check: async (s) => {
+      const status = await readStatus();
+      if (status === s.status) return s;
+      // Turned on in the OS settings while away: register the token for this session.
+      if (status === "granted") await requestPermission().catch(() => "granted");
+      return { ...s, ...viewFor(status), message: "" };
+    },
+    // Ask if the OS can still prompt; anything but a grant goes to the OS settings.
+    enable: async (s) => {
+      let status: Status;
+      try {
+        status = await requestPermission();
+      } catch {
+        status = await readStatus();
+      }
+      if (status === "granted") return { ...s, ...viewFor(status), message: "" };
+      const opened = await open();
+      return { ...s, ...viewFor(status), message: opened ? "" : OPEN_FAILED() };
+    },
+    openSettings: async (s) => {
+      // Coming back fires the poll, which repaints the status; nothing to do on success.
+      return { ...s, message: (await open()) ? "" : OPEN_FAILED() };
+    },
+  },
+});
+
+export { svc };

package/templates/brandy/tokens.json

@@ -109,11 +109,21 @@
       "weight": 700,
       "line": 1.2
     },
+    "title2": {
+      "size": 22,
+      "weight": 700,
+      "line": 1.22
+    },
     "body": {
       "size": 16,
       "weight": 400,
       "line": 1.5
     },
+    "footnote": {
+      "size": 14,
+      "weight": 500,
+      "line": 1.35
+    },
     "caption": {
       "size": 13,
       "weight": 400,

package/templates/community-club/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/community-club-owner/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/events-meetups/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/events-meetups-owner/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/gym-fitness/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/gym-fitness-owner/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/himi-chat/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/nonprofit-cause/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/nonprofit-cause-owner/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/owner-lite/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/podcast-creator/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/podcast-creator-owner/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/portfolio-creative/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/portfolio-creative-owner/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/restaurant/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/restaurant-owner/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/retail-store/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/retail-store-owner/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/yoga-studio/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override

package/templates/yoga-studio-owner/tier5-src/_shared/himi-copy.ts

@@ -1,4 +1,4 @@
-// Copy-as-configuration for WORKER-emitted strings (docs/designing-himi-screens.md
+// Copy-as-configuration for WORKER-emitted strings (`himi docs designing-himi-screens`,
 // §"Copy is configuration"): a worker never hardcodes user-facing copy — the
 // descriptor bakes the provisioned copy-pack overrides relevant to this worker
 // into its onAppear action params as a `copy` JSON object (key → override