PowerPoint add-in (task pane)
==============================

Connect your domain (recommended path)
1. At your DNS host (where you bought the domain), add an **A record**: name = `@` or `charts` (subdomain), value = your server’s public IPv4 (e.g. Hetzner VM IP). TTL300–3600. Wait until `ping your.hostname` resolves to that IP.
2. On the server, open ports **80** and **443** (Hetzner firewall + `sudo ufw allow 'Nginx Full'` if ufw is on).
3. From the repo on your laptop, copy `deploy/https-letsencrypt.sh` to the server and run it **on the server** with sudo (see comments at top of that file): set `DOMAIN` and `SSL_EMAIL`. Certbot will obtain a Let’s Encrypt certificate and configure nginx for HTTPS + HTTP→HTTPS redirect.
4. Copy `apps/office-addin/manifest.hetzner.https.example.xml` to `manifest.hetzner.https.xml`, replace **YOUR_DOMAIN** with the same hostname (no `https://` in the replacement text). Deploy/rsync the site and sideload **that** manifest (Office requires https:// URLs).

What’s included
- manifest.local.xml — dev sideloading (HTTPS localhost URLs on port 8080).
- manifest.xml — template for production: replace every YOUR_DEPLOYMENT_ORIGIN with your real SaaS origin (HTTPS, no trailing slash), e.g. https://app.example.com
- taskpane-instructions.html — **default task pane** (short hint: use the ribbon; chart tools run in **dialog** windows).
- taskpane.html, taskpane-likert.html, … — optional iframe shells (e.g. testing); production ribbon uses **ExecuteFunction** → `open*Dialog`, not ShowTaskpane.
- commands.html, ribbon-commands.js, share-link-dialog.html — ribbon + dialogs.
- assets/ — PNG icons referenced by the manifest.

Sideload with office-addin-debugging (recommended; non-local server)
- Microsoft guide: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/test-debug-non-local-server
- Prefer current **Node LTS** from nodejs.org (>=20.6 avoids dependency engine warnings on some packages).
- If `npm run addin:start` crashes with `ERR_REQUIRE_ESM` / `strip-bom`: run `npm install` again from repo root (package.json pins `strip-bom@4` via `overrides`).
- From the repository root (after `npm install`):
  - Staging URLs must already match your server inside `apps/office-addin/manifest.hetzner.xml` (edit the host if it changed).
  - `npm run addin:start` — registers the add-in and opens/sideloads it for PowerPoint (desktop).
  - `npm run addin:stop` — removes registration when you are done (always stop after a session; closing Office alone may leave stale registration).
- Per-app folder scripts (`apps/sankey`, `apps/snake-charts`, …): `npm run addin:start:local` still points at the same central manifest under `apps/office-addin/`.

Manual upload (alternative)
1. From the repository root: python3 -m http.server 8080
2. If the client rejects http://localhost, use HTTPS on 8080 (e.g. mkcert + a small TLS static server) and update manifest.local.xml URLs to https://localhost:8080.
3. PowerPoint → Insert → Add-ins → My Add-ins → Upload My Add-in → choose `apps/office-addin/manifest.local.xml`
4. Open the add-in; build a chart, then Insert into slide (PNG at the cursor / selection).

SaaS / production
- Host the whole site (`apps/**`, `apps/office-addin/**`, `packages/**`, etc.) on HTTPS.
- Ship a copy of manifest.xml with real URLs; distribute via Microsoft 365 admin center (centralized deployment) or Microsoft AppSource after certification.
- “Seamless” for enterprises usually means: SSO (Microsoft Entra ID), optional backend to sync projects instead of localStorage, and org-wide deployment so users don’t sideload manually.

Hetzner server (current static deploy)
- After rsync from repo root, chart apps live under `apps/<tool>/`; the **single** PowerPoint add-in is **`/apps/office-addin/`** (not under each tool). Legacy `/office-addin/` and `/apps/sankey/office-addin/` URLs redirect (see `deploy/nginx-static-site.example.conf`).
- Use manifest URLs like https://symviora.de/apps/office-addin/manifest.hetzner.xml — or upload that file from the repo after deploy.
- Download landing page (instructions + manifest button): https://symviora.de/download/ — nginx: `location = /download { return 301 /download/; }` (see deploy/nginx-static-site.example.conf).
- Short auto-download helper: https://symviora.de/apps/office-addin/m.html (Complex Charts manifest).

Old “Sankey solo” add-in still in PowerPoint
---------------------------------------------
That manifest was removed from this repo. Office **keeps** any add-in you already sideloaded until you remove it manually (Insert → Add-ins / Options → Add-ins, or admin center for centralized deployment). Uninstall the legacy entry, then use only **Complex Charts** (`apps/office-addin/manifest*.xml`).
- nginx: redirects for old `/office-addin/` and `/apps/sankey/office-addin/` paths (see `deploy/nginx-static-site.example.conf`).

“Unsupported URL in add-in” (or similar)
- Cause: Office does not allow http:// for the add-in’s SourceLocation / icon URLs. Your IP-only site must be reachable as https://YOUR_DOMAIN with a real certificate (not self-signed for most clients).
- Fix: Point a DNS name at the server, run Let’s Encrypt (e.g. certbot --nginx -d YOUR_DOMAIN), then use a manifest where every URL is https://YOUR_DOMAIN/... — start from `apps/office-addin/manifest.hetzner.https.example.xml` (replace YOUR_DOMAIN), deploy it, sideload that file.

If PowerPoint says the XML is “not a valid Office add-in”
- HTTPS: Many builds require https:// for IconUrl, HighResolutionIconUrl, SupportUrl, and SourceLocation. Plain http:// often fails validation. Fix: serve the site over TLS (hostname + certbot/Let’s Encrypt) and use a copy of the manifest with every URL switched to https://YOUR_HOST/...
- Wrong file on disk: Do not use “Save as Web Page” from the browser (that wraps content in HTML). Prefer: curl -fLo manifest.hetzner.xml 'https://symviora.de/apps/office-addin/manifest.hetzner.xml' or copy the file straight from the repo. The first line must be exactly: <?xml version="1.0" encoding="UTF-8"?>
- UTF-8 BOM: If you edited in Notepad on Windows, re-save as UTF-8 without BOM if problems persist.

Microsoft recommends HTTPS for all add-in URLs; HTTP may trigger security warnings or fail in some builds (especially Office on the web). For broad compatibility, put the same files behind HTTPS (domain + Let’s Encrypt or a reverse proxy) and duplicate the manifest with https:// origins.

Version baseline for this tree is recorded in ../VERSION (1.0.0 web MVP; add-in features ship in the same repo).