@wix/himalaya-cli 0.1076.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",

package/guides/skill.md

@@ -49,6 +49,7 @@ A build takes most of an hour. An owner who sees nothing for that long assumes n
 - **Journal every postcard** with `himi progress "<what changed>" --step <n> --image <png>` when the installed CLI lists `progress` (`himi --help`). It keeps a copy of each image exactly as it was when you sent it, and a bare `himi progress` prints the journal with the current step — the quickest way back to your place. The CLI also journals the first picture of the home screen, every `himi test` crawl and every draft push by itself; your postcards are the ones that say why.
 - **Give them a board to leave open.** When the installed CLI lists `studio`, run `himi studio` once, right after that first picture, and tell the owner it is there (a current `himi init` has already made the board; this opens it). It opens a local page in their browser that fills itself in — every screen as it renders, the journey step and your latest postcard, each check as it runs — so they can watch between your messages. It is a view of your local work, not the preview of step 7.
 - **Let them click around while you work.** Once step 4's startup preflight says the app may boot locally, and when the installed CLI's `himi run` accepts `--watch`, keep `himi run --watch` running in the background: it serves the app on this machine, opens it in their browser (no `--browser` flag — that is a different mode, and `--watch` refuses it), and repaints that tab every time you save — and the board frames the same live app. Once the app is bound to their site, the watch preview shows that site's live data, fetched by their own browser as an anonymous visitor. It is a local preview of your working copy, never the owner-private preview, and a save that does not build leaves the last good version on screen while you fix it.
+- **Inside a coding agent, prefer the `himi_*` tools.** When your tool list has them (`himi init` configures the `himi` MCP server for Claude Code, Cursor, Codex and VS Code), call them instead of shelling out: `himi_render` hands you the PNG to show, and `himi_preview_start` returns the live preview's URL. Open that URL in your own built-in browser — Claude Code desktop: start the `himi-preview` launch configuration; Cursor: its Browser tool; Codex in the ChatGPT desktop app: its Browser; VS Code: the integrated browser — so the owner watches the app take shape beside the chat.
 - **Hand over the story too.** At the handover in step 7, when `himi --help` lists `himi studio reel` (an older CLI can have `studio` without it), run `himi studio reel` and offer the owner the file it writes: one self-contained page of their app taking shape, version by version, with your postcards. It shows how the app was built; it is never a substitute for the preview URL, and it carries the same sample-data captions the postcards did.
 
 ## Approval gates
@@ -113,9 +114,9 @@ If a gate is not implied (no credentials, no draft instruction, no site URL for
 
 **Keep the owner watching, headless too.** Whoever watches the board while you work, or reads the run afterwards, sees only what reached the journal. Do these in the session that builds the app — not at the end, and not in a later session — each one when `himi --help` lists the command:
 
-1. **The board opens at init.** `himi init` creates the build board (`.himi/studio/index.html`) and its `next[]` starts with this session's first steps: run them now. When the installed `init` prints no `board`, run `himi studio --no-open` once in the app folder.
-2. **Keep the live preview running.** Once journey step 4's startup preflight clears the app to boot locally, start `himi run --watch &` in the app folder and leave it up until the handover: it repaints on every save and serves the board at `<url>/__himi/studio/`.
-3. **Make the first picture right after init:** `himi render <homeScreenId> --png --device iphone`. The CLI journals that first look itself.
+1. **The board opens at init.** `himi init` creates the build board (`.himi/studio/index.html`) and its `next[]` starts with this session's first steps: run them now, in order: the first picture and its postcard, the consent preflight, then the live preview — for every template. The preflight costs nothing on an app that makes no startup request: if no worker or config can make a Wix or external request at boot, go straight on. When the installed `init` prints no `board`, run `himi studio --no-open` once in the app folder.
+2. **Make the first picture right after init:** `himi render <homeScreenId> --png --device iphone`. It is offline — it never calls Wix — so it needs no preflight. The CLI journals that first look itself.
+3. **Then keep the live preview running.** Only once the consent preflight (journey step 4) clears the app to boot locally, start `himi run --watch &` in the app folder and leave it up until the handover: it repaints on every save and serves the board at `<url>/__himi/studio/`.
 4. **A postcard with a picture at every journey step:** `himi progress "<what changed>" --step <n> --image .himi/shots/<screenId>.png`. `himi test` and `himi push --draft` journal their own results too; your postcards say what changed and why it matters.
 5. **At the handover, the making-of:** run `himi studio reel` and name the file it writes in your final report.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1076.0",
+  "version": "0.1077.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": [
@@ -34,6 +34,7 @@
     "test": "node ../../tools/ci/run-tests.mjs --package tools/himi-cli"
   },
   "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
     "@rive-app/canvas": "^2.21.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
@@ -45,7 +46,8 @@
     "react-dom": "^18.2.0",
     "tough-cookie": "^6.0.1",
     "typescript": "^5.6.3",
-    "wawoff2": "^2.0.1"
+    "wawoff2": "^2.0.1",
+    "zod": "^4.2.0"
   },
   "optionalDependencies": {
     "playwright": "^1.40.0",
@@ -65,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "3123c984ed5fe0542e00a7944eefd04225a131e1fcdd210717328c3b"
+  "falconPackageHash": "f05f26ed8fab307cde555efea47651788f996fd6d20bb908d209e946"
 }