Idea: third-party component packs

[merlintheai[bot]]

Summary

Explore first-class support for third-party Agent Isles component packs: project-specific components, user-scoped local components, and components shared by other people via npm packages or git repositories.

The core idea:

A component pack is a declared bundle of custom elements, browser assets, and sanitizer permissions. Packs may come from the project, the user, npm packages, or pinned git repos. A render may include many packs, but each custom element tag should have exactly one owner.

Motivation

Agent Isles currently ships one built-in component bundle and a hardcoded sanitized-mode allowlist for core <agent-*> islands. That works for the first vocabulary, but teams and users will eventually want reusable components outside the core package:

• project-specific report components,
• personal/local rendering helpers,
• company/team design-system islands,
• community packs shared by npm or GitHub repos,
• specialized visualization/reporting components that should not live in core.

This should extend Agent Isles without turning it into a broad dashboard framework or arbitrary renderer plugin host.

Proposed model

Pack sources

Support these sources over time:

1. Project-local packs from isles.config.json.
2. User-local packs from user config, with a way to disable them for a render.
3. npm package packs such as @acme/agent-isles-charts.
4. git repo packs from pinned refs/tags/commits.

Example project config:

{
  "componentPacks": [
    "./components/executive-pack",
    "@acme/agent-isles-charts",
    {
      "type": "git",
      "repo": "https://github.com/acme/report-components.git",
      "ref": "v0.3.1",
      "path": "packs/roadmap"
    }
  ]
}

Pack manifest

A pack should declare its assets and safe tags/attributes up front, rather than requiring Agent Isles to execute pack code to discover them.

Possible agent-isles.pack.json shape:

{
  "$schema": "https://agent-isles.dev/schemas/pack.v1.json",
  "agentIslesPackVersion": 1,
  "name": "@acme/agent-isles-charts",
  "version": "0.2.0",
  "description": "Charts and KPI cards for Agent Isles reports",
  "homepage": "https://github.com/acme/agent-isles-charts",
  "tags": {
    "acme-kpi": {
      "description": "Compact KPI card",
      "attributes": {
        "label": { "type": "string", "required": true },
        "value": { "type": "string", "required": true },
        "unit": { "type": "string" },
        "tone": {
          "type": "enum",
          "values": ["neutral", "good", "warning", "danger"]
        }
      }
    },
    "acme-line-chart": {
      "description": "Small line chart",
      "attributes": {
        "label": { "type": "string" },
        "data": { "type": "json" }
      }
    }
  },
  "assets": [
    { "type": "module", "path": "dist/acme-agent-isles-charts.js" },
    { "type": "style", "path": "dist/acme-agent-isles-charts.css" }
  ]
}

In sanitized mode, Agent Isles can derive the allowed custom tags and attributes from the manifest, while still applying global safety rules.

Tag conflict policy

Custom element names are global in the page registry. customElements.define() throws if the same name is registered twice, and silent first/last-wins behavior would make rendering ambiguous.

Suggested policy:

1. Same canonical pack included twice: dedupe.
2. Same tag from the same canonical pack/version: dedupe.
3. Same tag from different packs: fail before rendering.
4. Core <agent-*> tags are reserved unless a future explicit override mode is added.
5. Pack JS should still defensively guard registration:

if (!customElements.get('acme-kpi')) {
  customElements.define('acme-kpi', AcmeKpi);
}

But Agent Isles should not rely on browser runtime errors as the conflict resolver.

Example failure:

Component tag conflict: <acme-chart> is declared by multiple packs.

- @acme/agent-isles-charts@0.2.0
- @contoso/isles-widgets@1.1.0

Use unique tag prefixes or configure an explicit tag owner.

User-scoped packs and reproducibility

User-scoped packs do not prevent the Markdown source from being reviewable in git. The reviewed artifact is still the source file.

The risk is narrower:

• reproducible rendering,
• semantic drift between environments,
• artifact portability,
• security posture.

So user packs should be allowed, but their use should be visible and controllable:

• support --no-user-packs,
• include pack metadata in the rendered HTML,
• provide a diagnostic command such as isles packs resolve report.md.

Example rendered metadata:

<meta name="agent-isles-packs" content="@agent-isles/core,@acme/agent-isles-charts,zach-local-notes">

Git repo support

Shared packs should support repositories, not only npm packages.

Possible explicit syntax:

{
  "type": "git",
  "repo": "https://github.com/acme/report-components.git",
  "ref": "v0.3.1",
  "path": "packs/roadmap"
}

Rules to consider:

• require or strongly warn for pinned refs/tags/commits,
• cache clones under an Agent Isles cache directory,
• require prebuilt assets and manifest in v1,
• do not auto-run npm install / build scripts from an arbitrary repo during render.

Users who want package-manager behavior can already install git dependencies through npm and reference the package by name.

Prior art / ecosystem patterns

Relevant patterns from other ecosystems:

• Docusaurus: explicit plugin/theme config, HTML tag injection, local component swizzling/overrides.
• Astro: integrations as installed packages with config/build hooks.
• MDX: component mapping through imports/providers, though Agent Isles differs by preserving HTML custom elements directly.
• Markdoc: custom tags with schemas, attributes, validation, and render targets. This is close to the manifest model Agent Isles likely wants.
• Web Components: duplicate tag registration is a real runtime failure; ecosystems such as Spectrum Web Components document registry conflicts and version deduplication concerns.
• WordPress/Gutenberg blocks: namespacing is used to avoid block-name collisions; Agent Isles can mirror this with custom-element prefixes such as <acme-kpi>.
• Vite/Storybook: ordered plugin/addon arrays are common, but Agent Isles should not use order to silently decide tag ownership.

