Generator Workbench Upgrade

generator-workbench can be delivered by CDN, but CDN updates alone do not guarantee that every existing generator has fully adopted a new shell capability.

This page defines the upgrade model for generator-workbench, explains how to read the CDN-published upgrade-manifest.json first, and gives generator owners a repeatable checklist for upgrading old integrations.

Why This Page Exists

When a generator loads:

• generator-sdk by CDN
• generator-workbench by CDN

the shell bundle can update automatically after a new release is published.

However, some new capabilities are not shell-only. They may also require:

• new host config
• new runtime events
• new CDN assets
• new route behavior
• new generator-side smoke tests

This is the main reason an old generator can "see the new workbench version" while still failing to use the new capability correctly.

The Three Upgrade Classes

Every generator-workbench release should classify new behavior into one of three buckets.

1. Auto-Adopted

These capabilities stay fully inside generator-workbench.

Examples:

• shell-only UI fixes
• internal billing flow fixes
• non-breaking shell rendering improvements

For these, updating the CDN script is usually enough.

2. Host-Action-Required

These capabilities require the generator host page or workbench host glue to change.

Examples:

• enabling cloudEnabled or historyEnabled
• adding atommProEnv or atommProDomain
• providing atommProScriptUrl and atommProCssUrl for CDN integrations
• exposing new host helpers such as saveToCloud()

For these, updating the CDN script is not enough. The generator host integration must also be updated.

3. Runtime-Action-Required

These capabilities require the generator runtime contract or runtime-side event flow to change.

Examples:

• making runtime.getState() stable before mount-time cloud bootstrap
• implementing subscribe(listener) correctly
• emitting runtime-visible state changes for template switching
• dispatching runtime-cloud-save-request when a custom cloud save payload is needed

For these, the generator runtime or runtime adapter must be updated explicitly.

Source Of Truth: upgrade-manifest.json

Upgrade metadata is published at:

https://static-res.atomm.com/scripts/js/generator-sdk/generator-workbench/upgrade-manifest.json

If the CDN manifest cannot be read temporarily, fall back to MCP upgrade documentation instead of assuming the change is shell-only.

This file is intended to be machine-readable so that:

• docs can explain upgrade requirements consistently
• MCP tools can query upgrade requirements
• the existing creating-generators skill can eventually audit generators against workbench releases
• generator owners can build repeatable upgrade checks

Manifest Structure

The manifest keeps:

• the latest known workbench version
• the public guide page for upgrades
• release-by-release upgrade entries
• per-release capability classification
• required host/runtime actions
• CDN asset requirements
• generator validation checklist items

Example shape:

{
  "schemaVersion": "1.0.0",
  "packageName": "@atomm-developer/generator-workbench",
  "latestVersion": "0.1.21",
  "releases": [
    {
      "version": "0.1.21",
      "previousVersion": "0.1.20",
      "autoAdoptedCapabilities": [],
      "adoptionRequirements": [],
      "cdnAssets": [],
      "generatorChecklist": []
    }
  ]
}

Recommended Upgrade Workflow

When a generator is already using generator-workbench by CDN, upgrade in this order:

1. Identify the generator's current workbench version.
2. Read the target release entry from the CDN upgrade-manifest.json.
3. Split new capabilities into:
   • auto-adopted
   • host-action-required
   • runtime-action-required
4. Update the generator's CDN URLs only after understanding whether host/runtime changes are also required.
5. Update the generator host glue code.
6. Update the generator runtime or runtime adapter when required.
7. Run generator-side smoke tests for the affected capabilities.

What CDN Can And Cannot Do

CDN Can Update

• the workbench bundle itself
• shell-only bug fixes
• shell-only UI improvements
• internal shell orchestration that does not change the host/runtime contract

CDN Cannot Automatically Update

• generator-local workbench-host.js
• runtime adapters
• runtime event emission
• route bootstrap strategy
• generator-side tests

