Distribution

Cosmo currently supports two widget publishing flows and one wallpaper publishing flow.

Widget Publishing

1. GitHub-Linked Publishing

This is the recommended path when your widget lives in a GitHub repository.

How it works:

1. Open the Cosmo web app and go to /publish.
2. Choose Widget.
3. Connect your GitHub account.
4. Install the Cosmo GitHub App on the repository you want to publish from.
5. Select the repository and choose a workflow trigger.

Available triggers:

• On Release: publish when you create a GitHub Release.
• On Version Bump: publish when the workflow sees a new widget version in your repo.
• Manual Only: install the workflow, but run it yourself from GitHub Actions.

When you submit the form, Cosmo:

• connects the repository to the publishing pipeline
• writes the required repository secret
• installs the publish workflow into .github/workflows/publish-widget.yml

After that, GitHub Actions runs the widget publish CLI for you.

2. Manual ZIP Publishing

Use this when you already have a packaged widget bundle and do not want to publish through a linked GitHub repo.

Manual ZIP upload currently happens on the same /publish page:

1. Choose Widget.
2. Upload a widget ZIP instead of selecting a repository.
3. Cosmo inspects the archive locally in the browser and shows:
   • widget name
   • widget version
   • config schema version
   • resolved widget identity
   • whether required files are present
4. If the ZIP looks valid, submit it to upload and process it.

The ZIP should match the packaged widget layout used by the publishing CLI:

• built widget output at the archive root, such as index.html and/or assets/
• widget.config.json
• optional README.md
• optional widget.preferences-template.json
• optional marketplace/previews/

Updating an Existing Widget

Version history is preserved in Cosmo. A widget keeps one stable widget record, and each release is stored as its own version entry.

Current update paths:

• GitHub-linked widgets: publish a newer version from the same repo.
• Manual ZIP widgets: on /publish, choose one of your existing published widgets and upload a new ZIP version for that widget.

Cosmo will keep the existing widget identity and add a new version instead of creating a duplicate widget.

Wallpaper Publishing

Wallpapers are published from the same /publish page, but the flow is simpler.

Current wallpaper flow:

1. Choose Wallpaper.
2. Upload an image or video file.
3. Add a description.
4. Submit the upload for processing.

Wallpapers do not use the widget packaging format, GitHub workflows, or widget version history.

Developer Mode vs Marketplace Publishing

Marketplace publishing is separate from local development.

• Developer Mode is for loading and testing a widget locally while you build it.
• Marketplace publishing is for uploading a packaged widget or connecting a GitHub repo so other users can discover it in Cosmo.

If you are still building your widget, stay in Developer Mode. Use the flows above once you are ready to distribute versions to the marketplace.

What Is Still Missing

The current publishing system works, but some publisher tooling is still being built:

• a dedicated “my published items” dashboard
• richer version history and release management UI
• more detailed processing/job status
• future monetization and moderation features