@atomm-developer/generator-workbench 0.1.7 → 0.1.9

package/README.md

@@ -5,7 +5,7 @@
 V1 provides:
 
 - Web Component shell
-- login / avatar / logout entry
+- guest avatar / login / avatar / logout entry
 - credits badge and export credit hint
 - built-in invitation action backed by `@atomm/atomm-pro` `InvitationModal`
 - local template import entry and template publish modal
@@ -82,7 +82,7 @@ workbench.config = {
 
 ## Invitation Modal
 
-By default, the shell adds an `Earn Credits` button to the left of the top-bar credits badge after login.
+By default, the shell adds an `Earn Credits` button to the left of the top-bar credits badge. When the user is logged out, the top bar also shows a 40x40 guest avatar instead of a text `Login` button.
 
 ```js
 workbench.config = {
@@ -92,11 +92,10 @@ workbench.config = {
 }
 ```
 
-`generator-workbench` will then auto-load `Pinia`, `Vue Router`, `Vue I18n`, and the bundled `atomm-pro` browser assets, mount `XtAtommProContext` inside the shell, and call `InvitationModal.open({ configKey })` when the user clicks the button.
+`generator-workbench` will then auto-load `Pinia`, `Vue Router`, `Vue I18n`, and the bundled `atomm-pro` browser assets, mount `XtAtommProContext` inside the shell, and call `InvitationModal.open({ configKey })` when the user clicks the button. If the user is still logged out, the shell first calls `sdk.auth.login()` and opens the invitation/share modal right after login completes.
 
 Notes:
 
-- `InvitationModal` depends on a real login token, so the button is only shown after `sdk.auth` reports `isLogin = true`.
 - If you need to hide the invite entry, explicitly pass `invitationEnabled: false`.
 - If `invitationConfigKey` is omitted, the shell defaults it to `generator_${sdk.getAppKey()}`.
 - If you still need a custom referral/share key, you can explicitly pass `invitationConfigKey`.
@@ -108,6 +107,38 @@ Notes:
 - `mode: 'full'` keeps the classic shell with the top bar plus the built-in right sidebar layout for separate canvas / panel mounting.
 - `mode: 'template'` hides the top bar, keeps `#sidebar-footer`, and is useful when the host page already owns branding and login UI.
 
+The shell layout mode above is different from the route capability mode. When the page URL contains `?mode=embed`, `generator-workbench` keeps the current layout mode but force-disables shell integrations for:
+
+- cloud save
+- history
+- credits badge / export credits hint
+- billing-backed export consumption
+- invitation / earn credits entry
+
+This is useful when the host site embeds a generator inside an `iframe` and wants a lighter shell surface. If the route omits `mode` or uses `mode=full`, the existing shell behavior stays unchanged.
+
+In this embed route, the shell also removes the top bar and `#sidebar-footer` export container from the DOM entirely. The underlying workbench methods and bridge actions still exist, but the shell chrome is no longer rendered inside the iframe.
+
+When `?mode=embed` is active, the workbench also boots an iframe bridge compatible with the main-site generator protocol:
+
+- outgoing ready signal: `generator_pageLoaded`
+- incoming host commands: `generator_loadTemplateData`, `generator_setGeneratorData`, `generator_getTemplateData`, `generator_getGeneratorData`, `generator_getFile`
+- outgoing result events: `generator_toTemplateLoaded`, `generator_toTemplateData`, `generator_toGeneratorData`, `generator_toFile`, `generator_toFileError`, `generator_toTemplateError`
+
+Default bridge mappings:
+
+- `generator_loadTemplateData` applies the incoming template through `sdk.template.applyToRuntime(...)`
+- `generator_setGeneratorData` restores `data.info` back into `runtime.setState(...)`
+- `generator_getTemplateData` builds a fresh template from the current runtime state and returns `{ template, info, cover, originImageUrl }`
+- `generator_getFile` reads export data from `config.embedBridge.getExportData(...)` first, then falls back to the SDK export provider registered through `sdk.export.register(...)`
+
+If the host needs stricter control, pass `config.embedBridge`:
+
+- `targetOrigin`: override the default `postMessage(..., '*')`
+- `validateOrigin(origin, event)`: filter incoming parent messages
+- `getExportData(action, context)`: provide bridge export data explicitly
+- `getOriginImageUrl(context)`: return the origin image URL stored by the host/runtime
+
 In `template` mode, the host shell can pass an external token into the workbench:
 
 ```js
@@ -120,7 +151,8 @@ This writes the token to `localStorage` using the SDK app key and then syncs the
 
 - When `sdk.credits` and `sdk.billing` are available, the top bar shows the current credits balance after login.
 - The export trigger reads `sdk.billing.getUsage()` and hides the hint completely when `usage.isEnabled = false`.
-- When billing is enabled, the hint switches between `free N`, `creditsPerUse`, and the `30s` free-period countdown.
+- When billing is enabled, the hint switches between `freeRemaining/freeTotal`, `creditsPerUse`, and the `30s` free-period countdown.
+- When free quota remains, the export hint hides the credits token icon and only shows the `remaining/total` text.
 - When free quota is exhausted, `exportSvg()` and `openInStudio()` compare `usage.creditsPerUse` with `usage.creditsBalance`; if balance is insufficient, they open the `@atomm/atomm-pro` credits purchase modal before retrying the export path.
 - `exportSvg()` and `openInStudio()` export first, then call `sdk.billing.consume()` on success; the credits path also calls `sdk.billing.refreshCredits()`.
 
@@ -144,6 +176,8 @@ When `cloudEnabled` is on, the workbench now also supports a route-based bootstr
 - if the page URL contains `?gid=<id>`, mount will call `sdk.cloud.restore(id)` and write the restored snapshot back through `runtime.setState(...)`
 - if `gid` is missing, mount will call `sdk.cloud.save(...)` once and write the returned id back into the current route as `gid`
 
+If the page route contains `?mode=embed`, this cloud bootstrap flow is skipped even when `cloudEnabled` was set by the host config.
+
 Cloud/history events are also emitted as DOM custom events:
 
 - `cloud-save-start`

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { BillingConsumeResult } from '@atomm-developer/generator-sdk';
 import { CloudRecord } from '@atomm-developer/generator-sdk';
 import { CloudSaveOptions } from '@atomm-developer/generator-sdk';
 import { CloudSaveResult } from '@atomm-developer/generator-sdk';
+import { ExportData } from '@atomm-developer/generator-sdk';
 import { ExportDownloadResult } from '@atomm-developer/generator-sdk';
 import { ExportOpenInStudioResult } from '@atomm-developer/generator-sdk';
 import { GeneratorTemplateDefinition } from '@atomm-developer/generator-sdk';
@@ -137,6 +138,7 @@ export declare interface GeneratorWorkbenchConfig {
     autoMount?: boolean;
     panelTarget?: 'left' | 'right';
     avatarMenuTrigger?: 'hover' | 'click';
+    embedBridge?: GeneratorWorkbenchEmbedBridgeConfig;
     /** Override the default Vue 3 CDN script URL auto-loaded when window.Vue is absent */
     vueScriptUrl?: string;
     /** Override the default Vue Router CDN script URL auto-loaded for invitation modal support */
@@ -188,6 +190,7 @@ export declare class GeneratorWorkbenchElement extends HTMLElement {
     private _historyController?;
     private _runtimeController?;
     private _shellContext?;
+    private _iframeBridge?;
     constructor();
     get sdk(): GeneratorSDKLike | null;
     set sdk(value: GeneratorSDKLike | null);
@@ -221,7 +224,10 @@ export declare class GeneratorWorkbenchElement extends HTMLElement {
     private openHistoryDialog;
     private closeHistoryDialog;
     private toggleTemplateExportField;
+    private applyTemplatePayload;
+    private tryResolveIframeBridgeFile;
     private bindAuthState;
+    private bindIframeBridge;
     private bindAutoSave;
     private bindRuntimeCloudSaveEvent;
     private readonly handleRuntimeCloudSaveRequest;
@@ -243,7 +249,10 @@ export declare class GeneratorWorkbenchElement extends HTMLElement {
     private clearBillingCountdownTimer;
     private syncBillingCountdown;
     private syncBillingState;
+    private getEffectiveConfig;
+    private getEffectiveSdk;
     private handleLogin;
+    private handleInvitationEntry;
     private handleLogout;
     private handleError;
     private requireRefs;
@@ -254,6 +263,15 @@ export declare class GeneratorWorkbenchElement extends HTMLElement {
     private requireHistoryController;
 }
 
+export declare interface GeneratorWorkbenchEmbedBridgeConfig {
+    targetOrigin?: string;
+    validateOrigin?: (origin: string, event: MessageEvent) => boolean;
+    getOriginImageUrl?: (context: GeneratorWorkbenchActionHookContext) => Promise<string> | string;
+    getExportData?: (action: GeneratorWorkbenchEmbedBridgeFileAction, context: GeneratorWorkbenchActionHookContext) => Promise<ExportData | null> | ExportData | null;
+}
+
+export declare type GeneratorWorkbenchEmbedBridgeFileAction = 'download' | 'openInStudio' | 'cover';
+
 declare interface GeneratorWorkbenchHistoryContext extends GeneratorWorkbenchActionHookContext {
     itemId: number;
 }