This distinction is critical for old generators such as flag, where the shell updated but the host/runtime contract did not.

Example: 0.1.20 To 0.1.21

The 0.1.21 manifest entry is a practical example of a publish-reopen behavior release: the shell now caches the first-open generatorImage and generatorTag, reuses the first uploaded OSS preview URL on later opens, and stops resetting the shared PublishTemplateModal automatically when the user closes and reopens it.

Auto-Adopted In 0.1.21

• on the first Publish as Template open, the shell now caches the resolved generatorImage and generatorTag for the current workbench instance
• if that first generatorImage is local image data, the shell uploads it once, caches the returned OSS URL, and reuses that URL for later opens instead of re-uploading the original base64 payload
• reopening the shared atomm-pro publish modal no longer calls resetForm() automatically, so draft form inputs are preserved by default after close and reopen

Host-Action-Required In 0.1.21

• for standard generator integrations, none; upgrading the shell bundle is usually enough to get the new reopen behavior
• if custom host glue, browser tests, or wrappers assumed that reopen clears the publish form automatically, update those assumptions and assertions
• if custom wrappers expected later runtime select_template or template_publish_media_change events to replace generatorTag or generatorImage after the first publish open, update those expectations because the first-open values now remain cached for the current workbench instance

Runtime-Action-Required In 0.1.21

• none; this release does not change the public runtime event contract

This is why 0.1.21 is mostly a CDN-only upgrade with one important behavioral caveat:

• the caching and default no-reset logic both live inside generator-workbench
• most generators only need the upgraded bundle to benefit from fewer repeated preview uploads and preserved draft form state
• custom wrappers, browser tests, or manual publish orchestration that depended on automatic reset or fresh runtime publish identity after reopen should be refreshed explicitly

Earlier Example: 0.1.18 To 0.1.20

The 0.1.20 manifest entry is a practical example of an almost fully auto-adopted performance release: the shell now splits shell-ready and runtime-ready timing, moves billing sync plus Atomm Pro assets off the first-render critical path, and makes stylesheet loading non-blocking so existing generators spend less time on a blank screen before the shell appears.

Auto-Adopted In 0.1.20

• the shell now exposes staged readiness timing for shell-ready and runtime-ready while keeping the older ready flow compatible for existing generators
• syncBillingState, atomm-pro runtime loading, and non-critical CSS work are now pushed later so they no longer block the initial shell render
• atomm-ui CSS now uses a single non-blocking fetch path plus a shared global style registry, reducing duplicate global style work across multiple workbench instances
• when invitation, Publish as Template, or credits purchase is enabled, atomm-pro.css is preloaded asynchronously in the background and the shared modal waits for that stylesheet before first open, fixing the earlier first-open style loss

Host-Action-Required In 0.1.20

• for standard generator integrations, none; upgrading the workbench bundle is usually enough to get the white-screen reduction
• only custom host glue, browser tests, or wrappers that inspect PublishTemplateModal.open(...) params need to update their reads from params.style to params.initialData.style
• keep passing workbench.config.style exactly as before when the generator wants a fixed or runtime-derived publish style; the host config field itself did not change

Runtime-Action-Required In 0.1.20

• none; this release does not change the public runtime event contract

This is why 0.1.20 is close to a CDN-only upgrade for most existing generators:

• the blank-screen optimization itself stays inside generator-workbench
• most generators only need the upgraded bundle to benefit from the earlier shell render and non-blocking asset loading
• the only compatibility caveat is custom code that directly inspects publish modal open params and still expects a top-level style field

Earlier Example: 0.1.17 To 0.1.18

The 0.1.18 manifest entry is a practical example of a mixed shell-plus-host release: the shell now preserves workbench.config.style through the full Publish as Template flow, including the final /community/v2/web/making/template submit request, and the topbar logo now jumps to the Atomm home page.

Auto-Adopted In 0.1.18

