@wix/himalaya-cli 0.1462.0 → 0.1464.0

package/guides/component-reference.json

@@ -21,8 +21,7 @@
     "Video",
     "PdfView",
     "MediaPlayer",
-    "TimeGrid",
-    "Agenda"
+    "TimeGrid"
   ],
   "components": [
     {
@@ -1277,31 +1276,18 @@
       "category": "Cross-cutting & media",
       "propsType": "PdfViewProps",
       "bindings": [],
-      "notImplemented": [
-        {
-          "props": [
-            "showPageControls",
-            "startPage"
-          ],
-          "platforms": [
-            "android"
-          ],
-          "severity": "styling",
-          "note": "No page controls. `startPage` is ignored."
-        },
-        {
-          "props": [
-            "showPageControls",
-            "zoomable",
-            "allowShare"
-          ],
-          "platforms": [
-            "web"
-          ],
-          "severity": "styling",
-          "note": "No page controls. The browser PDF viewer ignores `zoomable` and `allowShare`."
-        }
-      ],
+      "notImplemented": {
+        "props": [
+          "showPageControls",
+          "zoomable",
+          "allowShare"
+        ],
+        "platforms": [
+          "web"
+        ],
+        "severity": "styling",
+        "note": "Interactive PDF.js canvas rendering honours the reader’s page, zoom and export controls. Static previews and PDF.js loading/rendering failures use a native browser-viewer fallback. In that fallback, hiding page or zoom controls is only a viewer hint and cannot reliably hide browser chrome; allowShare hides the reader’s export controls but cannot prevent browser save/print. These props are UI controls, not document access restrictions."
+      },
       "propsSource": "export interface PdfViewProps {\n  url?: string;\n  height?: number;\n  showPageControls?: boolean;\n  /** 1-based; 0/absent ⇒ page 1. */\n  startPage?: number;\n  zoomable?: boolean;\n  allowShare?: boolean;\n}"
     },
     {
@@ -1399,20 +1385,19 @@
       "category": "Rich vector & celebration (motion grammar Batch 4)",
       "propsType": "TimeGridProps",
       "bindings": [
+        "anchorDatePath",
         "eventsPath",
         "resourcesPath"
       ],
       "notImplemented": {
         "props": [
-          "anchorDatePath",
-          "onRangeChange",
           "onCreate"
         ],
         "platforms": [
           "android"
         ],
         "severity": "category",
-        "note": "`anchorDatePath` does not bind, and `onRangeChange` and `onCreate` never fire."
+        "note": "`onCreate` never fires."
       },
       "propsSource": "export interface TimeGridProps {\n  mode?: \"day\" | \"3day\" | \"week\";\n  anchorDate?: string;\n  anchorDatePath?: string;\n  events?: CalendarEvent[];\n  eventsPath?: string;\n  startHour?: number;\n  endHour?: number;\n  firstWeekday?: number;\n  showNowLine?: boolean;\n  onSelectEvent?: Action;\n  onRangeChange?: Action;\n  /** Per-event body, `$item.*`-substituted per event. Absent ⇒ the built-in block. */\n  eventTemplate?: Component;\n  /** RESOURCE lanes: staff, rooms, chairs, courts. Overlap packing already splits\n   *  concurrent events into ANONYMOUS sub-columns; lanes make a column MEAN\n   *  something. Single-day modes only — a week of resource columns is a 2-D grid\n   *  that does not fit a phone, so `mode: \"week\"` ignores them. */\n  resources?: TimeGridResource[];\n  resourcesPath?: string;\n  /** EDITING. Opt-in, default off, so no existing read-only\n   *  grid can regress into one that moves bookings when a user meant to scroll. */\n  editable?: boolean;\n  /** Snap grid in minutes (default 15). A drag landing on 10:07 is almost never\n   *  what anyone meant, and no scheduling system accepts it. */\n  snapMinutes?: number;\n  /** Moved or resized → args{id, start, end}. The component REPORTS; the worker\n   *  decides. An edit that must be rejected has to be able to fail. */\n  onEventChange?: Action;\n  /** Empty space long-pressed → args{start, end} for one `snapMinutes` slot. */\n  onCreate?: Action;\n  /** Labels for the non-drag equivalents. Drag is unreachable by VoiceOver,\n   *  TalkBack and keyboard, so these are how editing stays operable at all. */\n  moveActionLabel?: string;\n  resizeActionLabel?: string;\n}"
     },
@@ -1424,16 +1409,6 @@
         "eventsPath",
         "scrollToDatePath"
       ],
