Add portion controls and improve recipe display

README.md

@@ -1,13 +1,12 @@
 # MMM-NextcloudCookbook
 
 A MagicMirror module that displays recipes from a read-only Nextcloud public
-share. It includes a phone-friendly control page for choosing a recipe and
-entering or leaving recipe mode.
+share. It includes a phone-friendly control page for choosing a recipe,
+adjusting its number of portions, and entering or leaving recipe mode.
 
-The Nextcloud share URL is read only by `node_helper.js` from
-`SECRET_NEXTCLOUD_COOKBOOK_SHARE_URL`. An optional protected-share password can
-be supplied as `SECRET_NEXTCLOUD_COOKBOOK_SHARE_PASSWORD`. Neither value is sent
-to the MagicMirror browser or control page.
+Create a public share for the folder configured as your Nextcloud Cookbook
+recipe directory. Read-only permission is sufficient. Copy the public share
+link; it should look like `https://cloud.example.test/s/SHARE_TOKEN`.
 
 ## MagicMirror configuration
 
@@ -16,11 +15,32 @@ to the MagicMirror browser or control page.
   module: "MMM-NextcloudCookbook",
   position: "fullscreen_above",
   config: {
+    shareUrl: "https://cloud.example.test/s/SHARE_TOKEN",
     controlPath: "/MMM-NextcloudCookbook/control"
   }
 }
 ```
 
+For a password-protected public share, add `sharePassword`:
+
+```js
+config: {
+  shareUrl: "https://cloud.example.test/s/SHARE_TOKEN",
+  sharePassword: "PUBLIC_SHARE_PASSWORD"
+}
+```
+
+MagicMirror sends module configuration to its browser clients. A public-share
+URL is normally appropriate there because the token is already a scoped share
+credential, but do not put a Nextcloud account password or app password in this
+configuration.
+
+For deployments that keep even the share token out of browser-visible
+configuration, set `SECRET_NEXTCLOUD_COOKBOOK_SHARE_URL` and, if needed,
+`SECRET_NEXTCLOUD_COOKBOOK_SHARE_PASSWORD` in the MagicMirror process
+environment and omit the corresponding config values. Environment values take
+precedence over module configuration and are read only by `node_helper.js`.
+
 Open the controller at:
 
 ```text
@@ -31,6 +51,37 @@ The share must contain Nextcloud Cookbook recipe folders with a `recipe.json`
 file in each folder. The module uses Nextcloud's token-scoped public DAV API;
 protected shares authenticate as Nextcloud's `anonymous` public-share user.
 
+## Data-source decision: public WebDAV instead of the Cookbook API
+
+Nextcloud Cookbook provides a REST API, but its external API requires
+Nextcloud user credentials on every request. A read-only public-share token
+cannot authenticate to that API.
+
+This module intentionally reads the recipe files through Nextcloud's public
+WebDAV interface because its job is limited to listing and displaying recipes.
+That gives the mirror a narrower security boundary:
+
+- access is scoped to the shared recipe folder;
+- the share can be read-only;
+- the mirror receives no general Nextcloud account credential; and
+- the module cannot create, update, or delete recipes.
+
+Cookbook stores recipes as ordinary `recipe.json` files, so WebDAV provides the
+data required by this read-only display without relying on Cookbook's database
+index. Index synchronization and reindexing matter when an external tool writes
+recipe files; this module does not write them.
+
+The Cookbook API would become preferable if the module later needs
+Cookbook-native search, categories, keywords, imports, or recipe editing. In
+that case, use a dedicated Nextcloud service user with read-only access to the
+recipe folder and a dedicated app password rather than credentials for a
+person's normal account.
+
+References:
+
+- [Cookbook API documentation](https://nextcloud.github.io/cookbook/dev/api/0.1.0/index.html)
+- [Cookbook user documentation](https://nextcloud.github.io/cookbook/user/)
+
 ## Development
 
 ```bash