• if the host already passes workbench.config.style, the shell now keeps that value on both PublishTemplateModal.open(...) and the final submit request even when the shared atomm-pro modal omits style while submitting
• clicking the shell logo now navigates the current page to Atomm
• these changes stay inside generator-workbench; no changes are required inside @atomm/atomm-pro

Host-Action-Required In 0.1.18

• pass workbench.config.style before workbench.mount() when the generator expects a fixed or runtime-derived style value to survive the entire publish flow
• if runtime state owns the style mode, bridge it explicitly in host glue, for example by reading runtime.getState().style and writing that value into workbench.config.style
• do not assume generator-workbench will auto-read arbitrary runtime fields during initialization; the host still owns the initial style bridge

Runtime-Action-Required In 0.1.18

• none; this release does not change the public runtime event contract

This is why 0.1.18 is not a purely invisible CDN-only upgrade for every generator:

• the submit-time style preservation lives inside generator-workbench
• but generators only benefit from it after the host actually passes workbench.config.style
• generator owners should smoke-test both the modal open params and the final publish submit request when they rely on a publish-facing style value

Earlier Example: 0.1.16 To 0.1.17

The 0.1.17 manifest entry is a practical example of a route-bootstrap release: when a workbench page opens without gid but with templateId, the shell now reads the community making detail payload, logs the response plus data.generatorInfo.info, and restores that info object into the runtime before it falls back to creating a fresh cloud record.

Auto-Adopted In 0.1.17

• if the route has templateId and no gid, the shell now requests /community/v1/web/making/:id automatically
• the shell logs both the making payload and data.generatorInfo.info, then restores that info object into runtime state with the same cloud-history source used by gid restore
• routes that already include gid still keep gid restore priority and skip the template bootstrap request

Host-Action-Required In 0.1.17

• update host route builders when the generator should bootstrap from a community/template entry by appending templateId=<making id>
• append env=dev|test|prod when the host needs to pin the making API environment explicitly; otherwise the shell falls back to config.atommProEnv
• keep gid on routes that should restore an existing cloud draft instead of replaying template bootstrap data

Runtime-Action-Required In 0.1.17

• none; this release does not change the public runtime event contract

This is why 0.1.17 is not a fully invisible CDN-only upgrade for every generator:

• the runtime restore behavior itself lives inside generator-workbench
• but generators only get the new bootstrap path after the host actually constructs templateId routes
• generator owners should smoke-test both templateId and gid routes because route identity now decides which restore source wins

Earlier Example: 0.1.15 To 0.1.16

The 0.1.16 manifest entry is a practical example of a shell-only publish hardening release: before the shared atomm-pro modal submits create or update requests, generator-workbench now uploads any local image data still present in top-level cover or generatorInfo.cover to OSS and replaces those fields with remote URLs.

Auto-Adopted In 0.1.16

• if the publish payload still carries local image data for cover or generatorInfo.cover, the shell now uploads it to OSS automatically before the final template request is sent
• when both fields point at the same local image source, the shell reuses one upload result for both payload locations
• downstream publish APIs now receive remote cover URLs instead of raw local image data at submit time

Host-Action-Required In 0.1.16

• none; this release does not require new host config

Runtime-Action-Required In 0.1.16

• none; this release does not change the public runtime event contract

This is why 0.1.16 is a practical CDN-only upgrade:

• the upload hardening lives inside the workbench publish bridge
• existing generators still open the same shared atomm-pro publish modal
• generator owners should still smoke-test publish flows that rely on shell-resolved covers or runtime cover overrides, because the submitted cover value is now normalized to an OSS URL

Earlier Example: 0.1.14 To 0.1.15

The 0.1.15 manifest entry is a practical example of a template-publish payload contract refresh: the shell now normalizes generatorInfo to { appKey, generatorCode, generatorName, info, template, cover, originImageUrl } and lets the runtime override generatorImage and initialData.cover through template_publish_media_change.

Auto-Adopted In 0.1.15

