@wix/himalaya-cli 0.838.0 → 0.840.0

package/guides/cms-collections.md

@@ -84,8 +84,9 @@ An adopted `wixId` declaration is **optional for reads**. A worker may call
 read even when `config.ts` has no `cms` block; declaring it records the expected
 schema for humans and `himi validate`, but does not grant or enable that read.
 
-`himi cms query` labels every collection on the site `owned`, `adopted`, or
-`foreign`, so the blast radius is visible before you run anything.
+`himi cms query --all` labels every collection on the site `owned`, `adopted`, or
+`foreign`, so the blast radius is visible before you run anything. (Without `--all`
+it reads only the ids you declare — see [below](#himi-cms-query--read-only).)
 
 ### `site analyze --apply` adopts, it never claims
 
@@ -275,7 +276,8 @@ boots as — an unauthenticated visitor — rather than as one it has no way to
 export WIX_SITE_ID=<msid>          # or pass --site <msid> to every command
 
 himi validate                      # offline: prefix, field types, displayField, seed keys, permissions
-himi cms query                     # READ-ONLY: what exists, who owns it, where it drifts
+himi cms query --all               # READ-ONLY: what the SITE has, including collections you never declared
+himi cms query                     # READ-ONLY: just your declared ids — what exists, who owns it, where it drifts
 himi cms create                    # provision the owned collections (idempotent)
 himi cms seed                      # fill the EMPTY owned collections from `seed:`
 himi push --draft                  # ship the content package; does NOT touch the site
@@ -287,13 +289,67 @@ publishing a release is exactly the surprise this design avoids.
 
 ### `himi cms query` — read-only
 
-Every collection on the site, labeled `owned` / `adopted` / `foreign`, with item
-counts for the declared ones and a `drift` list: declared-but-missing collections,
-missing fields, undeclared extra fields, and type mismatches. Run it first, and run
-it after `create` to confirm.
+**By default it reads only the ids you declared.** One targeted `GET` per declared
+collection, and the report says so with `siteScanned: false`. You get item counts and
+a `drift` list: declared-but-missing collections, missing fields, undeclared extra
+fields, and type mismatches. Run it first, and run it after `create` to confirm.
 
-Item counts are fetched only for *declared* collections — a site inventory doesn't
-fan out a query per foreign collection.
+The default never lists the site, so it cannot show you a collection you did not
+declare — **including one this app owns**. A leftover `himi_<app>_*` from a renamed
+declaration is labeled `owned` when the scan finds it, but only `--all` looks.
+
+The default stays off the site-wide list on purpose: that list is ~1MB and 46–60s on
+a real site (194 collections on one test site) and its socket gets reset mid-transfer,
+while the per-id reads it actually needs are ~3KB each.
+
+#### `--all` — scan the site and discover what to adopt
+
+`himi cms query --all --site <msid>` additionally lists the whole site and describes
+every **foreign** collection — one this app neither owns nor declares:
+
+```json
+{
+  "siteScanned": true,
+  "foreign": {
+    "count": 31,
+    "collections": [
+      { "id": "QaRecipes", "displayName": "Recipes", "readRole": "ANYONE", "itemCount": null,
+        "fields": [ { "key": "title", "type": "TEXT" }, { "key": "cookMinutes", "type": "NUMBER" } ] }
+    ],
+    "truncated": 6
+  }
+}
+```
+
+That is enough to write the adopted declaration without a second call: `wixId` is the
+`id`, and the `fields` carry the keys **and** the types a declaration must mirror (Wix
+cannot retype a field in place, so a wrong type is a refusal, not a warning). A field
+with no `type` is one the site did not report a type for — read that collection directly
+before declaring it, rather than guessing; the scan will not invent one for you.
+
+- **It works with no `cms` block at all.** Discovering what to declare is precisely the
+  case where nothing is declared yet, so `--all` is the one flag for which a missing
+  `cms` block is *not* "nothing to do".
+- **Foreign collections are never item-counted** (`itemCount: null`). A row count is one
+  query each, and fanning that across a whole site is the cost this scan must not pay.
+  Declare or adopt the collection and the count arrives with the next `himi cms query`.
+- **Only the first 25 are described.** `foreign.count` is how many the scan listed and
+  `foreign.truncated` says how many of those went undescribed, so a short list is never
+  mistaken for a short site. For the full per-collection picture — field types,
+  read/write roles and sample rows — use
+  [`himi site analyze --site <msid>`](wix-business-context.md).
+- **`foreign.count` is not a site census.** `GET /data/v2/collections` is paged and this
+  scan reads one page. When Wix reports a total larger than that page,
+  `unlistedCollections` says how many the listing left out; when Wix reports no total,
+  neither field can tell you, so treat `foreign.count` as "foreign collections in what we
+  listed" and use `site analyze` if you need certainty about a very large site.
+
+**The scan is owner-scoped, and there is no tokenless alternative.** It needs
+`--site <msid>` (or `WIX_SITE_ID`) and owner auth via `wix token`, because enumerating
+collections is `GET /data/v2/collections`, which requires the *Manage Data
+Collections* scope. A visitor/anonymous token can read the **items** of an
+`ANYONE`-read collection whose id you already have, but it can never list collections —
+so no CLI work can make the tokenless path discover them.
 
 ### `himi cms create` — additive and idempotent
 

package/guides/component-reference.json

@@ -101,7 +101,7 @@
       "bindings": [
         "text"
       ],
-      "propsSource": "export type TextProps = TextContent & {\n  style?: TokenName;\n  /** Foreground color token (default \"textPrimary\"). */\n  color?: TokenName;\n  /** Tail-truncate after N lines (absent = unlimited). */\n  maxLines?: number;\n  /** Render `text` as a constrained Markdown subset. */\n  markdown?: boolean;\n  /** Capability enrichments. */\n  textAlign?: \"leading\" | \"center\" | \"trailing\" | \"justify\";\n  /** Base writing direction. \"auto\" (or \"rtl\") makes a bidi paragraph resolve +\n   *  align by its own strong-directional content (Hebrew/Arabic → right-aligned,\n   *  RTL layout), matching per-message direction in chat bubbles. Absent/\"ltr\" =\n   *  the current left-to-right behavior. Both renderers honor it (parity). */\n  textDirection?: \"auto\" | \"ltr\" | \"rtl\";\n  decoration?: \"underline\" | \"strikethrough\";\n  lineSpacing?: number;\n  /** Per-item gate (usually an `$item.` field pre-substituted per row): when it\n   *  resolves empty, the text collapses to zero size instead of taking layout. */\n  collapseWhenEmpty?: boolean;\n  /** Motion grammar (Batch 1, item 4) — count-up tween for a numeric value on\n   *  change; non-numeric values render instantly. Gated by reduced motion. */\n  animateValue?: boolean;\n  /** Motion grammar — reveal the (post-substitution literal) text word-by-word,\n   *  once per distinct content, like a chat assistant \"typing\" its reply. Each\n   *  content animates a single time (progress is remembered), so list re-renders\n   *  and scrolls don't restart it. Gated by reduced motion (snaps to full).\n   *  Both renderers honor it (parity). Default nil/false. */\n  animateReveal?: boolean;\n};"
+      "propsSource": "export type TextProps = TextContent & {\n  style?: TokenName;\n  /** Foreground color token (default \"textPrimary\"). */\n  color?: TokenName;\n  /** Tail-truncate after N lines (absent = unlimited). */\n  maxLines?: number;\n  /** Lever D — a live time value (countdown/relative) the OS ticks with no refresh.\n   *  When present it OVERRIDES `text`. Widget-safe render only. */\n  timeRef?: WidgetTimeRef;\n  /** Render `text` as a constrained Markdown subset. */\n  markdown?: boolean;\n  /** Capability enrichments. */\n  textAlign?: \"leading\" | \"center\" | \"trailing\" | \"justify\";\n  /** Base writing direction. \"auto\" (or \"rtl\") makes a bidi paragraph resolve +\n   *  align by its own strong-directional content (Hebrew/Arabic → right-aligned,\n   *  RTL layout), matching per-message direction in chat bubbles. Absent/\"ltr\" =\n   *  the current left-to-right behavior. Both renderers honor it (parity). */\n  textDirection?: \"auto\" | \"ltr\" | \"rtl\";\n  decoration?: \"underline\" | \"strikethrough\";\n  lineSpacing?: number;\n  /** Per-item gate (usually an `$item.` field pre-substituted per row): when it\n   *  resolves empty, the text collapses to zero size instead of taking layout. */\n  collapseWhenEmpty?: boolean;\n  /** Motion grammar (Batch 1, item 4) — count-up tween for a numeric value on\n   *  change; non-numeric values render instantly. Gated by reduced motion. */\n  animateValue?: boolean;\n  /** Motion grammar — reveal the (post-substitution literal) text word-by-word,\n   *  once per distinct content, like a chat assistant \"typing\" its reply. Each\n   *  content animates a single time (progress is remembered), so list re-renders\n   *  and scrolls don't restart it. Gated by reduced motion (snaps to full).\n   *  Both renderers honor it (parity). Default nil/false. */\n  animateReveal?: boolean;\n};"
     },
     {
       "name": "Image",
@@ -388,7 +388,7 @@
       "bindings": [
         "avatarsPath"
       ],
-      "propsSource": "export interface AvatarStripProps {\n  /** `$service:` binding → a live array of `{imageUrl, initials}` (overrides `avatars`). */\n  avatarsPath?: string;\n  /** Literal fallback (Tier 0–4); ignored if `avatarsPath` resolves. */\n  avatars?: AvatarStripAvatar[];\n  /** Diameter in points (default 40). */\n  size?: number;\n  /** 0..1; shift = size * (1 - overlapRatio) (default 0.67). */\n  overlapRatio?: number;\n  /** Max avatars before overflow (default 4). */\n  maxVisible?: number;\n  /** Default true. */\n  showOverflow?: boolean;\n  /** Explicit overflow; if 0/absent computed from total. */\n  overflowCount?: number;\n  /** Literal caption (or `$service:` upstream-resolved). */\n  caption?: string;\n  /** Fired when tapping any avatar. */\n  onTap?: Action;\n}"
+      "propsSource": "export interface AvatarStripProps {\n  /** `$service:` binding → a live array of `{imageUrl, initials}` (overrides `avatars`). */\n  avatarsPath?: string;\n  /** Literal fallback (Tier 0–4); ignored if `avatarsPath` resolves. */\n  avatars?: AvatarStripAvatar[];\n  /** Diameter in points (default 40). */\n  size?: number;\n  /** 0..1; shift = size * (1 - overlapRatio) (default 0.67). */\n  overlapRatio?: number;\n  /** Max avatars before overflow (default 4). */\n  maxVisible?: number;\n  /** Default true. */\n  showOverflow?: boolean;\n  /** Explicit overflow; if 0/absent computed from total. */\n  overflowCount?: number;\n  /** Literal caption (or `$service:` upstream-resolved). */\n  caption?: string;\n  /** Fired when tapping any avatar. */\n  onTap?: Action;\n  /** Gradient token painted as a ring around each avatar — the \"story\" ring.\n   *  Resolved through the gradient tokens, not the colour ones. */\n  ringGradient?: TokenName;\n}"
     },
     {
       "name": "Banner",
@@ -651,7 +651,7 @@
         "valuePath",
         "tintPath"
       ],
-      "propsSource": "export interface GaugeProps {\n  value?: number;\n  /** `$service:`/`$item.` binding → a live number (overrides `value`). */\n  valuePath?: string;\n  min?: number;\n  max?: number;\n  label?: string;\n  kind?: \"radial\" | \"linear\";\n  tint?: TokenName;\n  /** Motion grammar (Batch 1, item 4) — tween the fill on value change instead of\n   *  snapping; gated by reduced motion. Mirror of ProgressBarProps.animated. */\n  animated?: boolean;\n  /** #1055 — `$service:`/`$item.` binding resolving to a tint TOKEN NAME (overrides `tint`). Binding-aware. */\n  tintPath?: string;\n}"
+      "propsSource": "export interface GaugeProps {\n  value?: number;\n  /** `$service:`/`$item.` binding → a live number (overrides `value`). */\n  valuePath?: string;\n  min?: number;\n  max?: number;\n  label?: string;\n  kind?: \"radial\" | \"linear\";\n  tint?: TokenName;\n  /** Concentric multi-ring gauge, drawn outer→inner. When present it overrides the\n   *  single `value`/`valuePath` radial. */\n  rings?: GaugeRing[];\n  /** Motion grammar (Batch 1, item 4) — tween the fill on value change instead of\n   *  snapping; gated by reduced motion. Mirror of ProgressBarProps.animated. */\n  animated?: boolean;\n  /** #1055 — `$service:`/`$item.` binding resolving to a tint TOKEN NAME (overrides `tint`). Binding-aware. */\n  tintPath?: string;\n}"
     },
     {
       "name": "Rating",
@@ -887,6 +887,8 @@
     "Presentation": "export type Presentation =\n  | \"push\"\n  | \"sheet\"\n  | \"replace\"\n  | \"dismiss\"\n  | \"back\"\n  | \"full_screen\"\n  | \"alert\"\n  | \"snackbar\";",
     "FilterChip": "export interface FilterChip {\n  id: string;\n  label: string;\n  leadingIcon?: IconRef;\n  count?: number;\n}",
     "TabItem": "export interface TabItem {\n  id: string;\n  label: string;\n  badge?: string;\n}",
+    "GaugeRing": "export interface GaugeRing {\n  /** Fraction 0..1 for this ring. */\n  value?: number;\n  /** `$service:`/`$item.` binding → a live number (overrides `value`). */\n  valuePath?: string;\n  tint?: TokenName;\n}",
+    "WidgetTimeRef": "export interface WidgetTimeRef {\n  /** Epoch seconds the style counts from/to. */\n  at: number;\n  /** SwiftUI `Text.DateStyle` / Android time style (default \"timer\"). */\n  style?: \"timer\" | \"relative\" | \"date\" | \"time\" | \"offset\";\n}",
     "Border": "export interface Border {\n  width: number;\n  color: TokenRef;\n}"
   }
 }

