pi-widget-host 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -1,16 +1,37 @@
 # Changelog
 
-## Unreleased
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning.
+
+## [0.3.6] - 2026-08-22
 
 ### Changed
 
-- Bump package version to `0.3.4` for the next patch release.
+- Merge the 2026-08-22 managed OSS dependency and maintenance PR batch.
 
-- Add Buy Me a Coffee sponsor button to README and native GitHub funding link via `.github/FUNDING.yml`.
+## [0.3.5] - 2026-08-04
 
-All notable changes to this project will be documented in this file.
+### Changed
 
-This project follows semantic versioning.
+- Bump package version for the Discord release webhook verification.
+
+## [0.3.4] - 2026-07-21
+
+### Added
+
+- `ROADMAP.md` maintenance context for weekly portfolio seeds and bounded micro-tasks.
+
+### Changed
+
+- CONTRIBUTING release instructions now match the auto-release and publish workflow (no `follow-tags`).
+- Dependency updates for `pi-widget-core` and development tooling.
+
+## [0.3.3] - 2026-07-04
+
+### Added
+
+- Buy Me a Coffee sponsor button to README and native GitHub funding link via `.github/FUNDING.yml`.
 
 ## [0.3.2] - 2026-06-26
 
@@ -50,4 +71,3 @@ This project follows semantic versioning.
 ### Changed
 
 - Replaced template placeholders and removed template-only skill, prompt, and theme resources.
-

package/README.md

@@ -1,5 +1,7 @@
 # Pi Widget Host
 
+[![Join dotfield.xyz on Discord](https://img.shields.io/badge/Join%20dotfield.xyz%20on%20Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/4945dXZVW5)
+
 [![CI](https://github.com/eiei114/pi-widget-host/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-widget-host/actions/workflows/ci.yml)
 [![Publish](https://github.com/eiei114/pi-widget-host/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-widget-host/actions/workflows/publish.yml)
 [![npm version](https://img.shields.io/npm/v/pi-widget-host.svg)](https://www.npmjs.com/package/pi-widget-host)
@@ -95,7 +97,7 @@ Future provider packages can publish to the host without importing this package
 - required fields: `providerId`, `available`, `lines`, `updatedAt`
 - optional fields: `priority`, `tags`, `mode`, `ttlMs`
 
-See [`docs/protocol.md`](docs/protocol.md).
+See [`docs/protocol.md`](docs/protocol.md) and the copy-paste [`minimal provider example`](docs/provider-example.md).
 
 ## Built-in demo provider
 
@@ -112,7 +114,9 @@ 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 |
 
 ## Development
@@ -150,4 +154,4 @@ For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
 
 ## License
 
-MIT
+MIT

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/docs/provider-example.md

@@ -0,0 +1,35 @@
+# Minimal provider example
+
+Provider packages can publish widget lines without importing `pi-widget-host`. They only need to write a `ProviderEntry` into the process-local registry on `globalThis`.
+
+```ts
+const registrySymbol = Symbol.for("pi-widget-host.registry.v1");
+
+type ProviderEntry = {
+  providerId: string;
+  available: boolean;
+  lines: string[];
+  updatedAt: string;
+  priority?: number;
+  tags?: string[];
+  mode?: string;
+  ttlMs?: number;
+};
+
+type WidgetHostRegistry = {
+  set(entry: ProviderEntry): void;
+};
+
+const registry = Reflect.get(globalThis, registrySymbol) as WidgetHostRegistry | undefined;
+
+registry?.set({
+  providerId: "example.now-playing",
+  available: true,
+  lines: ["Now Playing", "Example Artist — Example Song"],
+  updatedAt: new Date().toISOString(),
+  priority: 20,
+  tags: ["music", "playing-now"],
+});
+```
+
+Required fields are `providerId`, `available`, `lines`, and `updatedAt`. Optional fields such as `priority`, `tags`, `mode`, and `ttlMs` help the host choose between eligible providers. See [`protocol.md`](protocol.md) for the full registry shape and host selection notes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-widget-host",
-  "version": "0.3.4",
+  "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"
   }
 }