switchboard/core
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Releases 9 Wiki Activity

Feat v0.10.0 panel manifest lifecycle

Browse Source 
Panels are a new kernel rendering tier between surfaces and block
renderers, enabling composable companion views (e.g. notes panel
inside chat). This version ships the plumbing layer:

- Manifest validation for panels field (provider map + consumer array)
- Soft-dep warning at install time for unresolved panel consumers
- PanelMeta struct + resolvePanels() resolves consumers at surface load
- window.__PANELS__ injected into base template
- sw.panels SDK module (open/close/toggle/isOpen/isAvailable/list/active)
- Lazy JS loading pipeline with module caching
- 10 new tests (6 validation + 4 resolve)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jeffrey Smith
2026-04-03 21:03:22 +00:00
parent 414b2290ce
commit b937580ed8
9 changed files with 561 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
server/handlers/package_validate.go
View File

@@ -38,6 +38,8 @@ type ManifestInfo struct {
RequiresRoles []string // team roles needed to access this package (advisory, OR semantics)
Adoptable bool // if true, teams can adopt this package to get a team-scoped copy
HasFormTemplate bool // if true, package declares a form_template at the top level
HasPanels bool // if true, package provides panels (provider form)
PanelConsumers []string // panel IDs this package consumes (consumer form, e.g. "notes.reference")
}
// ValidateManifest parses a manifest map and validates all required fields,
@@ -199,6 +201,44 @@ func ValidateManifest(manifest map[string]any) (*ManifestInfo, error) {
info.HasFormTemplate = true
}
// v0.10.0: panels — provider (map) or consumer (array) declarations
if rawPanels := manifest["panels"]; rawPanels != nil {
switch p := rawPanels.(type) {
case map[string]any:
// Provider form: { "reference": { "entry": "...", "title": "..." }, ... }
for key, raw := range p {
panel, ok := raw.(map[string]any)
if !ok {
return nil, fmt.Errorf("panels.%s must be an object", key)
}
entry, _ := panel["entry"].(string)
if entry == "" {
return nil, fmt.Errorf("panels.%s requires an 'entry' field", key)
}
title, _ := panel["title"].(string)
if title == "" {
return nil, fmt.Errorf("panels.%s requires a 'title' field", key)
}
}
info.HasPanels = true
case []any:
// Consumer form: ["notes.reference", "notes.graph"]
for i, raw := range p {
s, ok := raw.(string)
if !ok || s == "" {
return nil, fmt.Errorf("panels[%d] must be a non-empty string", i)
}
parts := strings.SplitN(s, ".", 2)
if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
return nil, fmt.Errorf("panels[%d] must be in 'package.panel' format, got %q", i, s)
}
info.PanelConsumers = append(info.PanelConsumers, s)
}
default:
return nil, fmt.Errorf("panels must be an object (provider) or array (consumer)")
}
}
info.SchemaVersion = ParseSchemaVersion(manifest)
// ── Type-specific constraints ────────────────────────────────

97
server/handlers/package_validate_test.go
View File

@@ -349,3 +349,100 @@ func TestValidateManifest_AutoSynthesizeSurfaces(t *testing.T) {
t.Errorf("expected layout 'editor', got %q", s["layout"])
}
}
// ── Panels validation (v0.10.0) ─────────────────────────────
func TestValidateManifest_PanelsProviderValid(t *testing.T) {
m := map[string]any{
"id": "my-notes",
"title": "Notes",
"panels": map[string]any{
"reference": map[string]any{
"entry": "js/panels/reference.js",
"title": "Notes Reference",
"icon": "📝",
},
},
}
info, err := ValidateManifest(m)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if !info.HasPanels {
t.Error("expected HasPanels to be true")
}
}
func TestValidateManifest_PanelsProviderMissingEntry(t *testing.T) {
m := map[string]any{
"id": "my-notes",
"title": "Notes",
"panels": map[string]any{
"reference": map[string]any{
"title": "Notes Reference",
},
},
}
_, err := ValidateManifest(m)
if err == nil {
t.Fatal("expected error for panel missing entry")
}
}
func TestValidateManifest_PanelsProviderMissingTitle(t *testing.T) {
m := map[string]any{
"id": "my-notes",
"title": "Notes",
"panels": map[string]any{
"reference": map[string]any{
"entry": "js/panels/reference.js",
},
},
}
_, err := ValidateManifest(m)
if err == nil {
t.Fatal("expected error for panel missing title")
}
}
func TestValidateManifest_PanelsConsumerValid(t *testing.T) {
m := map[string]any{
"id": "my-chat",
"title": "Chat",
"panels": []any{"notes.reference", "notes.graph"},
}
info, err := ValidateManifest(m)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if len(info.PanelConsumers) != 2 {
t.Fatalf("expected 2 panel consumers, got %d", len(info.PanelConsumers))
}
if info.PanelConsumers[0] != "notes.reference" {
t.Errorf("expected 'notes.reference', got %q", info.PanelConsumers[0])
}
}
func TestValidateManifest_PanelsConsumerInvalidFormat(t *testing.T) {
m := map[string]any{
"id": "my-chat",
"title": "Chat",
"panels": []any{"notes-no-dot"},
}
_, err := ValidateManifest(m)
if err == nil {
t.Fatal("expected error for consumer panel without dot separator")
}
}
func TestValidateManifest_PanelsInvalidType(t *testing.T) {
m := map[string]any{
"id": "my-pkg",
"title": "My Package",
"panels": "invalid-string",
}
_, err := ValidateManifest(m)
if err == nil {
t.Fatal("expected error for panels as string (neither map nor array)")
}
}