-      "notImplemented": {
-        "props": [
-          "stickyHeaders"
-        ],
-        "platforms": [
-          "android"
-        ],
-        "severity": "styling",
-        "note": "Day headers do not pin."
-      },
       "propsSource": "export interface AgendaProps {\n  events?: CalendarEvent[];\n  eventsPath?: string;\n  scrollToDate?: string;\n  /** Worker-driven jump target (a literal `scrollToDate` is frozen in the descriptor). */\n  scrollToDatePath?: string;\n  stickyHeaders?: boolean;\n  emptyText?: string;\n  onSelectEvent?: Action;\n  /** Per-event row body, `$item.*`-substituted per event. Closes the gap that made\n   *  `agendaList()` (the LazyList-backed PRESET, which takes a `rowTemplate`) more\n   *  expressive than this component. Absent ⇒ the built-in row. */\n  eventTemplate?: Component;\n  /** Newest-first. Absent/false ⇒ ascending. Applies to the day GROUPS and to the\n   *  events within each group. Without it a list whose default sort is \"Newest\"\n   *  (an owner's orders, recent activity) could not become an Agenda without\n   *  silently inverting itself — every arm sorted ascending unconditionally. */\n  descending?: boolean;\n}"
     }
   ],

package/guides/component-reference.md

@@ -111,17 +111,17 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 | `Lottie` | Rich vector & celebration (motion grammar Batch 4) | — |
 | `Rive` | Rich vector & celebration (motion grammar Batch 4) | — |
 | `MonthCalendar` | Rich vector & celebration (motion grammar Batch 4) | `selectedDatePath`, `decorationsPath`, `yearPath`, `monthPath`, `selectedStartDatePath`, `selectedEndDatePath` |
-| `TimeGrid` | Rich vector & celebration (motion grammar Batch 4) | `eventsPath`, `resourcesPath` |
+| `TimeGrid` | Rich vector & celebration (motion grammar Batch 4) | `anchorDatePath`, `eventsPath`, `resourcesPath` |
 | `Agenda` | Rich vector & celebration (motion grammar Batch 4) | `eventsPath`, `scrollToDatePath` |
 
 ## Not implemented (decoded but never read)
 
 These props are accepted by the schema and pass validation, but the named platform's renderer never reads them — they silently do nothing (no warning, no log). Prefer a prop NOT listed here, or drive the behaviour from a worker.
 
-**Scope: 19 of 86 components, all of them android / web / ios-only** — every other component/platform pair reads every prop it decodes. The list splits in two, and the halves mean different things:
+**Scope: 18 of 86 components, all of them android / web / ios-only** — every other component/platform pair reads every prop it decodes. The list splits in two, and the halves mean different things:
 
 - **`category` (7: `Menu`, `Tooltip`, `Popover`, `ChipsInput`, `OtpInput`, `MediaPlayer`, `TimeGrid`)** — the prop changes the component's *kind*. These genuinely are **not implemented**: an overlay renders always-visible inline, so the component does not do the job its name implies. Check the row's note for a working alternative.
-- **`styling` (12: `Text`, `Icon`, `Carousel`, `Pager`, `Snackbar`, `WebView`, `Slider`, `SelectionControl`, `ActivityIndicator`, `Video`, `PdfView`, `Agenda`)** — the component itself **works**; only the listed prop is inert. `Slider` on iOS is a working slider whose `debounceMs` does not throttle — not a broken `Slider`. Use the component; just do not depend on that one prop.
+- **`styling` (11: `Text`, `Icon`, `Carousel`, `Pager`, `Snackbar`, `WebView`, `Slider`, `SelectionControl`, `ActivityIndicator`, `Video`, `PdfView`)** — the component itself **works**; only the listed prop is inert. `Slider` on iOS is a working slider whose `debounceMs` does not throttle — not a broken `Slider`. Use the component; just do not depend on that one prop.
 
 | Component | Unread props | Platform | Kind | Note |
 |---|---|---|---|---|