• generatorInfo.generatorCode now aligns with appKey
• generatorInfo.generatorName now mirrors the resolved template meta title, falling back to config.title
• generatorInfo.info is now rebuilt from the latest runtime state using the same info structure expected by sdk.cloud.save(...)
• the older generatorId, panelSchema, selectedFieldPaths, state, and templateMeta fields no longer appear inside the publish payload's generatorInfo

Host-Action-Required In 0.1.15

• none; this release does not require new host config

Runtime-Action-Required In 0.1.15

• if the generator runtime should own template publish images, keep runtime.subscribe(listener) and emit:
• template_publish_media_change
• the event payload shape is { data: { generatorImage?: string, cover?: string } }

This is why 0.1.15 is not a fully invisible upgrade for every generator:

• generators that only rely on the standard shell publish entry get the new generatorInfo contract automatically
• generators whose runtime must push custom publish preview images still need to emit the new runtime event
• any downstream consumer that still expects the old generatorInfo shape must update its parsing logic

Earlier Example: 0.1.13 To 0.1.14

The 0.1.14 manifest entry demonstrates a shell-only runtime-first release: the shell now mounts the runtime first and moves route-level cloud bootstrap into a background step, so login or cloud latency no longer blocks the initial runtime render.

Current releases go one step further for logged-out gid routes:

• mount still renders runtime first
• if the route already contains gid but there is no local token yet, the shell no longer auto-restores that cloud record
• after a later explicit login, the shell binds that gid for future saves instead of auto-restoring server content back into runtime state
• first-time cloud record creation is also deferred until an explicit save when the user enters logged out

Auto-Adopted In 0.1.14

• the runtime canvas/panel or workspace now mounts before gid restore or first cloud save finishes
• a dismissed or failed login flow during cloud bootstrap no longer keeps the runtime blank
• the shell now coordinates the first background cloud record creation with later saves so a fresh route is less likely to create duplicate drafts

Host-Action-Required In 0.1.14

• none; this release changes shell-side mount sequencing only

Runtime-Action-Required In 0.1.14

• none; this release does not change the public runtime contract

This is why 0.1.14 is a practical CDN-only upgrade:

• the fix lives inside generator-workbench mount orchestration
• existing generators do not need to add new host config or runtime events
• generator owners should still regression-test fresh routes, gid restore routes, and logged-out entry flows because the render/bootstrap timing changed

Earlier Example: 0.1.11 To 0.1.12

The 0.1.12 manifest entry demonstrates a host-adoption release: the shell now exports createAtommProHostI18nConfig(), but existing generators still need to wire that helper or pass an equivalent atommProLocale / atommProMessages pair when they use invite, earn-credits, purchase, or template-publish flows.

Auto-Adopted In 0.1.12

• none; this release adds a reusable host-side starter config, but existing generators do not get translated atomm-pro UI automatically just by replacing the CDN asset

Host-Action-Required In 0.1.12

• import createAtommProHostI18nConfig() from @atomm-developer/generator-workbench and spread it into workbench.config, or provide an equivalent atommProLocale + atommProMessages pair manually
• ensure the host-provided message set covers the shared atomm-pro namespaces used by:
  • invitation / referral share UI
  • credits purchase / recharge UI
  • template publish UI
• if the generator already overrides atomm-pro copy, merge those overrides on top of the new starter config instead of deleting the newly required keys

Runtime-Action-Required In 0.1.12

• none; this release does not change the runtime contract

This is why 0.1.12 is not a "CDN-only" upgrade for generators that expose atomm-pro UI:

• the shell bundle now exports a standard host i18n starter for atomm-pro
• but invite and purchase flows still render raw i18n keys until the host actually passes the required locale/messages
• generators that do not expose any atomm-pro invite / purchase / publish surface can usually treat this release as non-blocking

Earlier Example: 0.1.10 To 0.1.11

The 0.1.11 manifest entry demonstrates a publish-flow release: the shell now opens the shared @atomm/atomm-pro publish modal directly, while generators can optionally drive generatorTag from runtime select_template events.