16
server/handlers/packages.go
View File

@@ -349,6 +349,22 @@ func (h *PackageHandler) InstallPackage(c *gin.Context) {
}
}
// Phase 11: Soft-dep warnings for panel consumers
if len(mInfo.PanelConsumers) > 0 {
for _, ref := range mInfo.PanelConsumers {
parts := strings.SplitN(ref, ".", 2)
if len(parts) != 2 {
continue
}
provPkg, _ := h.stores.Packages.Get(c.Request.Context(), parts[0])
if provPkg == nil {
log.Printf("[packages] %s: panel consumer %q — provider package %q not installed", pkgID, ref, parts[0])
} else if !provPkg.Enabled {
log.Printf("[packages] %s: panel consumer %q — provider package %q is disabled", pkgID, ref, parts[0])
}
}
}
resp := gin.H{
"id": pkgID,
"title": mInfo.Title,

83
server/pages/pages.go
View File

@@ -61,6 +61,20 @@ type SurfaceManifest struct {
Source string `json:"source"` // "core" or "extension"
}
// PanelMeta describes a resolved panel available to a surface.
type PanelMeta struct {
PanelID string `json:"panel_id"` // e.g. "notes.reference"
PackageID string `json:"package_id"` // e.g. "notes"
Entry string `json:"entry"` // e.g. "js/panels/reference.js"
Title string `json:"title"` // human-readable
Icon string `json:"icon,omitempty"` // emoji or icon key
Description string `json:"description,omitempty"` // short description
MinWidth int `json:"min_width,omitempty"` // minimum width in px
MinHeight int `json:"min_height,omitempty"` // minimum height in px
DefaultWidth int `json:"default_width,omitempty"` // default width in px
DefaultHeight int `json:"default_height,omitempty"` // default height in px
}
// BannerConfig holds environment banner settings.
type BannerConfig struct {
Text string `json:"text"`
@@ -109,6 +123,8 @@ type PageData struct {
BrowserExtensions []string `json:"-"` // IDs of enabled browser-tier extensions (for script injection)
Panels []PanelMeta `json:"-"` // resolved panels available to this surface
InstanceName string // branding: instance display name
LogoURL string // branding: custom logo URL
Tagline string // branding: tagline under instance name
@@ -237,6 +253,72 @@ func (e *Engine) browserExtensionIDs() []string {
return ids
}
// resolvePanels reads the consumer's panels array from the raw manifest and
// resolves each reference against installed+enabled provider packages.
// Returns nil if no panels are declared or no providers are available.
func (e *Engine) resolvePanels(ctx context.Context, manifest map[string]any) []PanelMeta {
if e.stores.Packages == nil {
return nil
}
rawPanels, ok := manifest["panels"].([]any)
if !ok || len(rawPanels) == 0 {
return nil
}
var result []PanelMeta
for _, raw := range rawPanels {
ref, ok := raw.(string)
if !ok {
continue
}
parts := strings.SplitN(ref, ".", 2)
if len(parts) != 2 {
continue
}
pkgID, panelKey := parts[0], parts[1]
provPkg, err := e.stores.Packages.Get(ctx, pkgID)
if err != nil || provPkg == nil || !provPkg.Enabled {
continue
}
provPanels, ok := provPkg.Manifest["panels"].(map[string]any)
if !ok {
continue
}
panelDef, ok := provPanels[panelKey].(map[string]any)
if !ok {
continue
}
meta := PanelMeta{
PanelID: ref,
PackageID: pkgID,
}
meta.Entry, _ = panelDef["entry"].(string)
meta.Title, _ = panelDef["title"].(string)
meta.Icon, _ = panelDef["icon"].(string)
meta.Description, _ = panelDef["description"].(string)
if v, ok := panelDef["min_width"].(float64); ok {
meta.MinWidth = int(v)
}
if v, ok := panelDef["min_height"].(float64); ok {
meta.MinHeight = int(v)
}
if v, ok := panelDef["default_width"].(float64); ok {
meta.DefaultWidth = int(v)
}
if v, ok := panelDef["default_height"].(float64); ok {
meta.DefaultHeight = int(v)
}
if meta.Entry != "" && meta.Title != "" {
result = append(result, meta)
}
}
return result
}
// UserContext is the authenticated user's info available to templates.
type UserContext struct {
ID string `json:"id"`
@@ -552,6 +634,7 @@ func (e *Engine) RenderExtensionSurface() gin.HandlerFunc {
EnabledSurfaces: e.EnabledSurfaceIDs(),
ExtensionSurfaces: e.extensionNavItems(),
BrowserExtensions: e.browserExtensionIDs(),
Panels: e.resolvePanels(c.Request.Context(), sr.Manifest),
})
}
}

141
server/pages/panels_test.go Normal file
View File

@@ -0,0 +1,141 @@
package pages
import (
"context"
"testing"
"armature/store"
)
func TestResolvePanels_HappyPath(t *testing.T) {
// Provider package with a panels map
provider := &store.PackageRegistration{
ID: "notes",
Title: "Notes",
Enabled: true,
Source: "extension",
Manifest: map[string]any{
"panels": map[string]any{
"reference": map[string]any{
"entry": "js/panels/reference.js",
"title": "Notes Reference",
"icon": "📝",
"description": "Searchable note list",
"min_width": float64(280),
"default_width": float64(400),
},
},
},
}
// Consumer package that wants notes.reference
consumer := &store.PackageRegistration{
ID: "chat",
Title: "Chat",
Enabled: true,
Source: "extension",
Manifest: map[string]any{
"panels": []any{"notes.reference"},
},
}
e := testEngine(t, provider, consumer)
panels := e.resolvePanels(context.Background(), consumer.Manifest)
if len(panels) != 1 {
t.Fatalf("expected 1 panel, got %d", len(panels))
}
p := panels[0]
if p.PanelID != "notes.reference" {
t.Errorf("expected panel_id 'notes.reference', got %q", p.PanelID)
}
if p.PackageID != "notes" {
t.Errorf("expected package_id 'notes', got %q", p.PackageID)
}
if p.Entry != "js/panels/reference.js" {
t.Errorf("expected entry 'js/panels/reference.js', got %q", p.Entry)
}
if p.Title != "Notes Reference" {
t.Errorf("expected title 'Notes Reference', got %q", p.Title)
}
if p.Icon != "📝" {
t.Errorf("expected icon '📝', got %q", p.Icon)
}
if p.MinWidth != 280 {
t.Errorf("expected min_width 280, got %d", p.MinWidth)
}
if p.DefaultWidth != 400 {
t.Errorf("expected default_width 400, got %d", p.DefaultWidth)
}
}
func TestResolvePanels_ProviderMissing(t *testing.T) {
// Consumer references a package that doesn't exist
consumer := &store.PackageRegistration{
ID: "chat",
Title: "Chat",
Enabled: true,
Source: "extension",
Manifest: map[string]any{
"panels": []any{"nonexistent.panel"},
},
}
e := testEngine(t, consumer)
panels := e.resolvePanels(context.Background(), consumer.Manifest)
if len(panels) != 0 {
t.Errorf("expected 0 panels for missing provider, got %d", len(panels))
}
}
func TestResolvePanels_ProviderDisabled(t *testing.T) {
provider := &store.PackageRegistration{
ID: "notes",
Title: "Notes",
Enabled: false, // disabled
Source: "extension",
Manifest: map[string]any{
"panels": map[string]any{
"reference": map[string]any{
"entry": "js/panels/reference.js",
"title": "Notes Reference",
},
},
},
}
consumer := &store.PackageRegistration{
ID: "chat",
Title: "Chat",
Enabled: true,
Source: "extension",
Manifest: map[string]any{
"panels": []any{"notes.reference"},
},
}
e := testEngine(t, provider, consumer)
panels := e.resolvePanels(context.Background(), consumer.Manifest)
if len(panels) != 0 {
t.Errorf("expected 0 panels for disabled provider, got %d", len(panels))
}
}
func TestResolvePanels_NoPanelsField(t *testing.T) {
consumer := &store.PackageRegistration{
ID: "chat",
Title: "Chat",
Enabled: true,
Source: "extension",
Manifest: map[string]any{},
}
e := testEngine(t, consumer)
panels := e.resolvePanels(context.Background(), consumer.Manifest)
if panels != nil {
t.Errorf("expected nil panels for manifest without panels field, got %v", panels)
}
}

1
server/pages/templates/base.html
View File

@@ -124,6 +124,7 @@
{{if .Manifest}}window.__MANIFEST__ = {{.Manifest | toJSON}};{{end}}
{{if .SurfacePath}}window.__SURFACE_PATH__ = '{{.SurfacePath}}';{{end}}
{{if .SurfaceParams}}window.__SURFACE_PARAMS__ = {{.SurfaceParams | toJSON}};{{end}}
{{if .Panels}}window.__PANELS__ = {{.Panels | toJSON}};{{end}}
</script>
{{/* All surfaces use Preact SDK boot(). Legacy script includes removed.