@@ -141,13 +141,11 @@ These props are accepted by the schema and pass validation, but the named platfo
 | `ChipsInput` | `onAdd` | ios, android | category | `onAdd` never dispatches. |
 | `OtpInput` | `onComplete`, `onChange` | ios, android, web | category | Neither `onChange` nor `onComplete` dispatches. |
 | `Video` | `poster` | ios | styling | `poster` is not shown. |
-| `PdfView` | `showPageControls`, `startPage` | android | styling | No page controls. `startPage` is ignored. |
-| `PdfView` | `showPageControls`, `zoomable`, `allowShare` | web | styling | No page controls. The browser PDF viewer ignores `zoomable` and `allowShare`. |
+| `PdfView` | `showPageControls`, `zoomable`, `allowShare` | web | styling | Interactive PDF.js canvas rendering honours the reader’s page, zoom and export controls. Static previews and PDF.js loading/rendering failures use a native browser-viewer fallback. In that fallback, hiding page or zoom controls is only a viewer hint and cannot reliably hide browser chrome; allowShare hides the reader’s export controls but cannot prevent browser save/print. These props are UI controls, not document access restrictions. |
 | `MediaPlayer` | `autoplayVisibilityThreshold`, `preload`, `playbackRates`, `showQueue`, `showChapters`, `showTranscript` | ios | category | `autoplayVisibilityThreshold` is ignored (whenVisible = once on appear). `preload` is ignored. `playbackRates` is ignored, and the queue/chapters/transcript panels never render. |
 | `MediaPlayer` | `externalPlayback`, `appearance`, `allowCellular`, `preload`, `playbackRates`, `showQueue`, `showChapters`, `showTranscript` | android | category | `externalPlayback` is forced off. `appearance` is ignored. `allowCellular` is ignored. `preload` is ignored. `playbackRates` is ignored, and the queue/chapters/transcript panels never render. |
 | `MediaPlayer` | `allowCellular`, `forwardSkipSeconds`, `backwardSkipSeconds`, `playbackRates`, `showQueue`, `showChapters`, `showTranscript` | web | category | `allowCellular` is ignored. Skip buttons ignore `forwardSkipSeconds`/`backwardSkipSeconds`. `playbackRates` is ignored, and the queue/chapters/transcript panels never render. |
-| `TimeGrid` | `anchorDatePath`, `onRangeChange`, `onCreate` | android | category | `anchorDatePath` does not bind, and `onRangeChange` and `onCreate` never fire. |
-| `Agenda` | `stickyHeaders` | android | styling | Day headers do not pin. |
+| `TimeGrid` | `onCreate` | android | category | `onCreate` never fires. |
 
 ## Token slots: `TokenRef` object vs bare `TokenName` string
 
@@ -2090,9 +2088,7 @@ export interface PdfViewProps {
 }
 ```
 
-> ⚠️ **Implemented, but these props are inert on android:** `showPageControls`, `startPage` — No page controls. `startPage` is ignored.
-
-> ⚠️ **Implemented, but these props are inert on web:** `showPageControls`, `zoomable`, `allowShare` — No page controls. The browser PDF viewer ignores `zoomable` and `allowShare`.
+> ⚠️ **Implemented, but these props are inert on web:** `showPageControls`, `zoomable`, `allowShare` — Interactive PDF.js canvas rendering honours the reader’s page, zoom and export controls. Static previews and PDF.js loading/rendering failures use a native browser-viewer fallback. In that fallback, hiding page or zoom controls is only a viewer hint and cannot reliably hide browser chrome; allowShare hides the reader’s export controls but cannot prevent browser save/print. These props are UI controls, not document access restrictions.
 
 #### MediaPlayer
 
@@ -2265,7 +2261,7 @@ export interface TimeGridProps {
 }
 ```
 
-> ⚠️ **Not implemented on android:** `anchorDatePath`, `onRangeChange`, `onCreate` — `anchorDatePath` does not bind, and `onRangeChange` and `onCreate` never fire.
+> ⚠️ **Not implemented on android:** `onCreate` — `onCreate` never fires.
 
 #### Agenda
 
@@ -2291,8 +2287,6 @@ export interface AgendaProps {
 }
 ```
 
-> ⚠️ **Implemented, but these props are inert on android:** `stickyHeaders` — Day headers do not pin.
-
 ## Screen descriptor shape
 
 ```ts

