@wix/himalaya-cli 0.1075.0 → 0.1077.0

package/guides/component-reference.json

@@ -765,7 +765,7 @@
         "severity": "category",
         "note": "`action_sheet`/`context` render as an always-open inline list; `itemsPath` does not bind items."
       },
-      "propsSource": "export interface MenuProps {\n  anchor?: Component;\n  items?: MenuItem[];\n  style?: \"dropdown\" | \"context\" | \"action_sheet\";\n  /** \"$service:\" binding → MenuItem[]. */\n  itemsPath?: string;\n  /** The overlay traps focus and hides the rest of the tree from AT while\n   *  presented (iOS `accessibilityViewIsModal`, Android `isTraversalGroup`, ARIA\n   *  `aria-modal`). TRI-STATE: absent keeps today's NON-modal behaviour (flipping this\n   *  component's default to modal is #2900); `true` opts in, an explicit `false` stays out. */\n  modal?: boolean;\n}"
+      "propsSource": "export interface MenuProps {\n  anchor?: Component;\n  items?: MenuItem[];\n  style?: \"dropdown\" | \"context\" | \"action_sheet\";\n  /** \"$service:\" binding → MenuItem[]. */\n  itemsPath?: string;\n  /** The overlay traps focus and hides the rest of the tree from AT while\n   *  presented (iOS `accessibilityViewIsModal`, Android `isTraversalGroup`, ARIA\n   *  `aria-modal`). TRI-STATE: absent takes the Menu's default — MODAL,\n   *  from the one shared overlay default table — and an explicit `false` opts out. */\n  modal?: boolean;\n}"
     },
     {
       "name": "Tooltip",
@@ -790,21 +790,20 @@
       "name": "Popover",
       "category": "Overlays & menus",
       "propsType": "PopoverProps",
-      "bindings": [],
+      "bindings": [
+        "presentedPath"
+      ],
       "notImplemented": {
         "props": [
-          "edge",
-          "presented",
-          "presentedPath",
-          "onDismiss"
+          "edge"
         ],
         "platforms": [
           "ios"
         ],
         "severity": "category",
-        "note": "Not an overlay — renders always-expanded inline and is never dismissible."
+        "note": "Presentation follows `presented` / `presentedPath` (a gated popover shows its bubble only while presented, and is modal then), but the bubble is drawn in the screen's flow under its anchor, not floating over it: `edge` placement is not implemented. It closes when its gate closes, or on the VoiceOver escape gesture, which fires `onDismiss` so a worker can clear the gate."
       },
-      "propsSource": "export interface PopoverProps {\n  anchor?: Component;\n  content?: Component;\n  edge?: \"top\" | \"bottom\" | \"leading\" | \"trailing\" | \"auto\";\n  presented?: boolean;\n  presentedPath?: string;\n  onDismiss?: Action;\n  /** The overlay traps focus and hides the rest of the tree from AT while\n   *  presented (iOS `accessibilityViewIsModal`, Android `isTraversalGroup`, ARIA\n   *  `aria-modal`). TRI-STATE: absent keeps today's NON-modal behaviour (flipping this\n   *  component's default to modal is #2900); `true` opts in, an explicit `false` stays out. */\n  modal?: boolean;\n}"
+      "propsSource": "export interface PopoverProps {\n  anchor?: Component;\n  content?: Component;\n  edge?: \"top\" | \"bottom\" | \"leading\" | \"trailing\" | \"auto\";\n  presented?: boolean;\n  presentedPath?: string;\n  onDismiss?: Action;\n  /** The overlay traps focus and hides the rest of the tree from AT while\n   *  presented (iOS `accessibilityViewIsModal`, Android `isTraversalGroup`, ARIA\n   *  `aria-modal`). TRI-STATE: absent takes the Popover's default — MODAL,\n   *  from the one shared overlay default table — and an explicit `false` opts out. Applies to a\n   *  popover presented through `presented` / `presentedPath`; one with neither is an\n   *  inline callout, and never modal. */\n  modal?: boolean;\n}"
     },
     {
       "name": "Chip",

package/guides/component-reference.md

@@ -78,7 +78,7 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 | `BottomSheet` | Overlays & menus | — |
 | `Menu` | Overlays & menus | — |
 | `Tooltip` | Overlays & menus | — |
-| `Popover` | Overlays & menus | — |
+| `Popover` | Overlays & menus | `presentedPath` |
 | `Chip` | Chips & selection | `selectedPath`, `tokenPath` |
 | `ChipsInput` | Chips & selection | `valuesPath` |
 | `Section` | Structure & disclosure | — |
@@ -131,7 +131,7 @@ These props are accepted by the schema and pass validation, but the named platfo
 | `BottomSheet` | `detents`, `dismissible`, `onDismiss`, `presented`, `presentedPath`, `edge` | ios | category | Presentation is not implemented — BottomSheet renders as an always-visible inline surface, never a dismissible sheet. All six presentation props are dead. Use the WORKING alternative instead: present the content as its own screen with `presentation: "sheet"` on the navigating `Action` — that is a real dismissible sheet on every platform. Reach for BottomSheet only when an always-visible inline surface is what you actually want. |
 | `Menu` | `style`, `itemsPath` | ios | category | `action_sheet`/`context` render as an always-open inline list; `itemsPath` does not bind items. |
 | `Tooltip` | `edge`, `trigger`, `onDismiss` | ios | category | Not an overlay — renders always-expanded inline; `trigger` and dismissal are inert. |
-| `Popover` | `edge`, `presented`, `presentedPath`, `onDismiss` | ios | category | Not an overlay — renders always-expanded inline and is never dismissible. |
+| `Popover` | `edge` | ios | category | Presentation follows `presented` / `presentedPath` (a gated popover shows its bubble only while presented, and is modal then), but the bubble is drawn in the screen's flow under its anchor, not floating over it: `edge` placement is not implemented. It closes when its gate closes, or on the VoiceOver escape gesture, which fires `onDismiss` so a worker can clear the gate. |
 | `ChipsInput` | `onAdd` | ios | styling | `onAdd` never dispatches. |
 | `OtpInput` | `onChange`, `onComplete` | ios | styling | Neither callback dispatches. |
 | `Video` | `poster` | ios | styling | `poster` (pre-play frame) is not shown. |
@@ -1304,8 +1304,8 @@ export interface MenuProps {
   itemsPath?: string;
   /** The overlay traps focus and hides the rest of the tree from AT while
    *  presented (iOS `accessibilityViewIsModal`, Android `isTraversalGroup`, ARIA
-   *  `aria-modal`). TRI-STATE: absent keeps today's NON-modal behaviour (flipping this
-   *  component's default to modal is #2900); `true` opts in, an explicit `false` stays out. */
+   *  `aria-modal`). TRI-STATE: absent takes the Menu's default — MODAL,
+   *  from the one shared overlay default table — and an explicit `false` opts out. */
   modal?: boolean;
 }
 ```
@@ -1340,13 +1340,15 @@ export interface PopoverProps {
   onDismiss?: Action;
   /** The overlay traps focus and hides the rest of the tree from AT while
    *  presented (iOS `accessibilityViewIsModal`, Android `isTraversalGroup`, ARIA
-   *  `aria-modal`). TRI-STATE: absent keeps today's NON-modal behaviour (flipping this
-   *  component's default to modal is #2900); `true` opts in, an explicit `false` stays out. */
+   *  `aria-modal`). TRI-STATE: absent takes the Popover's default — MODAL,
+   *  from the one shared overlay default table — and an explicit `false` opts out. Applies to a
+   *  popover presented through `presented` / `presentedPath`; one with neither is an
+   *  inline callout, and never modal. */
   modal?: boolean;
 }
 ```
 