package/guides/component-reference.md

@@ -167,7 +167,7 @@ So `border` nests an object and `boxShadow`/`backgroundGradient` nest strings. R
 element interface (printed below) rather than extrapolating from the level.
 
 - Modifier-level (`TokenRef` object): `modifiers.background`, `modifiers.shadow`, `modifiers.backgroundGradient`, `modifiers.appear`, `modifiers.material`, `modifiers.pressMotion`, `modifiers.border.color`.
-- Component-prop-level (bare `TokenName` string): `Card.background`, `Text.style`, `Text.color`, `Image.placeholder`, `Image.tint`, `Icon.tint`, `Toggle.trackOn`, `Toggle.trackOff`, `Toggle.thumb`, `Badge.token`, `Tag.token`, `ProgressBar.tint`, `ProgressBar.trackColor`, `ListItem.titleStyle`, `ListItem.subtitleStyle`, `ListItem.titleColor`, `ListItem.subtitleColor`, `ListItem.overlineColor`, `Slider.tint`, `ActivityIndicator.tint`, `Chip.token`, `Label.style`, `Label.color`, `Gauge.tint`, `Rating.color`, `Chart.color`, `DonutChart.color`, `VoiceNote.tint`, `Marquee.style`, `Marquee.color`, `Fab.tint`.
+- Component-prop-level (bare `TokenName` string): `Card.background`, `Text.style`, `Text.color`, `Image.placeholder`, `Image.tint`, `Icon.tint`, `Toggle.trackOn`, `Toggle.trackOff`, `Toggle.thumb`, `Badge.token`, `Tag.token`, `ProgressBar.tint`, `ProgressBar.trackColor`, `AvatarStrip.ringGradient`, `ListItem.titleStyle`, `ListItem.subtitleStyle`, `ListItem.titleColor`, `ListItem.subtitleColor`, `ListItem.overlineColor`, `Slider.tint`, `ActivityIndicator.tint`, `Chip.token`, `Label.style`, `Label.color`, `Gauge.tint`, `Rating.color`, `Chart.color`, `DonutChart.color`, `VoiceNote.tint`, `Marquee.style`, `Marquee.color`, `Fab.tint`.
 
 There is **no `modifiers.color` and no `modifiers.tint`** — a `tint` is always a component
 prop. Of the two nested slots spelled `color`, `modifiers.border.color` is a `TokenRef`
