pi-widget-host 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning.
 
+## [0.3.6] - 2026-08-22
+
+### Changed
+
+- Merge the 2026-08-22 managed OSS dependency and maintenance PR batch.
+
 ## [0.3.5] - 2026-08-04
 
 ### Changed
@@ -65,4 +71,3 @@ This project follows semantic versioning.
 ### Changed
 
 - Replaced template placeholders and removed template-only skill, prompt, and theme resources.
-

package/README.md

@@ -114,6 +114,7 @@ The built-in demo provider exists to prove the host loop first:
 |---|---|
 | `extensions/index.ts` | Pi extension entrypoint and `/widget-host:*` command registration |
 | `lib/` | config store, registry protocol, policy evaluation, and demo provider |
+| `docs/README.md` | documentation index for protocol, release, and maintenance docs |
 | `docs/protocol.md` | registry protocol reference for future provider packages |
 | `docs/provider-example.md` | minimal copy-paste provider publishing through the registry |
 | `docs/release.md` | Trusted Publishing release notes |

package/docs/README.md

@@ -0,0 +1,25 @@
+# Documentation index
+
+Entry point for `pi-widget-host` maintainer and provider-author docs.
+
+## Guides
+
+| Doc | Purpose |
+|---|---|
+| [`config.md`](config.md) | `HostConfig` field contract, defaults, and `normalizeConfig` coercion rules. |
+| [`protocol.md`](protocol.md) | Registry protocol reference (`globalThis`, required fields, tags, TTL). |
+| [`provider-example.md`](provider-example.md) | Minimal copy-paste provider that publishes through the registry. |
+| [`release.md`](release.md) | npm Trusted Publishing workflow and CI release automation. |
+
+## Maintenance context
+
+| Doc | Purpose |
+|---|---|
+| [ROADMAP.md](https://github.com/eiei114/pi-widget-host/blob/main/ROADMAP.md) | Living release status, priorities, and bounded maintenance seeds. |
+| [`npm-publish-run-2026-07-04.md`](npm-publish-run-2026-07-04.md) | Notes from the 2026-07-04 publish run (historical reference). |
+
+## Quick links
+
+- Package README: [`../README.md`](../README.md)
+- Contributing: [CONTRIBUTING.md](https://github.com/eiei114/pi-widget-host/blob/main/CONTRIBUTING.md)
+- Changelog: [`../CHANGELOG.md`](../CHANGELOG.md)

package/docs/config.md

@@ -0,0 +1,110 @@
+# Host config schema and normalization
+
+`pi-widget-host` persists host settings in a JSON file under the Pi agent directory. Every read and write path runs the payload through `normalizeConfig` in `lib/config.ts` so callers always receive a stable `HostConfig` shape.
+
+## Storage location
+
+| Item | Value |
+|---|---|
+| Default path | `~/.pi/agent/pi-widget-host-config.json` |
+| Override | Set `PI_WIDGET_HOST_AGENT_DIR` to use `<dir>/pi-widget-host-config.json` instead |
+
+If the file is missing, unreadable, or contains invalid JSON, `readHostConfig()` returns `createDefaultConfig()` without throwing.
+
+## `HostConfig` fields
+
+All fields are required on the normalized object. Unknown keys in stored JSON are ignored.
+
+| Field | Type | Default | `normalizeConfig` coercion |
+|---|---|---|---|
+| `schemaVersion` | `1` (literal) | `1` | Always rewritten to `1`. Any stored value is replaced. |
+| `setupComplete` | `boolean` | `false` | `true` only when the input value is strictly `true`; every other value becomes `false`. |
+| `demoProviderEnabled` | `boolean` | `false` | `true` only when the input value is strictly `true`; every other value becomes `false`. |
+| `presetId` | `string` | `"always-demo"` | Valid built-in preset ids are preserved. Invalid ids, non-string values, and strings that do not exactly match a built-in id (including whitespace-wrapped values such as `" focus-day "`) normalize to `"always-demo"`. |
+| `mutedProviderIds` | `string[]` | `[]` | When the input is an array, string elements with non-blank content (checked via `trim()`) are kept as written, including surrounding whitespace; duplicates removed, order preserved. Any non-array input becomes `[]`. |
+
+Built-in preset ids (from `lib/policy.ts`):
+
+- `always-demo` (default)
+- `focus-day`
+- `night-owl`
+
+## Normalization entry points
+
+| Function | Behavior |
+|---|---|
+| `createDefaultConfig()` | Returns a fresh default object without touching disk. |
+| `readHostConfig()` | Reads JSON from disk, parses it, then normalizes. On any I/O or parse failure, returns `createDefaultConfig()`. |
+| `writeHostConfig(config)` | Normalizes the input, writes pretty-printed JSON, returns the normalized value. |
+| `updateHostConfig(mutator)` | Reads current config, applies `mutator`, then writes through `writeHostConfig`. |
+
+## Non-object and partial payloads
+
+When the parsed JSON root is not a plain object (`null`, array, string, number, boolean), normalization treats the payload as `{}` and produces the full default config shape.
+
+Examples:
+
+```json
+"hello"
+```
+
+```json
+42
+```
+
+Both normalize to:
+
+```json
+{
+  "schemaVersion": 1,
+  "setupComplete": false,
+  "demoProviderEnabled": false,
+  "presetId": "always-demo",
+  "mutedProviderIds": []
+}
+```
+
+Partial objects keep valid fields and coerce the rest:
+
+```json
+{
+  "setupComplete": true,
+  "presetId": "focus-day",
+  "mutedProviderIds": ["alpha", "alpha", " "]
+}
+```
+
+Normalizes to:
+
+```json
+{
+  "schemaVersion": 1,
+  "setupComplete": true,
+  "demoProviderEnabled": false,
+  "presetId": "focus-day",
+  "mutedProviderIds": ["alpha"]
+}
+```
+
+## Malformed field examples
+
+| Stored value | Normalized result |
+|---|---|
+| `"presetId": "not-a-real-preset"` | `"presetId": "always-demo"` |
+| `"presetId": " focus-day "` | `"presetId": "always-demo"` |
+| `"mutedProviderIds": "alpha"` | `"mutedProviderIds": []` |
+| `"mutedProviderIds": [" alpha "]` | `"mutedProviderIds": [" alpha "]` |
+| `"mutedProviderIds": ["ok", 42, "", "  ", "ok"]` | `"mutedProviderIds": ["ok"]` |
+| `"setupComplete": "yes"` | `"setupComplete": false` |
+| `"demoProviderEnabled": 1` | `"demoProviderEnabled": false` |
+
+## Schema versioning
+
+`schemaVersion` is pinned to `1`. There is no forward migration path yet; future versions would extend `normalizeConfig` to upgrade older shapes before returning `HostConfig`.
+
+## Related code
+
+- Type definition: `lib/types.ts` (`HostConfig`)
+- Normalization and persistence: `lib/config.ts`
+- Preset catalog: `lib/policy.ts` (`PRESET_OPTIONS`, `getPreset`, `DEFAULT_PRESET_ID`)
+- Tests: `tests/config.test.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-widget-host",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Host package for managing one shared Pi widget slot across multiple providers with preset policies and a built-in demo provider.",
   "type": "module",
   "license": "MIT",
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "pi-widget-core": "^0.1.0"
+    "pi-widget-core": "^0.1.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
@@ -60,6 +60,6 @@
     "@earendil-works/pi-coding-agent": "latest",
     "@types/node": "^26.0.0",
     "tsx": "^4.20.6",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   }
 }