-> ⚠️ **Not implemented on ios:** `edge`, `presented`, `presentedPath`, `onDismiss` — Not an overlay — renders always-expanded inline and is never dismissible.
+> ⚠️ **Not implemented on ios:** `edge` — Presentation follows `presented` / `presentedPath` (a gated popover shows its bubble only while presented, and is modal then), but the bubble is drawn in the screen's flow under its anchor, not floating over it: `edge` placement is not implemented. It closes when its gate closes, or on the VoiceOver escape gesture, which fires `onDismiss` so a worker can clear the gate.
 
 ### Chips & selection
 

package/guides/headless-loop.md

@@ -77,10 +77,11 @@ The customer entry skill asks for a picture at every milestone (**Keep the owner
 loop already makes the pictures — send them, and journal each one:
 
 ```sh
-himi render home --png shots/home.png --device iphone                    # the first picture, right after init
-himi studio                                                              # the build board (init made it): opens it, keeps itself current
-himi run --watch &                                                       # live preview: repaints the open tab on every save
+himi render home --png shots/home.png --device iphone                    # the first picture, right after init (offline: no request)
 himi progress "Starting from branded-lite" --step implement --image shots/home.png
+himi studio                                                              # the build board (init made it): opens it, keeps itself current
+# consent preflight (skill: "Consent preflight before a template preview"): authorize or mock any Wix or external startup request; with none, go on
+himi run --watch &                                                       # live preview, after the preflight: repaints the open tab on every save
 himi render home --png shots/home-dark.png --device iphone --scheme dark
 himi progress "Your brand, light and dark" --step brand --image shots/home.png --image shots/home-dark.png
 himi progress                                                            # the journal: current step, elapsed, every postcard
@@ -88,8 +89,9 @@ himi studio reel                                                         # at ha
 ```
 
 `himi init` already writes the board (`.himi/studio/index.html`) without opening anything, and its
-`next[]` starts with this session's first steps — the live preview, the first picture, its postcard —
-so run those before anything else. `himi studio` writes the board and opens it; from then on every
+`next[]` starts with this session's first steps — the first picture and its postcard,
+the consent preflight, then the live preview — so run those, in order, before anything else. The preflight costs nothing on an app with
+no startup request; with one, authorize or mock it before the live preview boots the workers. `himi studio` writes the board and opens it; from then on every
 render, test, validate, push and progress entry refreshes it, and the page picks that up by itself — no
 server, nothing to re-run (`--no-open` prints its path instead, for SSH). The CLI journals three
 milestones by itself: the first PNG of the home screen, every completed `himi test` crawl, and every

package/guides/himi-mcp.md

@@ -0,0 +1,120 @@
+# himi in your coding agent (MCP)
+
+`himi mcp` runs the himi tools as a local **Model Context Protocol** server, so a coding agent —
+Claude Code, Cursor, Codex, VS Code — calls them as tools instead of remembering commands. Every
+tool runs the same `himi` command you would type, on the app folder already on your disk.
+
+## Set it up
+
+**Nothing to do for a new app.** `himi init` (and `himi agent-init` in an existing app) writes the
+server into each agent's config, beside any servers you already have — only the `himi` entry is
+touched:
+
+| Agent | File | Notes |
+| --- | --- | --- |
+| Claude Code | `.mcp.json` | Claude Code asks once before using a project server. |
+| Cursor | `.cursor/mcp.json` | |
+| VS Code (Copilot) | `.vscode/mcp.json` | |
+| Codex | `.codex/config.toml` | Written only if the file does not exist yet — an existing one is never edited; `himi agent-init` prints the command to add it instead. Codex reads project config only for trusted projects. |
+
+Every entry starts the server the same way:
+
+```bash
+npx -y @wix/himalaya-cli mcp
+```
+
+`npx` rather than a global `himi`, because desktop apps often do not see the shell `PATH` a global
+install lives on, and `npx` always runs the current CLI. The first start downloads it, so it can
+take a minute; later starts come from the npx cache.
+
+**Adding it by hand:**
+
+```bash
+claude mcp add himi -- npx -y @wix/himalaya-cli mcp
+```
+
+```bash
+codex mcp add himi -- npx -y @wix/himalaya-cli mcp
+```
+
+For Cursor, add `{"command": "npx", "args": ["-y", "@wix/himalaya-cli", "mcp"]}` under `mcpServers`
+in `~/.cursor/mcp.json`, or open this one-click install link:
+
+```text
+cursor://anysphere.cursor-deeplink/mcp/install?name=himi&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB3aXgvaGltYWxheWEtY2xpIiwibWNwIl19
+```
+
+### The Claude Code plugin
+
+The plugin bundles the himi skill with the MCP server, so a Claude Code session knows how to guide a
+business from an idea to a preview and has the tools to do it. In a Claude Code session:
+
+```text
+/plugin marketplace add https://apps.wix.com/_api/himi-serve/.claude-plugin/marketplace.json
+/plugin install himi@wix-himi
+```
+
+The marketplace hands the plugin out as a zip archive, which needs Claude Code 2.1.224 or later;
+an older Claude Code refuses the entry — update it first (`claude update`).
+
+To look at it before installing, `himi mcp plugin --out ./himi-plugin` writes the same plugin as a
+folder: `claude plugin validate ./himi-plugin` checks it, and `claude --plugin-dir ./himi-plugin`
+runs a session with it.
+
+## The tools
+
+| Tool | What it does |
+| --- | --- |
+| `himi_docs`, `himi_components`, `himi_sdk`, `himi_icons` | Read the guides and the component, SDK and icon references. Offline. |
+| `himi_init` | Create a new app (optionally from a template), with these configs already written. |
+| `himi_build` | Compile the app's worker bundles. |
+| `himi_validate` | Lint the app without publishing anything. |
+| `himi_test` | The behavioral crawl — every action each screen declares, against the app's mocked network. Never reaches live data. |
+| `himi_render` | Render one screen and return the PNG to the agent (needs Playwright's Chromium: `npx playwright install chromium`). |
+| `himi_progress` | Read or add to the build journal the owner follows. |
+| `himi_preview_start` / `_status` / `_stop` | The live preview — see below. |
+| `himi_whoami` | Which account the stored sign-in belongs to. |
+| `himi_push` | Publish a **draft**: private to the owner, viewable by preview link and in Himi Player, not live. |
+| `himi_share`, `himi_preview_links` | Share links for a published release. |
+
+Each tool acts on the agent's workspace folder unless it is given a `dir`.
+
+**What the tools will not do:** sign in, make a release live, build store binaries, touch secrets,
+write to a site's CMS, or create a Wix site. Those spend money, handle credentials, or change what
+real users see, so they stay commands a person runs. Publishing needs a sign-in first — run
+`himi login --browser` in a terminal; the server never asks for or handles a credential. A tool
+input that starts with `-` is refused, so nothing can be passed through to a flag no tool offers.
+
+## See the app inside your IDE
+
+`himi_preview_start` keeps a live preview running on your machine (`himi run --watch` — every save
+rebuilds and repaints) and returns its URL. Each app gets its own stable port between 5400 and 5499.
+
+| Agent | Where the preview shows |
+| --- | --- |
+| Claude Code (desktop app) | The browser pane beside the chat. With no preview running yet, starting the **`himi-preview`** launch configuration (`.claude/launch.json`, written by `himi init`) starts one on the same port — so use one or the other, not both. |
+| Cursor | The agent opens the URL with Cursor's Browser tool. |
+| Codex in the ChatGPT desktop app | Its built-in Browser. |
+| VS Code | The integrated browser. |
+| A terminal-only agent | `himi_render` PNGs — the agent shows you the picture. |
+
+Claude Code's browser pane shows the layout and repaints it on every save, but it blocks the frame
+a screen's worker runs in — so a tap that needs the worker does nothing there. To click through a
+worker-backed flow, open the same URL in your regular browser.
+
+When `himi studio` has written the build board, the preview also serves it at `/__himi/studio/` on
+the same origin, and `himi_preview_start` returns that URL as `board`.
+
+To see the app **on your phone**, `himi_push` publishes a draft and returns a link that opens it in
+Himi Player.
+
+## Good to know
+
+- **The MCP configs never leave your machine.** `.mcp.json`, `.cursor/mcp.json`,
+  `.vscode/mcp.json` and `.codex/config.toml` are left out of every source archive `himi push`
+  uploads, because they usually list your other servers and their keys. The rest of `.cursor/`
+  and `.vscode/` (rules, settings) is archived as before.
+- **One command at a time.** The server runs tool calls one after another in a single process; an
+  agent that asks for two at once gets them in order.
+- **It never updates itself.** A server's output is its conversation with the agent; `npx` picks up
+  new CLI versions the next time the agent starts it.

package/guides/index.json

@@ -52,6 +52,12 @@
       "category": "CLI & Loop",
       "file": "headless-loop.md"
     },
+    {
+      "id": "himi-mcp",
+      "title": "himi in your coding agent (MCP)",
+      "category": "CLI & Loop",
+      "file": "himi-mcp.md"
+    },
     {
       "id": "templates",
       "title": "Starter templates — list, scaffold, publish",