widget-workshop-dev

name	widget-workshop-dev
description	Use when creating or editing Widget Workshop component source folders, manifest.json, index.html, settings files, locale files, preview assets, styling, or runtime component code.

Widget Workshop Dev

Overview

Use this Skill to build the component package itself. Keep implementation tied to the redesigned creator-facing docs and validate the source folder after changing package files.

Component Shape

Start from a source folder outside installed app-data runtime copies:

my-component/
  manifest.json
  index.html
  preview.png
  locales/en-US.json
  locales/zh-CN.json
  scripts/settings.json

Only manifest.json, index.html, and a preview image are always required. Locale files are read only when localization is enabled, and settings files are read only when declared by the manifest.

Build Flow

1. Read docs/zh-CN/component-quickstart.md, docs/zh-CN/manifest-reference.md, and docs/zh-CN/settings-reference.md; use docs/en-US as the mirrored English structure.
2. Create or update manifest.json before writing runtime code.
3. Add index.html as the fixed entry.
4. Add a package-relative .png, .jpg, or .jpeg preview.
5. Add locales/<language>.json only when locales.enable is true or an old manifest declares locales.default and locales.supported without enable; otherwise keep visible text in index.html.
6. Add scripts/settings.json only when hasCustomSettings is true; every settings field needs a compatible default.
7. Use widget-workshop-api for every window.widgetWorkshop call and permission decision.
8. Run component validation and re-import the component after package file changes.

Runtime Code Rules

• Wait for the page to load before reading window.widgetWorkshop.
• Read settings with window.widgetWorkshop.host.getComponentSettings().
• Use app.getLocaleInfo() for locale decisions.
• Wrap Host API calls in try/catch and show useful degraded UI when a capability is unavailable.
• Keep all package paths relative and inside the component folder.
• Keep drag regions inside windowSize; if dragArea is missing, the whole unlocked window can drag.
• Keep visual behavior self-contained in the component; do not require host app changes for normal package work.

Example Host API Pattern

<script>
async function loadComponent() {
  const api = window.widgetWorkshop;
  try {
    const [context, settings, grants] = await Promise.all([
      api.host.getComponentContext(),
      api.host.getComponentSettings(),
      api.host.getPermissionGrants()
    ]);
    document.body.dataset.packageId = context.packageId;
    document.body.style.setProperty("--accent", settings.accentColor || "#3B82F6");
    document.body.classList.toggle("can-fetch", grants.fetch === true);
  } catch (error) {
    document.body.classList.add("host-api-unavailable");
  }
}
window.addEventListener("DOMContentLoaded", loadComponent);
</script>

Common Mistakes

Mistake	Fix
Editing an installed runtime copy	Edit the source folder and re-import
Adding unsupported manifest compatibility fields	Follow schemas/manifest.schema.json
Setting hasCustomSettings without scripts/settings.json	Add the settings schema or set the flag to false
Adding locale files without enabling localization	Set locales.enable: true or remove the locale files
Calling gated APIs without UI fallback	Check grants and handle rejected promises
Changing docs or contracts for one language only	Keep docs/en-US and docs/zh-CN mirrored