Repository navigation
Compat baseline 2/5: define required vs optional host capability checks (degrade only the dependent feature) #132
Description
Part of #102. Depends on Compat baseline 1/5 (the matrix says what is required vs optional).
A missing optional API must disable only the features that depend on it, never the whole plugin.
Scope
- Define the convention plugins use to declare and check required vs optional host capabilities (feature detection at the call site, one predicate per feature, a single named warning when an optional feature is unavailable).
- Document the convention in the plugin docs so plugins converge on it.
- Apply it to the host APIs listed in Define a verifiable core compatibility baseline for current plugins #102 as a reference, e.g.
renderFrameAt/setExternalFrameDriver,playerContexts,/ws/sync/{session_id}, chart-transform, andgetPhrases().top_difficulty.
Acceptance criteria
- Each API in the matrix has a documented probe.
- A host missing one optional API still loads dependent plugins; only that feature reports as unavailable, with a message naming the missing requirement.
- No plugin raises its basic-mode floor because an optional feature needs a newer host.
Out of scope
Enforcing minHost (sub-issue 3).
Activity
pullfrog commentedon Oct 2, 2026
pullfrog commentedon Oct 9, 2026
Docs-only sub-issue 2/5 of #102 landed as PR #142 (branch
pullfrog/132-host-capability-checks, commitcore(docs): ..., 4 files, +308/−1).Delivered:
docs/plugin-host-compat.mddefines the plugin-side convention for required-vs-optional host capability checks — one exact-surface predicate per host API at the call site (never version strings), one per-session warning naming the plugin/feature/missing requirement, and the rule that a missing optional API disables only its feature, never the plugin and never its basic-mode floor. It documents the canonicalHOST_FEATURES/hostFeature/assumeHostFeatureJS pattern plus theroutes.py+context["log"]backend equivalent, and gives a probe + per-row degradation contract for all sevendocs/compatibility.mdmatrix rows (dlc_paths,read_member_bytes,chart-transform,/ws/syncrelay,setExternalFrameDriver/renderFrame/renderFrameAt,playerContexts,getPhrases().top_difficulty), along with a plugin-PR checklist.CLAUDE.md,README.md, and the CHANGELOG[Unreleased]were updated.Scope exclusions (recorded): no new core API (a helper only new hosts ship can't serve a degrade-on-old-host convention — detection is plugin-side), no
minHostchanges (sub-issue 3/5's material), no loading/capability behavior change.Verification: every probe was cross-checked against current host source (
static/highway.js,static/capabilities/chart-transform.js,static/capabilities/player-identity.js,plugins/__init__.py); commit hashes and upstream/fork-only tags matchdocs/compatibility.mdexactly; all JS/Python fenced blocks were syntax-checked; secret/PII scan clean; areviewfrogpre-commit self-review returned zero blocking findings (four clarity-level suggestions were addressed). No tests run — docs-only diff (tests/test_plugin_manifest_contract.pyonly parsesdocs/capability-recipes.md, untouched).Task list (5/5 completed)
big-pickle(free) ｜ 𝕏