package/guides/sdk-reference.json

@@ -70,6 +70,12 @@
         "jsdoc": "/**\n * Repeating-refresh directive. An action may return its new state with a transient\n * `_poll` field; the runtime strips it and asks the host to invoke `action` every\n * `intervalMs`. The worker has no timers — this is the only way it refreshes on a\n * cadence. Each fire runs through the normal reducer→render loop.\n *\n * The polled action MUST be idempotent (merge by id, never append): overlapping\n * ticks, a retried query and a cold-start refetch all have to converge on one row.\n */",
         "decl": "export interface PollDirective {\n  /** Stable id; a new directive with the same id REPLACES the prior timer. */\n  id: string;\n  /** Requested period. Native clamps to a 1000ms floor and logs the clamp. */\n  intervalMs: number;\n  /** \"<service>.<action>\" — invoked on every fire. */\n  action: string;\n  /** Fire once immediately instead of waiting out the first interval. */\n  immediate?: boolean;\n}"
       },
+      {
+        "name": "PollStopDirective",
+        "kind": "interface",
+        "jsdoc": "/**\n * Stops the poll `id`. Return it as `_poll` — typically from the polled\n * action itself, on the tick that sees the job finish: the host cancels `id` and does\n * not re-arm it. Stopping an id that is not polling is a no-op. A stop never starts or\n * replaces a poll, so it carries nothing else. Type a state's field as\n * `_poll?: PollDirective | PollStopDirective` to allow both.\n */",
+        "decl": "export interface PollStopDirective {\n  /** The id the poll was started under. */\n  id: string;\n  /** Must be the boolean `true`. */\n  stop: true;\n}"
+      },
       {
         "name": "encodeSubtree",
         "kind": "function",

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

@@ -565,10 +565,24 @@ What the host guarantees, on every surface:
 
 Two things to know before you reach for it:
 
-- **`_poll` has no stop form.** The directive can start and replace a poll, not end one.
-  Worker teardown is the only stop; navigating away from a pooled screen pauses the poll
-  rather than ending it. Pick a cadence you would be comfortable running on several
-  screens at once.
+- **Stop it when the work is done.** Return `_poll: { id, stop: true }` to cancel the poll
+  `id` — typically from the polled action itself, on the tick that sees the job finish:
+
+  ```ts
+  checkJob: async (s) => {
+    const job = await fetchJob(s.jobId);
+    return job.status === "done"
+      ? { ...s, job, _poll: { id: `job-${s.jobId}`, stop: true } }  // ends the poll
+      : { ...s, job };                                              // keeps polling
+  },
+  ```
+
+  The stop is stripped from state like any `_poll`. The tick that returns it finishes
+  normally and the host does not re-arm it. Stopping an id that is not polling is a no-op.
+  `stop` must be the boolean `true`. A stop never starts or replaces a poll, so other
+  fields on it (`intervalMs`, `action`, `immediate`) are ignored; leave them off. Without
+  a stop, worker teardown ends the poll, and leaving a pooled screen only pauses it. So
+  pick a cadence you would be comfortable running on several screens at once.
 - **Emit it from the action that runs on every entry**, not only from a first-open path.
   Restored worker state re-paints data but arms no timer, so a poll armed only by `open`
   restores into a screen that *looks* live and never refreshes.
@@ -583,7 +597,7 @@ invisible: the timer arms, fires forever, and does nothing.
 > state. And contrast with `_stream` ([RFC 0040](../core/schema/RFC/0040-tier5-streaming-bridge.md)):
 > `_stream` is for data the server pushes, `_poll` for data it does not.
 
-Full specification, the eight host semantics, the per-surface background signal, and the
+Full specification, the nine host semantics, the per-surface background signal, and the
 accepted limitations: [RFC 0040 § Amendment — the `_poll` directive](../core/schema/RFC/0040-tier5-streaming-bridge.md#amendment-2026-08-16--the-_poll-directive).
 
 ### Navigate to a detail screen (tabs + push)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1462.0",
+  "version": "0.1464.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "d40739f8a350f4cf15d4ea5e3677bd4b4b29a3c9311c8e80752b9d3b"
+  "falconPackageHash": "3919cfeb6cc26ef641fd143cfe0395aad1e15aea098655650caa396b"
 }