From 52d5b98606aab23c56fe0a1859531ec402e9cfa5 Mon Sep 17 00:00:00 2001 From: Simon Clark Date: Mon, 13 Apr 2026 21:20:45 +0100 Subject: [PATCH] docs: deploy user pages to Web Assets, not plugin bundle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit User HTML dashboard pages should never go into a plugin's Contents/Resources/ folder — those are replaced on every plugin update. Update the skill's Phase 4 DEPLOY guidance and design-guidelines reference to point at Indigo's Web Assets/static/pages/ folder instead. Changes: - SKILL.md Phase 4: Option A is now "Indigo Web Assets folder" (persistent), Option C is "Shipping demo pages as part of a plugin" (plugin authors only, commit to git). Added explicit warning not to drop files into running plugin folders. - design-guidelines.md: rewrote Deployment Options section with Web Assets as primary target, removed plugin-bundle instructions. - Added Page Manifest section documenting the Domio plugin's /pages/ endpoint response shape including the new `source` field (plugin vs user) and the URL patterns each source maps to. - Bumped to 1.5.0 (feature-level docs update). Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- skills/html-pages/SKILL.md | 26 +++++-- .../references/design-guidelines.md | 73 ++++++++++++++++--- 4 files changed, 86 insertions(+), 17 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index fdbc260..f985702 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -8,7 +8,7 @@ "name": "indigo", "source": "./", "description": "Indigo home automation development toolkit \u2014 plugin development, API integration, and control page building", - "version": "1.4.3", + "version": "1.5.0", "repository": "https://github.com/simons-plugins/indigo-claude-plugin", "license": "MIT", "keywords": [ diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 977ec5d..0fef08c 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "indigo", - "version": "1.4.3", + "version": "1.5.0", "description": "Indigo home automation development toolkit \u2014 plugin development, API integration, and control page building", "repository": "https://github.com/simons-plugins/indigo-claude-plugin" } diff --git a/skills/html-pages/SKILL.md b/skills/html-pages/SKILL.md index 1c3f59f..2699887 100644 --- a/skills/html-pages/SKILL.md +++ b/skills/html-pages/SKILL.md @@ -138,13 +138,29 @@ Produce a single HTML file. Follow this template structure: ### Phase 4: DEPLOY -Offer deployment options based on how the page will be used: +**Critical:** Never deploy user pages into a plugin's `Contents/Resources/` directory. Plugin bundles are replaced on every update/reinstall, so any files dropped there will be wiped when the plugin next releases. Plugin folders are for plugin-shipped demo content only. -**Option A — Serve from an Indigo plugin** (recommended for app integration): -Copy to any plugin's `Contents/Resources/static/pages/` directory and restart the plugin via MCP. The page is then accessible at `https://{server}:8176/{bundleID}/static/pages/page.html`. Apps that support the `/pages/` manifest endpoint discover pages automatically. +Deployment options for user-owned pages: -**Option B — Browser-only**: -Save the HTML file anywhere. Open it directly in a browser — the page shows a connection form prompting for the Indigo server URL and API key. No plugin deployment needed. Good for quick testing or standalone dashboards on a wall-mounted tablet. +**Option A — Indigo Web Assets folder** (recommended for persistent pages): + +Copy to `{IndigoInstallFolder}/Web Assets/static/pages/`. This folder lives outside any plugin bundle and survives plugin updates, reinstalls, and Indigo upgrades. + +```bash +cp "page-name.html" "/Library/Application Support/Perceptive Automation/Indigo {VERSION}/Web Assets/static/pages/" +``` + +Access via: `https://{server}:8176/static/pages/page-name.html?api-key=KEY` + +If the Domio plugin (or any compatible plugin) is installed, it will scan this folder and expose the pages through its `/pages/` manifest endpoint — so pages appear automatically in the Domio iOS app's Pages tab, tagged with `source: "user"`. + +**Option B — Browser-only / standalone**: + +Save the HTML file anywhere (Desktop, project folder, etc.). Open it directly in a browser — the page shows a connection form prompting for the Indigo server URL and API key. No server deployment needed. Good for development, quick testing, or wall-mounted kiosk tablets opened from a local file path. + +**Option C — Shipping a demo page as part of a plugin** (plugin authors only): + +Only if you're building a plugin and want to ship a built-in sample page. Commit the HTML file to the plugin's git repo at `Contents/Resources/static/pages/` so it's included in every release build. **Never drop files into a running plugin's Resources folder at deploy time — they'll be wiped on the next update.** ## Device Classification diff --git a/skills/html-pages/references/design-guidelines.md b/skills/html-pages/references/design-guidelines.md index 9c871be..4ba2b4d 100644 --- a/skills/html-pages/references/design-guidelines.md +++ b/skills/html-pages/references/design-guidelines.md @@ -251,25 +251,78 @@ When developing pages, test at these minimum widths in browser dev tools: 4. **820px** — iPad portrait 5. **1180px** — iPad landscape +## Page Manifest (Domio Plugin) + +The Domio plugin exposes a manifest endpoint that lists all HTML pages available on the server, scanned from two locations: + +``` +GET /message/com.simons-plugins.domio/pages/ +``` + +**Response:** +```json +{ + "pages": [ + { + "id": "home-summary", + "name": "Home Summary", + "icon": "house.fill", + "description": "Device counts and active device controls", + "path": "home-summary.html", + "source": "plugin" + }, + { + "id": "dining-room", + "name": "Dining Room", + "icon": "fork.knife", + "description": "Dining room lights, heating and temperature chart", + "path": "dining-room.html", + "source": "user" + } + ] +} +``` + +**The `source` field** determines which URL serves the page: + +| Source | Location | URL pattern | +|--------|----------|-------------| +| `plugin` | `Domio.indigoPlugin/Contents/Resources/static/pages/` | `{base}/com.simons-plugins.domio/static/pages/{path}` | +| `user` | `Web Assets/static/pages/` | `{base}/static/pages/{path}` | + +Pages metadata is parsed from `` tags in each HTML file's ``: + +```html + + + +``` + ## Deployment Options -### Serve from an Indigo Plugin +### Indigo Web Assets Folder (recommended) + +User-owned pages belong in Indigo's `Web Assets/static/pages/` folder. This location lives outside any plugin bundle and survives plugin updates, reinstalls, and Indigo upgrades. -Copy to any plugin's `Contents/Resources/static/pages/` directory and restart: ```bash -cp "page.html" "/Volumes/Macintosh HD-1/Library/Application Support/Perceptive Automation/Indigo 2025.1/Plugins/{PluginName}.indigoPlugin/Contents/Resources/static/pages/" +cp "page.html" "/Library/Application Support/Perceptive Automation/Indigo {VERSION}/Web Assets/static/pages/" ``` -Then restart: `mcp__indigo__restart_plugin(plugin_id="{plugin.bundle.id}")` -Access via: `https://{server}:8176/{bundleID}/static/pages/page.html?api-key=KEY` +Access via: `https://{server}:8176/static/pages/page.html?api-key=KEY` + +The `?api-key=` query parameter authenticates with IWS for the page load. Inside the page, `indigo-api.js` reads the API key from the URL (or from `window.INDIGO_CONFIG` if injected by a compatible iOS app) and uses it as a Bearer token for REST API calls. + +**Discovery by the Domio app:** If the Domio plugin is installed, it automatically scans `Web Assets/static/pages/` and exposes the files via its `/message/com.simons-plugins.domio/pages/` manifest endpoint. The Domio iOS app reads this manifest and shows user pages in its Pages tab, tagged with `source: "user"`. + +### Warning: Do NOT deploy to a plugin's Resources folder -The `?api-key=` parameter authenticates with IWS and provides credentials to `indigo-api.js`. +Plugin bundles (`PluginName.indigoPlugin/Contents/Resources/`) are **wiped and replaced on every plugin update**. Any files you drop into a running plugin's `Resources/static/pages/` folder will be destroyed the next time the plugin is updated. This folder is only for content that's committed to the plugin's source repo and shipped in every release build. -### Browser-Only (No Plugin) +### Browser-Only (No Server Deployment) -Save the HTML file anywhere and open directly in a browser. Pages should detect when `INDIGO_CONFIG` is missing and show a connection form prompting for the server URL and API key. See `examples/active-devices.html` for the fallback pattern. +Save the HTML file anywhere (Desktop, local project, etc.) and open directly in a browser. Pages should detect when `INDIGO_CONFIG` is missing and show a connection form prompting for the server URL and API key. See `examples/active-devices.html` for the fallback pattern. -This approach works for: +Good for: - Quick testing during development -- Standalone dashboards on wall-mounted tablets +- Standalone dashboards on wall-mounted tablets opened from a local file - Users without any specific plugin installed