Possible implementation phases

1. Project-local pack MVP

   • Add --pack <path>.
   • Resolve agent-isles.pack.json.
   • Copy pack JS/CSS assets into output.
   • Inject pack assets into rendered HTML.

2. Sanitizer extension and conflict detection

   • Merge manifest-declared tags/attributes into sanitized mode.
   • Fail on duplicate tag ownership.
   • Reserve core <agent-*> tags.

3. Project and user config

   • Add isles.config.json discovery.
   • Add user config loading.
   • Add --no-user-packs.
   • Add rendered pack metadata.

4. npm package packs

   • Resolve installed packages.
   • Read agentIsles.pack from package.json or root manifest.

5. git repo packs

   • Support pinned git sources.
   • Clone/cache repos.
   • Require prebuilt assets and manifests.

6. Diagnostics and authoring tools

   • isles packs resolve <file.md>.
   • isles packs validate <pack>.
   • Pack authoring docs/templates.

Open questions

• Should user-scoped packs load automatically from user config, or only when explicitly requested?
• Should unpinned git refs be an error or warning?
• Do we want a future explicit override mode for core tags or third-party tag conflicts?
• How much manifest validation should exist in v1 versus later?
• Should pack manifests support attribute value validation immediately, or only sanitizer allowlists first?
• What is the right asset output layout for multiple packs?

Suggested first slice

Start narrow:

Given a trusted local pack manifest, copy/inject its assets and preserve its declared custom elements in sanitized mode, while failing clearly on duplicate tag declarations.

That gives Agent Isles extensibility without turning the renderer into a general plugin host.

[zpyoung]

@merlin-the-ai

Should user-scoped packs load automatically from user config, or only when explicitly requested?
Automatically

Should unpinned git refs be an error or warning?
Warning

Do we want a future explicit override mode for core tags or third-party tag conflicts?
No

How much manifest validation should exist in v1 versus later?
Can you elaborate on this?

Should pack manifests support attribute value validation immediately, or only sanitizer allowlists first?
Elaborate on this

What is the right asset output layout for multiple packs?
What are our options?

[merlin-the-ai]

Short version:

Decisions:

• User packs load by default; --no-user-packs keeps CI/repro renders clean.
• Unpinned git refs warn, not fail, in render and packs resolve.
• No override mode: core <agent-*> tags are reserved; tag conflicts fail before render.

V1 should validate only safety/structure:

• valid JSON/version/name
• valid custom-element tags/attrs
• no reserved core tags
• known asset types: module, style
• relative in-pack asset paths that exist
• no duplicate tag ownership

Use manifest tags/attrs as sanitized-mode allowlists. Defer required/enum/range/slot/a11y checks to isles packs validate or later strict mode.

Recommended asset layout:

dist/assets/agent-isles/packs/<safe-pack-id>/<declared-assets>
dist/assets/agent-isles/packs.json

First slice: resolve trusted local/project/user manifests, warn on unpinned refs, fail on tag conflicts/reserved tags, copy declared assets, inject deterministically, and extend sanitized mode from allowlists.

Defer npm/git fetching until manifest + asset resolution is stable.

Triggered by GitHub Discussion mention via Hermes Agent.

[zpyoung]

@merlin-the-ai Let's create issues for the V1 of this feature. Create a new discussion for any v1+ modifications on this feature.

[merlin-the-ai]

Done.

Created the V1 executable issue chain:

• Parent: Component Packs V1: trusted local/user/project packs #68 — Component Packs V1: trusted local/user/project packs
• Component Packs 1/6: add V1 pack manifest model and loader #69 — 1/6: add V1 pack manifest model and loader — ready
• Component Packs 2/6: resolve explicit, project, and user pack inputs #70 — 2/6: resolve explicit, project, and user pack inputs — blocked by Component Packs 1/6: add V1 pack manifest model and loader #69
• Component Packs 3/6: enforce tag ownership and conflict policy #71 — 3/6: enforce tag ownership and conflict policy — blocked by Component Packs 2/6: resolve explicit, project, and user pack inputs #70
• Component Packs 4/6: extend sanitized mode from pack manifests #72 — 4/6: extend sanitized mode from pack manifests — blocked by Component Packs 3/6: enforce tag ownership and conflict policy #71
• Component Packs 5/6: copy pack assets and inject deterministic metadata #73 — 5/6: copy pack assets and inject deterministic metadata — blocked by Component Packs 4/6: extend sanitized mode from pack manifests #72
• Component Packs 6/6: add V1 diagnostics, docs, and demo fixture #74 — 6/6: add V1 diagnostics, docs, and demo fixture — blocked by Component Packs 5/6: copy pack assets and inject deterministic metadata #73

Also created:

• Milestone: Component Packs V1
• Label: area:packs
• V1+ follow-up discussion: Idea: component packs V1+ extensions #75 — Idea: component packs V1+ extensions

Synced all V1 issues into GitHub Project #1 with P1 / Release Readiness:

• Component Packs V1: trusted local/user/project packs #68 and Component Packs 1/6: add V1 pack manifest model and loader #69 are Todo
• Component Packs 2/6: resolve explicit, project, and user pack inputs #70–Component Packs 6/6: add V1 diagnostics, docs, and demo fixture #74 are Blocked in dependency order

V1 is scoped narrowly around trusted local/project/user pack manifests, deterministic asset handling, sanitized-mode allowlists, metadata, and hard tag-conflict failures. npm packages, git repo packs, strict validation, and authoring tools are captured in the V1+ discussion.

---

Triggered by GitHub Discussion mention via Hermes Agent.