Skip to content

FE-1758: Document the Petrinaut plugin interface - #9797

Closed
kube wants to merge 2 commits into
claude/fe-1757-plugin-chrome-migrationfrom
claude/fe-1758-plugin-docs
Closed

FE-1758: Document the Petrinaut plugin interface#9797
kube wants to merge 2 commits into
claude/fe-1757-plugin-chrome-migrationfrom
claude/fe-1758-plugin-docs

Conversation

@kube

@kube kube commented Sep 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Important

Docs and a Storybook example, nothing user-facing.

Summary

Adds the plugin interface documentation: a usage manual in the architecture docs attached to the ui.plugins layer, and a Storybook story with one host plugin that contributes buttons, panel sections, a Labs settings group and a command.

The manual covers the places, the data model and its rules, worked plugins from the website and the HASH embed, installation, and what the API does not do yet. That last section lists the places a Brunch assistant plugin needs before it can leave the aiAssistant prop.

Links

Changes

  • content/plugins/usage-manual.mdx documents the plugin interface

    Places table, the PetrinautPlugin model, a button plugin, a stateful overlay plugin, an edit view plugin, a Labs settings group, and installation.

  • Manual states the contract every contribution runs under

    Ids are unique per place and canvas is reserved.
    Each contribution has its own error and Suspense boundary, and a failing component keeps the plugin's commands.
    component mounts inside the workspace row and remounts on a document switch.

  • Manual lists what is not here yet

    Menu items, an assistant contribution with tool registration, notices, windows, exported settings rows and a public Voice session hook.

  • content/handle/host-integration.mdx points hosts at plugins

    Props table drops viewportActions and marks slots deprecated, with only settingsLabs left.

  • Plugins / Host plugin story installs one plugin into the editor

    A top-bar button running a command, a viewport button, a bottom-panel tab, a sidebar section and a Labs group with a toggle.

Test coverage

  • lint:arch-docs and the docs-site build:

    The page attaches to a declared layer and compiles.

How to test

  • Open Plugins usage manual on Vercel

    Expect the page under the ui.plugins layer

  • yarn workspace @hashintel/petrinaut dev
  • Plugins > Host plugin

    Expect the Greet button in the top bar, a Net summary tab and a Host notes section

  • Menu > User settings
    • Labs

      Expect a Host plugin group with a Host experiment toggle

@kube kube self-assigned this Sep 20, 2026
@vercel

vercel Bot commented Sep 20, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
hash Ready Ready Preview Sep 22, 2026 7:14pm UTC
petrinaut Ready Ready Preview Sep 22, 2026 7:14pm UTC
petrinaut-docs Ready Ready Preview Sep 22, 2026 7:14pm UTC
1 Skipped Deployment
Project Deployment Actions Updated
hashdotdesign-tokens Ignored Ignored Preview Sep 22, 2026 7:14pm UTC

Request Review

@kube
kube added this pull request to stack #9798 September 20, 2026 18:16
@github-actions github-actions Bot added area/libs Relates to first-party libraries/crates/packages (area) type/eng > frontend Owned by the @frontend team type/eng > backend Owned by the @backend team area/apps > hash.design Affects the `hash.design` design site (app) labels Sep 20, 2026
kube added 2 commits September 22, 2026 19:54
@kube
FE-1758: Document the Petrinaut plugin interface
19c80e1 
A usage manual in the architecture docs, attached to the ui.plugins
layer, and a Storybook story with one host plugin that contributes
buttons, panel sections and a command.
@kube
FE-1758: Document settings groups, contribution boundaries and what B…
de07f4c 
…runch needs next

The usage manual gains the Labs settings place, the per-contribution error
and Suspense boundaries, where plugin components mount and what they may
render, the display-only command shortcut, and a list of the places still
missing with the consumer each one waits for. The host-integration prop
table drops viewportActions and marks slots as Labs-only. The host-plugin
story contributes a Labs settings group.
@kube
kube force-pushed the claude/fe-1758-plugin-docs branch from 2293fd5 to de07f4c Compare September 22, 2026 19:01
@kube

kube commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

Superseded: the plugin API docs ship in #9904 and #9914.

@kube kube closed this Oct 7, 2026

This branch was successfully deployed

3 active deployments
Preview – hash — de07f4c0 Deployed Sep 22, 2026 by vercel[bot]
View deployment
Preview – petrinaut-docs — de07f4c0 Deployed Sep 22, 2026 by vercel[bot]
View deployment
Preview – petrinaut — de07f4c0 Deployed Sep 22, 2026 by vercel[bot]
View deployment
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot will automatically review once the pull request is marked ready for review

Assignees

@kube kube

Labels

area/apps > hash.design Affects the `hash.design` design site (app) area/libs Relates to first-party libraries/crates/packages (area) type/eng > backend Owned by the @backend team type/eng > frontend Owned by the @frontend team

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@kube