pi-widget-host 0.3.6 → 0.3.11

package/CHANGELOG.md

@@ -4,18 +4,39 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning.
 
+## [0.3.11] - 2026-09-27
+
+- chore: periodic patch bump after 7+ days without npm publish
+
+
+
+
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning.
+## [0.3.10] - 2026-09-28
+
+- chore: periodic patch bump after 7+ days without npm publish
+## [0.3.9] - 2026-09-28
+
+- chore: periodic patch bump after 7+ days without npm publish
+## [0.3.8] - 2026-09-28
+
+- chore: periodic patch bump after 7+ days without npm publish
+## [0.3.7] - 2026-09-28
+
+- chore: periodic patch bump after 7+ days without npm publish
 ## [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
 
 - Bump package version for the Discord release webhook verification.
-
 ## [0.3.4] - 2026-07-21
 
 ### Added
@@ -26,26 +47,22 @@ This project follows semantic versioning.
 
 - 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
 
 ### Fixed
 
 - npm Trusted Publishing publish retry after registry configuration fix (no functional changes from 0.3.1).
-
 ## [0.3.1] - 2026-06-25
 
 ### Changed
 
 - README install and development guidance now matches the current Pi OSS template baseline, including project-local install, `pi -e npm:pi-widget-host`, and `npm run pack:check` (`npm pack --dry-run`) validation in the public docs flow.
 - `Package contents` now lists the actual shipped paths instead of unused template resource directories.
-
 ## [0.3.0] - 2026-06-24
 
 ### Added
@@ -56,7 +73,6 @@ This project follows semantic versioning.
 ### Changed
 
 - Minor semver bump marking the completed Host-only MVP: event boost, known tags, registry protocol, and demo-provider dogfooding path.
-
 ## [0.2.0] - 2026-06-15
 
 ### Added
@@ -71,3 +87,5 @@ This project follows semantic versioning.
 ### Changed
 
 - Replaced template placeholders and removed template-only skill, prompt, and theme resources.
+## Unreleased
+

package/README.md

@@ -99,6 +99,8 @@ Future provider packages can publish to the host without importing this package
 
 See [`docs/protocol.md`](docs/protocol.md) and the copy-paste [`minimal provider example`](docs/provider-example.md).
 
+Preset time blocks (`morning`, `day`, `evening`, `night`) follow the host machine's local hour with no timezone override — see [Limitations](docs/protocol.md#limitations) for how this affects presets such as `focus-day` and `night-owl`.
+
 ## Built-in demo provider
 
 The built-in demo provider exists to prove the host loop first:

package/docs/README.md

@@ -7,8 +7,8 @@ Entry point for `pi-widget-host` maintainer and provider-author docs.
 | 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. |
