pi-widget-host

v0.3.6

Published

15 days ago

Host package for managing one shared Pi widget slot across multiple providers with preset policies and a built-in demo provider.

Downloads

419

0High
0Medium
0Low

eiei114

pi-package pi-extension widget host display-policy

Pi Widget Host

Shared-slot host for managing one prompt-top Pi widget across multiple providers.

What this is

pi-widget-host owns one shared widget slot in Pi and picks a single winner from registered providers.

v1 is a Host-only MVP:

user-global config under ~/.pi/agent/
preset-first time-block policy
globalThis registry protocol for future provider packages
built-in demo provider for setup and dogfooding
silent empty slot when nothing should render

Features

/widget-host:setup guided first-run flow
/widget-host:status, /widget-host:policy, /widget-host:providers
/widget-host:mute and /widget-host:unmute
event boost for playing-now and matchday
known host tags: music, sports, playing-now, matchday, idle

Install

Install the published npm package with Pi:

pi install npm:pi-widget-host

Install into the current project instead of your user Pi settings:

pi install npm:pi-widget-host -l

Or install from GitHub:

pi install git:github.com/eiei114/pi-widget-host

Try it without permanently installing:

pi -e npm:pi-widget-host

Local development from this repository:

pi -e .

Quick start

Run the host locally, then open these commands:

/widget-host:setup
/widget-host:status
/widget-host:providers

/widget-host:setup asks whether to enable the built-in demo provider and which preset policy to save.

Commands

/widget-host:setup — save initial preset and optionally enable the demo provider
/widget-host:status — report setup status, preset, and active provider
/widget-host:policy — show or change the saved preset
/widget-host:providers — inspect known provider entries and effective state
/widget-host:mute — mute one provider in host config
/widget-host:unmute — unmute one provider in host config

Commands take no inline arguments. Input is collected with Pi UI prompts.

Registry protocol

Future provider packages can publish to the host without importing this package at runtime.

backing: globalThis
symbol: Symbol.for("pi-widget-host.registry.v1")
required fields: providerId, available, lines, updatedAt
optional fields: priority, tags, mode, ttlMs

See docs/protocol.md and the copy-paste minimal provider example.

Built-in demo provider

The built-in demo provider exists to prove the host loop first:

setup enables it explicitly
it publishes through the same registry protocol as future packages
it renders provider-owned lines through the shared host slot
if muted, disabled, or filtered out by policy, the slot disappears

Package contents

| Path | Purpose | |---|---| | 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

npm install
npm run ci
npm run pack:check

npm run ci runs typecheck, tests, and pack validation. npm run pack:check runs npm pack --dry-run to confirm the shipped tarball contents.

Release

This package uses npm Trusted Publishing.

npm version patch
git push

See docs/release.md.

Security

Pi packages execute with your local permissions. Review extensions before installing third-party packages.

For vulnerability reporting, see SECURITY.md.

License

MIT