Auto-Adopted In 0.1.11

• clicking the template entry now opens @atomm/atomm-pro PublishTemplateModal instead of stopping at a shell-only field picker
• the shell now maps runtime state, template JSON, cover/origin image data, and template metadata into the publish modal payload automatically
• generators already using the standard workbench template entry get this modal integration immediately after upgrading the shell bundle

Host-Action-Required In 0.1.11

• host-side work is optional, but recommended when the publish modal needs prefilled summary, contentTags, a stable generatorInfo.generatorName, or a fallback generatorTag
• pass those defaults through workbench.config.getTemplateMeta()
• treat getTemplateMeta().generatorTag as the fallback only; runtime select_template.data.name now has higher priority when present

Runtime-Action-Required In 0.1.11

• keep runtime.subscribe(listener) as the standard runtime -> workbench event channel
• emit select_template with { data: { name, category? } } whenever runtime template choice changes and the publish modal tag should follow that choice
• ensure data.name is the final tag text expected by the publish modal, because the shell now reuses the latest emitted name as publishParams.generatorTag
• keep other runtime events such as params_change or state-change when existing shell integrations still depend on them

This is why 0.1.11 is not a "CDN-only" upgrade for every generator:

• the shell bundle now contains the atomm-pro publish modal integration
• but runtime-driven generatorTag only works after the generator emits select_template with the expected data.name
• generators that do not need runtime-driven tags can still upgrade the shell first and rely on getTemplateMeta().generatorTag as the fallback

Generator Owner Checklist

When a new release introduces host/runtime adoption requirements, check all of the following:

• Is this capability auto-adopted or does it require host/runtime work?
• Does the generator explicitly pass the new workbench.config fields?
• Does the runtime read routeMode when embed/full route capability affects runtime behavior?
• Does the runtime expose subscribe(listener)?
• Does the runtime emit select_template or params_change when the shell or host is expected to observe those business events?
• If the host needs reverse commands, is workbench.dispatchRuntimeCommand(...) wired together with runtime.dispatchWorkbenchCommand(...)?
• Does the runtime emit observable state changes for runtime-owned edits?
• If custom save payloads are needed, does the runtime dispatch runtime-cloud-save-request?
• If cloud route bootstrap is enabled, can runtime.getState() be called safely before the real child runtime is mounted?
• If invite or purchase UI is enabled, are the required atomm-pro CDN assets reachable?
• Does the generator have smoke tests that cover the new capability?

How This Connects To MCP And Skills

This page and the manifest are intentionally designed so the existing generator-sdk-mcp/skills/creating-generators workflow can be extended later without creating a new skill.

The intended future flow is:

1. the skill detects that the task is an old-generator refactor or workbench upgrade
2. it reads https://static-res.atomm.com/scripts/js/generator-sdk/generator-workbench/upgrade-manifest.json
3. if the CDN manifest cannot be read, it falls back to MCP documentation
4. it scans the target generator for required host/runtime markers
5. it outputs a generator-specific upgrade checklist

That means the upgrade logic should live in:

• this guide page
• the manifest
• existing creating-generators guidance

not in a separate explosion of new skills.

Publish Guidance

When generator-workbench adds, removes, or changes capabilities, update all of the following in the same release task:

• https://static-res.atomm.com/scripts/js/generator-sdk/generator-workbench/upgrade-manifest.json
• this guide page
• docs/zh/guide/generator-workbench-upgrade.md
• docs/guide/generator-workbench.md and docs/zh/guide/generator-workbench.md when shell behavior changes
• docs/guide/generator-workbench-runtime-communication.md and docs/zh/guide/generator-workbench-runtime-communication.md when the communication contract changes
• any MCP knowledge or skill reference that describes the affected integration path

Related Pages

• Generator Workbench
• Workbench Runtime Communication
• Developer Journey
• Installation
• Runtime Contract