Tool package interface 0.1

From 0.1.208, clicking Install without risk confirmation highlights the checkbox in red and scrolls it into view. Checking it clears the highlight.

From 0.1.207, opening this tab automatically reloads the catalog and current installation status. Removing a package listed in the catalog makes it installable again, even if it was originally installed locally. Newly approved packages appear the next time the tab opens.

Since 0.1.205, catalog packages and locally installed tool packages appear as two cards side by side, each with an icon. The installed package icon is used when available; otherwise a toolbox icon is shown. Refresh, removal and existing tool actions remain available.

Since 0.1.206, the more compact Local / Catalog / GitHub selector stays visible at the top while scrolling. The entire tab uses one shared scroll area; catalog and installed package lists no longer have nested scroll areas.

From Studio 0.1.204, Settings → Tools offers Local / Catalog / GitHub sources. The catalog shows licenses, descriptions, minimum Studio versions and installation status, including Colorpicker and Tools Test. GitHub requires a direct public .tp file link. Risk confirmation is required before installation; catalog downloads verify SHA-256 and the selected package ID/version. Settings remain open, and the package list and toolbar refresh immediately. An explicitly selected newer tool version can replace the existing version; equal or older versions are rejected. Projects and Colorpicker favorites are retained. The standalone Packer is available under Helper tools on the catalog website.

Packages and helper tools are provided centrally at visualstudio.ugso-software.de. This open-source page provides descriptions and instructions; downloads are provided by the package catalog.

Starting with Studio 0.1.89, you can install ZIP-based packages ending in .tp. Existing .tp.zip files remain supported; the extension and manifest must both identify a tool package.

Under Settings → Tools, you can install a local *.tp.zip. Installed tools also appear as icons in two rows of the editor toolbar; its toolbox icon opens the Tools tab for management. Tool packages extend the editor, not the widget palette or runtime. Interface 0.1 supports one declarative action: setting the current page's background color. Clicking a toolbar tool icon or Run in the Tools tab opens a preview; only Apply commits the change. Undo can revert it, and normal project saving persists it. Installation itself does not run an action.

UGSo Colorpicker 1.2.0

Starting with Studio 0.1.113, Colorpicker and Favorites retain the same dialog size when switching tabs. Favorites use two columns on larger screens and one column on narrow screens. Longer lists scroll within the tab. Existing tool installations only require the Studio update.

Update 1.2.0 (Studio 0.1.112): Save favorite is available alongside Copy. The separate Favorites tab holds up to 15 colors with HEX and names, automatically stored in add-on data and shared across HA administrator browsers through Ingress. Regular users can use the picker but cannot access favorites. Duplicate colors do not consume another slot. At capacity, a yellow Favorites full message appears and Save is disabled. Each entry has an SVG button to copy its HEX value and a trash button. Deleting shifts later entries forward. Selecting a color returns it to the picker. Opening the Favorites tab reloads the shared list.

Import local favorites merges the previous browser list into the shared list. Colors that do not fit remain locally stored. Tool updates or reinstalls do not delete favorites. Back up add-on data before uninstalling the add-on or migrating servers. If the administrator check is unavailable, reopen Studio through Home Assistant; favorites are not stored locally as a fallback.

Download Colorpicker 1.2.0.

This tool requires HA Grafik Visual Studio 0.1.112 or newer. Install the downloaded .tp file under Settings → Tools. Existing Colorpicker installations receive the new dialog by updating Studio. Open the color-wheel toolbar icon or click Run.

• Choose hue and saturation on the wheel; adjust brightness separately or enter HEX directly.
• Select HEX or Color name and click Copy. If browser clipboard access is unavailable, select and copy the output manually.
• The 31,918 names from meodai/color-names are bundled locally; no internet connection is required. Exact and nearest matches are distinguished using RGB distance.
• Names are labels, not CSS color values. Copy HEX for widget color fields.
• The picker does not modify projects and requires no project permissions. Shared favorites require HA administrator rights. Left/right arrow keys change hue and up/down change saturation on the wheel.

The new declarative color-picker action uses capabilities: []. Studio supplies the dialog and color-name data; the data-only package activates the tool. Older Studio versions do not support this action. License and attribution links are available in the dialog. The existing set-page-background action remains unchanged.

Build a package

The ZIP contains a UTF-8 manifest.json and optionally referenced SVG or PNG images under icons/. No other files are allowed. Package IDs use dot-separated parts; the tool ID uses the package namespace. Package versions have the form x.y.z. A tool package contains exactly one tool.

{
  "format": "ha-grafik-tool-package",
  "apiVersion": "0.1",
  "id": "example.tools",
  "name": "Example Tools",
  "version": "1.0.0",
  "license": "MIT",
  "tools": [{
    "id": "example.tools/background",
    "definitionVersion": "0.1",
    "label": "Page color",
    "description": "Sets the current page background.",
    "context": "page",
    "capabilities": ["project.read", "project.write"],
    "action": { "kind": "set-page-background", "defaultColor": "#224466" }
  }]
}

defaultColor is a six-digit hex color and can be changed in the preview. The listed capabilities apply only to this confirmed editor action; they do not grant package code general write access. A package or tool may optionally reference "icon": "icons/name.svg" or .png. The file must be present in the ZIP; Studio action buttons continue to use SVG symbols.

The ZIP limit is 2 MB, the manifest limit is 200 KB, and each image is limited to 50 KB. PNG images are limited to 1024 × 1024 pixels; SVG files are checked for inert content.

Install and manage

1. Create a ZIP such as page-color.tp with manifest.json and any referenced images. page-color.tp.zip remains supported.
2. Select it under Settings → Tools. The list shows the package ID, version, license and included tool.
3. Open the preview from the tool icon in the editor toolbar or with Run in the Tools tab, then confirm the page change with Apply.

Packages can be removed from the Tools tab. Custom scripts, Home Assistant services, external URLs, GitHub installation and updates are not part of 0.1 yet. See the planned compatibility and extension points in the tool rules in the source repository.