@@ -366,6 +366,9 @@ export type TextProps = TextContent & {
   color?: TokenName;
   /** Tail-truncate after N lines (absent = unlimited). */
   maxLines?: number;
+  /** Lever D — a live time value (countdown/relative) the OS ticks with no refresh.
+   *  When present it OVERRIDES `text`. Widget-safe render only. */
+  timeRef?: WidgetTimeRef;
   /** Render `text` as a constrained Markdown subset. */
   markdown?: boolean;
   /** Capability enrichments. */
@@ -915,6 +918,9 @@ export interface AvatarStripProps {
   caption?: string;
   /** Fired when tapping any avatar. */
   onTap?: Action;
+  /** Gradient token painted as a ring around each avatar — the "story" ring.
+   *  Resolved through the gradient tokens, not the colour ones. */
+  ringGradient?: TokenName;
 }
 ```
 
@@ -1265,6 +1271,9 @@ export interface GaugeProps {
   label?: string;
   kind?: "radial" | "linear";
   tint?: TokenName;
+  /** Concentric multi-ring gauge, drawn outer→inner. When present it overrides the
+   *  single `value`/`valuePath` radial. */
+  rings?: GaugeRing[];
   /** Motion grammar (Batch 1, item 4) — tween the fill on value change instead of
    *  snapping; gated by reduced motion. Mirror of ProgressBarProps.animated. */
   animated?: boolean;
@@ -1913,12 +1922,15 @@ export interface LogicBundleRef {
 }
 ```
 
-## Element shapes (list & tab items)
+## Element shapes (list & tab items, and other typed prop objects)
 
-A few props take an array of typed **element objects** rather than nested components:
-`FilterChips.chips` is a `FilterChip[]`, and `SegmentedControl.options` / `Tabs.tabs` are a
-`TabItem[]`. The prop blocks above name those arrays; here are the element interfaces themselves
-(each item's own fields — `id` is what an `onChange` reports back).
+A few props take a typed **object** rather than nested components. Some are arrays of them:
+`FilterChips.chips` is a `FilterChip[]`, `SegmentedControl.options` / `Tabs.tabs` are a
+`TabItem[]`, and `Gauge.rings` is a `GaugeRing[]` (concentric rings, drawn outer→inner).
+One is a single object: `Text.timeRef` is a `WidgetTimeRef`, the widget-safe live clock —
+note its `at` is REQUIRED and is in epoch SECONDS. The prop blocks above name these types;
+here are the interfaces themselves (for the arrays, each item's own fields — `id` is what an
+`onChange` reports back).
 
 ```ts
 export interface FilterChip {
@@ -1933,6 +1945,21 @@ export interface TabItem {
   label: string;
   badge?: string;
 }
+
+export interface GaugeRing {
+  /** Fraction 0..1 for this ring. */
+  value?: number;
+  /** `$service:`/`$item.` binding → a live number (overrides `value`). */
+  valuePath?: string;
+  tint?: TokenName;
+}
+
+export interface WidgetTimeRef {
+  /** Epoch seconds the style counts from/to. */
+  at: number;
+  /** SwiftUI `Text.DateStyle` / Android time style (default "timer"). */
+  style?: "timer" | "relative" | "date" | "time" | "offset";
+}
 ```
 
 ## Modifiers

package/guides/wix-site-to-himi-app.md

@@ -184,7 +184,9 @@ images stay as `static.wixstatic.com` URLs in descriptors — do not vendor
 
 ### 4. CMS, verticals, forms, pages
 
-- **CMS the site already has** — `himi cms query`, then **adopt** with `wixId` in
+- **CMS the site already has** — `himi cms query --all --site <msid>` (owner-scoped;
+  it is the only door that reveals a collection id you do not already know), then
+  **adopt** with `wixId` in
   `config.ts` (`himi docs cms-collections`). Read-only. Never seed or alter a
   collection you did not create. Create `himi_<appSlug>_*` only for storage the
   site does not have.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.838.0",
+  "version": "0.840.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": [
@@ -63,5 +63,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "9fd823cad2c263e2917b872794458e3c97e9ffc0040e182088a08fa5"
+  "falconPackageHash": "3cc7ad5aafc738871bc07293ce79f445509b78f308bb192a30fb8a3a"
 }