Document module script entries (scriptType) and the src/ tree

[topkoa]

Summary

The stems plugin's R1 pilot (its PRs #23–#36) split its client code from one monolithic screen.js into an ES-module tree: plugin.json declares "scriptType": "module", screen.js is a one-line import './src/main.js';, and the code lives under src/ sharing state via import/export.

The current feedBack Host already supports this — it injects <script type="module"> when scriptType is "module", and serves the module tree at /api/plugins/{id}/src/{path} — but the spec did not describe it, and best-practices actively contradicted it ("screen.js runs as a classic script", "the plugin root is not a servable directory"). This PR brings the spec up to date.

Changes (purely additive — every existing manifest still validates)

• spec/plugin-spec-v1.md — §3 anatomy shows the optional src/ tree; §4.1/§4.3 document the new scriptType and minHost keys; §6.1 notes classic-vs-module loading; new §6.8 "Splitting client code across modules."
• schemas/plugin.schema.json — added scriptType and minHost properties.
• spec/best-practices.md — rewrote rules 27–29 (and the checklist): an ES-module entry (scriptType: "module" + src/) is now the recommended way to split client code; the classic single-screen.js bundle / window-shared runtime split is kept as the fallback for older Hosts. Corrects text that was flatly wrong once scriptType: "module" is set.
• CHANGELOG.md — [Unreleased] entry.

Per spec §9 this is additive (a new OPTIONAL manifest key an older Host ignores), so no manifest-major bump.

Verification

• schemas/plugin.schema.json is valid JSON; tools/validate.py passes both examples and the real stems main manifest.
• Repo test suite: 11 passed.
• All new cross-reference anchors match GitHub's heading-slug convention.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added support for ES-module client entries via a scriptType manifest setting, enabling src/-based code splitting.
  • Documented minHost guidance for module-dependent plugins to prevent older hosts from loading module entries incorrectly.
• Documentation
  • Updated the plugin specification and best-practices to clearly explain classic-script vs module entry behavior, including asset URL patterns and re-hydration/idempotency expectations.
• Schema Updates
  • Extended the plugin manifest schema with scriptType and minHost, and clarified the script field’s meaning.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 392a3f12-f56c-4080-a8c0-4b0f593d8a85

📥 Commits

Reviewing files that changed from the base of the PR and between 45ffb00 and 3609087.

📒 Files selected for processing (1)

• spec/best-practices.md

🚧 Files skipped from review as they are similar to previous changes (1)

• spec/best-practices.md

---

📝 Walkthrough

Walkthrough

This PR updates the schema, spec, best-practices guide, and changelog to define scriptType and minHost, and to document ES-module client entries alongside classic script loading and splitting.

Changes

scriptType and module splitting documentation

Layer / File(s)	Summary
Schema definition for scriptType and minHost schemas/plugin.schema.json	Adds scriptType and minHost properties and revises the script description.
Plugin spec v1 classic vs module script semantics spec/plugin-spec-v1.md	Updates the plugin anatomy, field summary, script loading semantics, screen lifecycle text, and module-splitting section for scriptType and minHost.
Best-practices guidance for splitting client code spec/best-practices.md	Revises split-client-code guidance for module mode, classic mode, idempotent loading, and the publishing checklist.
Changelog entry CHANGELOG.md	Documents scriptType, minHost, and the revised client-code organization guidance.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• got-feedBack/feedBack-plugin-spec#1: Introduces the plugin spec, schema, and best-practices files that this PR extends with scriptType and minHost documentation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: documenting module script entries and the optional src/ tree.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/module-script-paradigm

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@spec/best-practices.md`:
- Around line 455-460: The split-runtime guidance in best-practices.md hardcodes
the plugin asset route, which conflicts with Host-assigned asset URLs. Update
the “Split at runtime” section to tell authors to use the Host-provided asset
URL/base instead of `/api/plugins/<id>/assets/…`, and keep the checklist bullet
aligned; the relevant guidance is in the split-runtime asset-loading note and
the classic-script state-sharing example.
- Around line 422-429: The fenced examples in this best-practices section are
unlabeled, which triggers MD040 and makes them harder to read. Update the code
fences in the tree example and the runtime snippet to use the appropriate
language tags, using text for the directory tree and js for the JavaScript
example. Apply the same fix to the matching fenced block referenced later in the
document so all examples use explicit labels.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5bf35df4-9fc0-4e9d-9fb9-55b6cd24eb39

📥 Commits

Reviewing files that changed from the base of the PR and between 2995351 and 45ffb00.

📒 Files selected for processing (4)

• CHANGELOG.md
• schemas/plugin.schema.json
• spec/best-practices.md
• spec/plugin-spec-v1.md