+| [`protocol.md`](protocol.md) | Registry protocol reference (`globalThis`, required fields, tags, TTL). Includes [time-block timezone limitations](protocol.md#limitations) and [scheduling examples](protocol.md#scheduling-examples-local-hour-assumptions). |
+| [`provider-example.md`](provider-example.md) | Minimal copy-paste provider that publishes through the registry. Notes [timezone assumptions](provider-example.md#timezone-assumptions) for `updatedAt` vs preset time blocks. |
 | [`release.md`](release.md) | npm Trusted Publishing workflow and CI release automation. |
 
 ## Maintenance context

package/docs/protocol.md

@@ -51,3 +51,65 @@ type WidgetHostRegistry = {
 - `ttlMs` + `updatedAt` drive stale exclusion
 - providers render final lines themselves; the host only picks a winner
 - the host can mute providers from config without uninstalling the package
+
+## Limitations
+
+### Time blocks use the host's local timezone
+
+Policy evaluation calls `detectTimeBlock(now)` in `lib/policy.ts`, which reads `now.getHours()` — the **host machine's local hour** in the process timezone. There is no `HostConfig` field or environment variable to override the timezone or shift block boundaries.
+
+Block boundaries (local hour, inclusive start / exclusive end unless noted):
+
+| Block | Local hour range |
+|---|---|
+| `morning` | 05:00–10:59 |
+| `day` | 11:00–16:59 |
+| `evening` | 17:00–21:59 |
+| `night` | 22:00–04:59 |
+
+Because presets are keyed by these blocks, the same `presetId` can behave differently on machines in different timezones or when the OS timezone changes. For example:
+
+- **`focus-day`** keeps the shared slot active during `morning`, `day`, and `evening`, but stays **silent at `night`**. A provider that looks "blocked" at 23:00 UTC may still be eligible at 23:00 JST on a Tokyo-local host.
+- **`night-owl`** stays **silent during `morning` and `day`**, then allows the slot in `evening` and `night`. Travel or remote machines can flip eligibility without any config change.
+
+When debugging provider priority or preset behavior, check the host's local time and current block before assuming a config bug.
+
+### Scheduling examples (local hour assumptions)
+
+The examples below mirror `tests/time-block-policy.test.ts`. Each `Date` is constructed with the host's **local** calendar fields (`new Date(year, month, day, hour, …)`), so the resulting time block follows the machine timezone, not UTC.
+
+**Example 1 — `night-owl` stays silent during work hours**
+
+With `presetId: "night-owl"` and one eligible demo provider:
+
+| Local time on host | `detectTimeBlock` | Widget slot |
+|---|---|---|
+| 07:00 | `morning` | silent |
+| 13:00 | `day` | silent |
+| 19:00 | `evening` | active |
+| 23:00 | `night` | active |
+
+The same saved preset can look "broken" when you compare against UTC. At **23:00 UTC** on a UTC host the block is `night` and the slot is active; on a **Tokyo-local host** that instant is **08:00 JST** (`morning`), so `night-owl` correctly stays silent.
+
+**Example 2 — `focus-day` vs `always-demo` at local night**
+
+At **23:30 local** with one eligible provider:
+
+- `always-demo` — slot stays active (`night` block is allowed).
+- `focus-day` — slot is silent (`night` block sets `allowedProviderIds: []`).
+
+**Example 3 — TTL refresh scheduling is UTC-based**
+
+Stale exclusion and the host's stale-TTL `setTimeout` use `updatedAt` (ISO-8601 UTC) plus `ttlMs`. That path does **not** read local hour boundaries:
+
+```ts
+registry.set({
+  providerId: "example.stale-check",
+  available: true,
+  lines: ["hello"],
+  updatedAt: new Date().toISOString(), // UTC instant
+  ttlMs: 90_000,
+});
+```
+
+A provider published at `2026-06-15T12:00:00.000Z` with `ttlMs: 60_000` goes stale at `12:01:00Z` on every host, regardless of preset or local time block. Do not mix this TTL clock with preset time-block scheduling when debugging.

package/docs/provider-example.md

@@ -33,3 +33,16 @@ registry?.set({
 ```
 
 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.
+
+## Timezone assumptions
+
+Two different clocks appear in this example:
+
+| Field / mechanism | Time basis | Used for |
+|---|---|---|
+| `updatedAt` (`toISOString()`) | UTC instant | stale exclusion and stale-TTL refresh scheduling |
+| Preset time blocks (`morning`, `day`, …) | Host machine local hour | when a saved preset allows or silences the shared slot |
+
+`new Date().toISOString()` in the snippet above is correct for TTL bookkeeping. It does **not** pin the provider to a local time block — the host evaluates blocks separately via `detectTimeBlock(now)` when applying preset policy.
+
+Tags cannot gate availability: the host scores `tags` only against the current block's `preferredTags` (plus the `playing-now` / `matchday` event boost) to adjust `effectivePriority`. Eligibility still depends on registry state (`available`, `lines`, stale TTL, host mutes) and the preset's `allowedProviderIds`. If your provider must appear only during certain local hours, enforce that in your own publish loop; the host will still classify the current block from the **process local timezone**. See [Limitations — scheduling examples](protocol.md#scheduling-examples-local-hour-assumptions) for preset walkthroughs (`focus-day`, `night-owl`) and a UTC-vs-local debugging scenario.

package/extensions/index.ts

@@ -258,3 +258,17 @@ export default function widgetHostExtension(pi: ExtensionAPI) {
     },
   });
 }
+
+export function resetHostExtensionStateForTests(): void {
+  clearStaleTimer();
+  registryDispose?.();
+  registryDispose = undefined;
+  stopDemoProviderHeartbeat();
+  uiBridge = undefined;
+}
+
+export function isRegistryWatcherActiveForTests(): boolean {
+  return registryDispose !== undefined;
+}
+
+export { ensureRegistryWatcher, refreshHostWidget };

package/lib/demo-provider.ts

@@ -1,6 +1,6 @@
 import { createProviderRuntime, type ProviderRuntime } from "pi-widget-core/provider";
 import { readHostConfig } from "./config.ts";
-import { detectTimeBlock } from "./policy.ts";
+import { DEFAULT_PRESET_ID, detectTimeBlock, getBlockPreferredTags, getPreset } from "./policy.ts";
 import { DEMO_PROVIDER_ID, type HostConfig, type ProviderEntry } from "./types.ts";
 
 const HEARTBEAT_MS = 30_000;
@@ -14,20 +14,6 @@ function ensureRuntime(): ProviderRuntime {
   return runtime;
 }
 
-function baseTagsForBlock(block: ReturnType<typeof detectTimeBlock>): string[] {
-  switch (block) {
-    case "morning":
-      return ["music", "idle"];
-    case "day":
-      return ["sports", "idle"];
-    case "evening":
-      return ["music", "sports"];
-    case "night":
-    default:
-      return ["idle", "music"];
-  }
-}
-
 function readEventTags(): string[] {
   const tags: string[] = [];
   if (["1", "true", "yes"].includes(String(process.env.PI_WIDGET_HOST_DEMO_PLAYING_NOW ?? "").toLowerCase())) {
@@ -41,7 +27,8 @@ function readEventTags(): string[] {
 
 export function buildDemoProviderEntry(config: HostConfig, now = new Date()): ProviderEntry {
   const block = detectTimeBlock(now);
-  const tags = [...new Set([...baseTagsForBlock(block), ...readEventTags()])];
+  const preferredTags = getBlockPreferredTags(getPreset(DEFAULT_PRESET_ID), block);
+  const tags = [...new Set([...preferredTags, ...readEventTags()])];
 
   return {
     providerId: DEMO_PROVIDER_ID,

package/lib/policy.ts

@@ -2,6 +2,7 @@ import { type HostConfig, type HostTimeBlock, type KnownHostTag, type PolicyEval
 
 export const DEFAULT_PRESET_ID = "always-demo";
 export const KNOWN_HOST_TAGS: readonly KnownHostTag[] = ["music", "sports", "playing-now", "matchday", "idle"] as const;
+const KNOWN_HOST_TAG_SET = new Set<string>(KNOWN_HOST_TAGS);
 
 export const PRESET_OPTIONS: readonly PolicyPreset[] = [
   {
@@ -39,8 +40,14 @@ export const PRESET_OPTIONS: readonly PolicyPreset[] = [
   },
 ];
 
+const PRESET_BY_ID = new Map(PRESET_OPTIONS.map((preset) => [preset.id, preset]));
+
 export function getPreset(id: string | undefined): PolicyPreset {
-  return PRESET_OPTIONS.find((preset) => preset.id === id) ?? PRESET_OPTIONS[0]!;
+  return PRESET_BY_ID.get(id ?? DEFAULT_PRESET_ID) ?? PRESET_OPTIONS[0]!;
+}
+
+export function getBlockPreferredTags(preset: PolicyPreset, block: HostTimeBlock): readonly KnownHostTag[] {
+  return preset.blocks[block].preferredTags ?? [];
 }
 
 export function detectTimeBlock(now = new Date()): HostTimeBlock {
@@ -63,29 +70,32 @@ export function isEntryStale(entry: Pick<ProviderEntry, "updatedAt" | "ttlMs">,
   return typeof remaining === "number" ? remaining <= 0 : false;
 }
 
-function tagScore(knownTags: KnownHostTag[], preferredTags: readonly KnownHostTag[] | undefined): number {
+function tagScore(knownTags: ReadonlySet<KnownHostTag>, preferredTags: readonly KnownHostTag[] | undefined): number {
   if (!preferredTags || preferredTags.length === 0) return 0;
-  const scores = preferredTags
-    .map((tag, index) => (knownTags.includes(tag) ? Math.max(40 - index * 10, 10) : 0))
-    .filter((value) => value > 0);
-  return scores.length > 0 ? Math.max(...scores) : 0;
+  let best = 0;
+  for (let index = 0; index < preferredTags.length; index++) {
+    const tag = preferredTags[index]!;
+    if (!knownTags.has(tag)) continue;
+    best = Math.max(best, Math.max(40 - index * 10, 10));
+  }
+  return best;
 }
 
-function eventBoost(knownTags: KnownHostTag[]): number {
+function eventBoost(knownTags: ReadonlySet<KnownHostTag>): number {
   let boost = 0;
-  if (knownTags.includes("playing-now")) boost += 100;
-  if (knownTags.includes("matchday")) boost += 80;
+  if (knownTags.has("playing-now")) boost += 100;
+  if (knownTags.has("matchday")) boost += 80;
   return boost;
 }
 
-function normalizeKnownTags(tags: string[] | undefined): KnownHostTag[] {
+function normalizeKnownTags(tags: string[] | undefined): Set<KnownHostTag> {
   const known = new Set<KnownHostTag>();
   for (const tag of tags ?? []) {
-    if ((KNOWN_HOST_TAGS as readonly string[]).includes(tag)) {
+    if (KNOWN_HOST_TAG_SET.has(tag)) {
       known.add(tag as KnownHostTag);
     }
   }
-  return [...known];
+  return known;
 }
 
 export function describePreset(preset: PolicyPreset): string {
@@ -103,13 +113,16 @@ export function evaluateProviderEntries(entries: readonly ProviderEntry[], confi
   const preset = getPreset(config.presetId);
   const timeBlock = detectTimeBlock(now);
   const blockPolicy = preset.blocks[timeBlock];
+  const mutedProviderIds = new Set(config.mutedProviderIds);
+  const allowedProviderIds =
+    blockPolicy.allowedProviderIds === undefined ? undefined : new Set(blockPolicy.allowedProviderIds);
 
   const providerStates = entries.map<ProviderState>((entry) => {
-    const knownTags = normalizeKnownTags(entry.tags);
-    const isMuted = config.mutedProviderIds.includes(entry.providerId);
+    const knownTagSet = normalizeKnownTags(entry.tags);
+    const isMuted = mutedProviderIds.has(entry.providerId);
     const isStale = isEntryStale(entry, now);
     const hasLines = Array.isArray(entry.lines) && entry.lines.length > 0;
-    const isAllowed = blockPolicy.allowedProviderIds === undefined || blockPolicy.allowedProviderIds.includes(entry.providerId);
+    const isAllowed = allowedProviderIds === undefined || allowedProviderIds.has(entry.providerId);
     const reasons: string[] = [];
 
     if (!entry.available) reasons.push("provider reported unavailable");
@@ -118,7 +131,7 @@ export function evaluateProviderEntries(entries: readonly ProviderEntry[], confi
     if (isMuted) reasons.push("muted in host config");
     if (isStale) reasons.push("stale ttl");
 
-    const effectivePriority = (entry.priority ?? 0) + tagScore(knownTags, blockPolicy.preferredTags) + eventBoost(knownTags);
+    const effectivePriority = (entry.priority ?? 0) + tagScore(knownTagSet, blockPolicy.preferredTags) + eventBoost(knownTagSet);
 
     let effectiveStatus: ProviderState["effectiveStatus"] = "eligible";
     if (isMuted) {
@@ -133,7 +146,7 @@ export function evaluateProviderEntries(entries: readonly ProviderEntry[], confi
       ...entry,
       effectivePriority,
       effectiveStatus,
-      knownTags,
+      knownTags: [...knownTagSet],
       reasons,
       isMuted,
       isStale,

package/package.json

@@ -1,65 +1,65 @@
-{
-  "name": "pi-widget-host",
-  "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",
-  "author": "Keisu",
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "widget",
-    "host",
-    "display-policy"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/eiei114/pi-widget-host.git"
-  },
-  "bugs": {
-    "url": "https://github.com/eiei114/pi-widget-host/issues"
-  },
-  "homepage": "https://github.com/eiei114/pi-widget-host#readme",
-  "files": [
-    "extensions/",
-    "lib/",
-    "docs/",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test tests/*.test.ts",
-    "ci": "npm run typecheck && npm test && npm run pack:check",
-    "pack:check": "npm pack --dry-run"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "pi": {
-    "extensions": [
-      "./extensions/index.ts"
-    ]
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "pi-widget-core": "^0.1.3"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
-  },
-  "peerDependenciesMeta": {
-    "@earendil-works/pi-coding-agent": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@earendil-works/pi-coding-agent": "latest",
-    "@types/node": "^26.0.0",
-    "tsx": "^4.20.6",
-    "typescript": "^7.0.2"
-  }
-}
+{
+  "name": "pi-widget-host",
+  "version": "0.3.11",
+  "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",
+  "author": "Keisu",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "widget",
+    "host",
+    "display-policy"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eiei114/pi-widget-host.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eiei114/pi-widget-host/issues"
+  },
+  "homepage": "https://github.com/eiei114/pi-widget-host#readme",
+  "files": [
+    "extensions/",
+    "lib/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "ci": "npm run typecheck && npm test && npm run pack:check",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "pi-widget-core": "^0.1.4"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "latest",
+    "@types/node": "^26.0.0",
+    "tsx": "^4.20.6",
+    "typescript": "^7.0.2"
+  }
+}