Beautiful Open-Source Form Builder
fix(mcp): make guest previews read-only (#1274)
Julien Nahum3cda32d97017
diff --git a/api/app/Mcp/Apps/FormDraftPreviewApp.php b/api/app/Mcp/Apps/FormDraftPreviewApp.phpindex 395aaef13..0f718dad1 100644--- a/api/app/Mcp/Apps/FormDraftPreviewApp.php+++ b/api/app/Mcp/Apps/FormDraftPreviewApp.php@@ -13,8 +13,8 @@ use Laravel\Mcp\Server\Ui\AppMeta;use Laravel\Mcp\Server\Ui\Csp;#[Name('form_draft_preview')]-#[Description('Interactive preview of a guest OpnForm draft with a secure editor handoff.')]-#[Uri('ui://opnform/form-draft-preview-v3')]+#[Description('Interactive preview of a temporary guest OpnForm draft with an optional editor handoff.')]+#[Uri('ui://opnform/form-draft-preview-v4')]class FormDraftPreviewApp extends AppResource{public function shouldRegister(McpAvailability $availability): booldiff --git a/api/app/Mcp/Tools/CreateFormDraftTool.php b/api/app/Mcp/Tools/CreateFormDraftTool.phpindex 64c5a7021..62a3818d7 100644--- a/api/app/Mcp/Tools/CreateFormDraftTool.php+++ b/api/app/Mcp/Tools/CreateFormDraftTool.php@@ -18,7 +18,7 @@ use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;#[Name('create_form_draft')]#[Title('Create a Guest Form Draft')]-#[Description('Use this as the default creation tool whenever the user asks to create, build, or preview a new form without explicitly asking to save it in an OpnForm account or workspace. It works immediately without login; never request authentication or use create_form_in_account instead for this guest-first workflow. Creates a private unpublished draft that expires after seven days and returns a capability token once; keep it private and use it with get_form_draft, patch_form_draft, and preview_form_draft.')]+#[Description('Use this as the default creation tool whenever the user asks to create, build, or preview a new form without explicitly asking to save it in an OpnForm account or workspace. It works immediately without login; never request authentication or use create_form_in_account instead for this guest-first workflow. Creates a temporary unpublished draft that expires after seven days and returns an opaque draft handle for get_form_draft, patch_form_draft, and preview_form_draft.')]#[IsReadOnly(false)]#[IsDestructive(false)]#[IsOpenWorld(false)]@@ -41,10 +41,10 @@ class CreateFormDraftTool extends GuestDraftMcpTool$created = $drafts->create($validated['definition']);return Response::structured([- 'draft_token' => $created['token'],+ 'draft_handle' => $created['token'],'draft' => $drafts->serialize($created['draft']),'next_steps' => [- 'Keep draft_token private; it grants access to this draft.',+ 'Pass draft_handle unchanged to guest draft tools. Do not display this internal handle to the user.','Use patch_form_draft with expected_version for changes.','Render a preview before asking the user to claim or publish the form.',],@@ -63,7 +63,11 @@ class CreateFormDraftTool extends GuestDraftMcpToolpublic function outputSchema(JsonSchema $schema): array{return [- 'draft_token' => $schema->string()->min(43)->max(43)->required(),+ 'draft_handle' => $schema->string()+ ->description('Opaque reference for this temporary draft. Pass it unchanged to guest draft tools.')+ ->min(43)+ ->max(43)+ ->required(),'draft' => McpOutputSchema::draft($schema)->required(),'next_steps' => $schema->array()->items($schema->string())->required(),];diff --git a/api/app/Mcp/Tools/GetFormDraftTool.php b/api/app/Mcp/Tools/GetFormDraftTool.phpindex 16f38bb0e..fb332d377 100644--- a/api/app/Mcp/Tools/GetFormDraftTool.php+++ b/api/app/Mcp/Tools/GetFormDraftTool.php@@ -24,19 +24,19 @@ class GetFormDraftTool extends GuestDraftMcpToolpublic function handle(Request $request, AgentFormDraftService $drafts): ResponseFactory{$validated = $request->validate([- 'draft_token' => ['required', 'string', 'size:43'],+ 'draft_handle' => ['required', 'string', 'size:43'],]);return Response::structured([- 'draft' => $drafts->serialize($drafts->get($validated['draft_token'])),+ 'draft' => $drafts->serialize($drafts->get($validated['draft_handle'])),]);}public function schema(JsonSchema $schema): array{return [- 'draft_token' => $schema->string()- ->description('Private capability token returned by create_form_draft.')+ 'draft_handle' => $schema->string()+ ->description('Opaque reference returned by create_form_draft. Pass it unchanged.')->min(43)->max(43)->required(),diff --git a/api/app/Mcp/Tools/OpenFormDraftInEditorTool.php b/api/app/Mcp/Tools/OpenFormDraftInEditorTool.phpindex e02f61d07..a04925495 100644--- a/api/app/Mcp/Tools/OpenFormDraftInEditorTool.php+++ b/api/app/Mcp/Tools/OpenFormDraftInEditorTool.php@@ -14,32 +14,56 @@ use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;#[Name('open_form_draft_in_editor')]-#[Description('Create a reusable OpnForm editor link that remains valid until the guest draft expires.')]+#[Description('Create a reusable OpnForm editor link only after the user chooses to continue editing the guest draft in OpnForm. The link remains valid until the seven-day draft expires.')]#[IsReadOnly(false)]#[IsDestructive(false)]#[IsOpenWorld(false)]class OpenFormDraftInEditorTool extends GuestDraftMcpTool{+ /**+ * @return array<string, mixed>+ */+ public function toArray(): array+ {+ $tool = parent::toArray();++ return [+ ...$tool,+ '_meta' => [+ ...($tool['_meta'] ?? []),+ 'ui' => ['visibility' => ['model', 'app']],+ ],+ ];+ }+public function handle(Request $request, AgentFormDraftService $drafts): ResponseFactory{$validated = $request->validate([- 'draft_token' => ['required', 'string', 'size:43'],+ 'draft_handle' => ['required', 'string', 'size:43'],]);- return Response::structured($drafts->issueEditorHandoff($validated['draft_token']));+ $handoff = $drafts->issueEditorHandoff($validated['draft_handle']);++ return Response::structured([+ 'editor_url' => $handoff['editor_url'],+ 'expires_at' => $handoff['expires_at'],+ ]);}public function schema(JsonSchema $schema): array{return [- 'draft_token' => $schema->string()->min(43)->max(43)->required(),+ 'draft_handle' => $schema->string()+ ->description('Opaque reference returned by create_form_draft. Pass it unchanged.')+ ->min(43)+ ->max(43)+ ->required(),];}public function outputSchema(JsonSchema $schema): array{return [- 'handoff_token' => $schema->string()->min(43)->max(43)->required(),'editor_url' => $schema->string()->format('uri')->required(),'expires_at' => $schema->string()->format('date-time')->required(),];diff --git a/api/app/Mcp/Tools/PatchFormDraftTool.php b/api/app/Mcp/Tools/PatchFormDraftTool.phpindex e413645a4..623cc0097 100644--- a/api/app/Mcp/Tools/PatchFormDraftTool.php+++ b/api/app/Mcp/Tools/PatchFormDraftTool.php@@ -3,6 +3,8 @@namespace App\Mcp\Tools;use App\Mcp\Support\McpOutputSchema;+use App\Models\Forms\Form;+use App\Service\Forms\AgentFormFieldCatalog;use App\Service\Forms\AgentFormDraftService;use Illuminate\Contracts\JsonSchema\JsonSchema;use Laravel\Mcp\Request;@@ -15,7 +17,7 @@ use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;#[Name('patch_form_draft')]-#[Description('Apply validated semantic operations to a private draft. Operations can replace or remove draft content. Requires expected_version, so concurrent agent or editor changes cannot be silently overwritten. Supported ops: set_form_values, add_block, update_block, remove_block, move_block. Before changing presentation_style, fields, layout, or media, read opnform://reference/form-fields/v1; focused mode derives one step per block and media belongs in the block image property.')]+#[Description('Apply validated semantic operations to a private draft. Operations can replace or remove draft content. Requires expected_version, so concurrent agent or editor changes cannot be silently overwritten. Supported ops: set_form_values, add_block, update_block, remove_block, move_block. Before changing presentation_style, fields, layout, or media, read opnform://reference/form-fields/v1. Style values are strict: border_radius is none, small, or full; width is centered or full; size is sm, md, or lg; theme is default, simple, notion, minimal, or transparent. Classic mode uses nf-page-break for explicit pagination; focused mode derives one step per block and must not use page breaks.')]#[IsReadOnly(false)]#[IsDestructive]#[IsOpenWorld(false)]@@ -24,7 +26,7 @@ class PatchFormDraftTool extends GuestDraftMcpToolpublic function handle(Request $request, AgentFormDraftService $drafts): ResponseFactory{$validated = $request->validate([- 'draft_token' => ['required', 'string', 'size:43'],+ 'draft_handle' => ['required', 'string', 'size:43'],'expected_version' => ['required', 'integer', 'min:1'],'operations' => ['required', 'array', 'min:1', 'max:100'],'operations.*' => ['required', 'array'],@@ -32,7 +34,7 @@ class PatchFormDraftTool extends GuestDraftMcpTool]);$draft = $drafts->patch(- $validated['draft_token'],+ $validated['draft_handle'],$validated['expected_version'],$validated['operations'],);@@ -46,8 +48,8 @@ class PatchFormDraftTool extends GuestDraftMcpToolpublic function schema(JsonSchema $schema): array{return [- 'draft_token' => $schema->string()- ->description('Private capability token returned by create_form_draft.')+ 'draft_handle' => $schema->string()+ ->description('Opaque reference returned by create_form_draft. Pass it unchanged.')->min(43)->max(43)->required(),@@ -61,12 +63,38 @@ class PatchFormDraftTool extends GuestDraftMcpTool'op' => $schema->string()->enum(['set_form_values', 'add_block', 'update_block', 'remove_block', 'move_block'])->required(),- 'values' => $schema->object(),- 'block' => $schema->object(),- 'patch' => $schema->object(),- 'block_id' => $schema->string(),- 'index' => $schema->integer()->min(0),- 'to_index' => $schema->integer()->min(0),+ 'values' => $schema->object([+ 'title' => $schema->string()->description('Form title.'),+ 'presentation_style' => $schema->string()->enum(Form::PRESENTATION_STYLES),+ 'width' => $schema->string()->enum(Form::WIDTHS),+ 'size' => $schema->string()->enum(Form::SIZES),+ 'theme' => $schema->string()->enum(Form::THEMES),+ 'border_radius' => $schema->string()->enum(Form::BORDER_RADIUS),+ 'color' => $schema->string()->description('Form accent color, preferably a hex color.'),+ 'uppercase_labels' => $schema->boolean(),+ 'show_progress_bar' => $schema->boolean(),+ 'submit_button_text' => $schema->string(),+ 'settings' => $schema->object(),+ ])->description('Top-level form values for set_form_values. Do not put properties here.'),+ 'block' => $schema->object([+ 'name' => $schema->string()->required(),+ 'type' => $schema->string()->enum(AgentFormFieldCatalog::types())->required(),+ 'placeholder' => $schema->string()->nullable(),+ 'help' => $schema->string()->nullable(),+ 'required' => $schema->boolean(),+ 'width' => $schema->string()->enum(['full', '1/2', '1/3', '2/3', '1/4', '3/4']),+ ])->description('Complete block for add_block. Use type nf-page-break only in classic mode.'),+ 'patch' => $schema->object([+ 'name' => $schema->string(),+ 'type' => $schema->string()->enum(AgentFormFieldCatalog::types()),+ 'placeholder' => $schema->string()->nullable(),+ 'help' => $schema->string()->nullable(),+ 'required' => $schema->boolean(),+ 'width' => $schema->string()->enum(['full', '1/2', '1/3', '2/3', '1/4', '3/4']),+ ])->description('Fields to merge into the selected block for update_block. Block id cannot change.'),+ 'block_id' => $schema->string()->description('Stable block id from the latest draft.'),+ 'index' => $schema->integer()->description('Zero-based block index. For add_block, insertion at the final count is allowed.')->min(0),+ 'to_index' => $schema->integer()->description('Zero-based destination for move_block.')->min(0),]))->min(1)->max(100)diff --git a/api/app/Mcp/Tools/PreviewFormDraftTool.php b/api/app/Mcp/Tools/PreviewFormDraftTool.phpindex 4d37fff43..949d82025 100644--- a/api/app/Mcp/Tools/PreviewFormDraftTool.php+++ b/api/app/Mcp/Tools/PreviewFormDraftTool.php@@ -17,9 +17,9 @@ use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;#[Name('preview_form_draft')]-#[Description('Render the current guest draft, return a browser preview valid for one hour, and create a reusable editor link that remains valid for the seven-day guest draft lifetime. Call this tool again whenever a fresh preview link is needed.')]+#[Description('Render the current guest draft and return a browser preview valid for one hour. This read-only tool does not create an editor link. Call open_form_draft_in_editor only when the user chooses to continue editing in OpnForm.')]#[RendersApp(resource: FormDraftPreviewApp::class)]-#[IsReadOnly(false)]+#[IsReadOnly]#[IsDestructive(false)]#[IsOpenWorld(false)]class PreviewFormDraftTool extends GuestDraftMcpTool@@ -27,24 +27,22 @@ class PreviewFormDraftTool extends GuestDraftMcpToolpublic function handle(Request $request, AgentFormDraftService $drafts): ResponseFactory{$validated = $request->validate([- 'draft_token' => ['required', 'string', 'size:43'],+ 'draft_handle' => ['required', 'string', 'size:43'],]);- $draft = $drafts->get($validated['draft_token']);- $handoff = $drafts->issueEditorHandoff($validated['draft_token']);+ $draft = $drafts->get($validated['draft_handle']);return Response::structured([+ 'draft_handle' => $validated['draft_handle'],'draft' => $drafts->serialize($draft),'preview_url' => $drafts->previewUrl($draft),- 'editor_url' => $handoff['editor_url'],- 'editor_link_expires_at' => $handoff['expires_at'],]);}public function schema(JsonSchema $schema): array{return [- 'draft_token' => $schema->string()- ->description('Private capability token returned by create_form_draft.')+ 'draft_handle' => $schema->string()+ ->description('Opaque reference returned by create_form_draft. Pass it unchanged.')->min(43)->max(43)->required(),@@ -54,10 +52,9 @@ class PreviewFormDraftTool extends GuestDraftMcpToolpublic function outputSchema(JsonSchema $schema): array{return [+ 'draft_handle' => $schema->string()->min(43)->max(43)->required(),'draft' => McpOutputSchema::draft($schema)->required(),'preview_url' => $schema->string()->format('uri')->required(),- 'editor_url' => $schema->string()->format('uri')->required(),- 'editor_link_expires_at' => $schema->string()->format('date-time')->required(),];}}diff --git a/api/app/Service/Forms/AgentFormDefinition.php b/api/app/Service/Forms/AgentFormDefinition.phpindex 51f1aadd0..c1ceadef5 100644--- a/api/app/Service/Forms/AgentFormDefinition.php+++ b/api/app/Service/Forms/AgentFormDefinition.php@@ -204,6 +204,13 @@ class AgentFormDefinition'regex:/^[A-Za-z0-9\-_\.]+$/','required_if:analytics.provider,meta_pixel,google_analytics,gtm',],+ ], [+ 'theme.in' => 'theme must be one of: default, simple, notion, minimal, transparent.',+ 'presentation_style.in' => 'presentation_style must be one of: classic, focused.',+ 'width.in' => 'width must be one of: centered, full.',+ 'size.in' => 'size must be one of: sm, md, lg.',+ 'border_radius.in' => 'border_radius must be one of: none, small, full.',+ 'dark_mode.in' => 'dark_mode must be one of: auto, light, dark.',])->validate();}diff --git a/api/app/Service/Forms/AgentFormDraftService.php b/api/app/Service/Forms/AgentFormDraftService.phpindex 296e4b2a0..cda25d0d9 100644--- a/api/app/Service/Forms/AgentFormDraftService.php+++ b/api/app/Service/Forms/AgentFormDraftService.php@@ -227,7 +227,7 @@ class AgentFormDraftServiceprivate function resolveActive(string $token, bool $lock = false): AgentFormDraft{- $this->assertTokenShape($token, 'draft_token');+ $this->assertTokenShape($token, 'draft_handle');$query = AgentFormDraft::query()->where('token_hash', $this->hashToken($token))@@ -287,7 +287,7 @@ class AgentFormDraftService{if (! preg_match('/^[A-Za-z0-9_-]{43}$/', $token)) {throw ValidationException::withMessages([- $field => ['Invalid or unavailable capability token.'],+ $field => ['Invalid or unavailable draft handle.'],]);}}@@ -317,7 +317,7 @@ class AgentFormDraftServiceprivate function unavailable(): ValidationException{return ValidationException::withMessages([- 'draft_token' => ['Draft not found, expired, or already claimed.'],+ 'draft_handle' => ['Draft not found, expired, or already claimed.'],]);}}diff --git a/api/app/Service/Forms/AgentFormFieldCatalog.php b/api/app/Service/Forms/AgentFormFieldCatalog.phpindex 741164133..79833653d 100644--- a/api/app/Service/Forms/AgentFormFieldCatalog.php+++ b/api/app/Service/Forms/AgentFormFieldCatalog.php@@ -103,6 +103,16 @@ class AgentFormFieldCatalog],],],+ 'form_style' => [+ 'theme' => ['default', 'simple', 'notion', 'minimal', 'transparent'],+ 'width' => ['centered', 'full'],+ 'size' => ['sm', 'md', 'lg'],+ 'border_radius' => ['none', 'small', 'full'],+ 'dark_mode' => ['auto', 'light', 'dark'],+ 'color' => 'Accent color string, preferably a hex color such as #2563EB.',+ 'uppercase_labels' => 'Boolean.',+ 'show_progress_bar' => 'Boolean.',+ ],'authoring_guidelines' => AgentFormAuthoringGuide::reference(),'block_media' => ['property' => 'image',diff --git a/api/resources/views/mcp/form-draft-preview-app.blade.php b/api/resources/views/mcp/form-draft-preview-app.blade.phpindex eacfe330c..ac907cff4 100644--- a/api/resources/views/mcp/form-draft-preview-app.blade.php+++ b/api/resources/views/mcp/form-draft-preview-app.blade.php@@ -4,34 +4,34 @@:root { color-scheme: light dark; }body { margin: 0; font-family: ui-sans-serif, system-ui, sans-serif; color: var(--color-text-primary, #111827); }main { padding: 0; }- .preview-surface { border-radius: 14px; padding: 18px; background: var(--color-background-secondary, #f5f5f5); }- .header { display: flex; align-items: flex-start; justify-content: space-between; gap: 16px; }+ .preview-surface { border-radius: 12px; padding: 11px; background: var(--color-background-secondary, #f5f5f5); }+ .header { display: flex; align-items: center; justify-content: space-between; gap: 12px; }.heading { min-width: 0; }- .header-actions { display: flex; align-items: center; gap: 8px; }- .eyebrow { display: flex; align-items: center; gap: 8px; margin: 0 0 10px; color: var(--color-text-secondary, #4b5563); font-size: 13px; font-weight: 650; }- .eyebrow::before { width: 8px; height: 8px; border-radius: 999px; background: #3b82f6; content: ''; }- h1 { margin: 0 0 8px; font-size: 20px; }- .meta { margin: 0; color: var(--color-text-secondary, #6b7280); font-size: 13px; }- .zoom-controls { display: flex; align-items: center; overflow: hidden; border: 1px solid var(--color-border-primary, #d1d5db); border-radius: 8px; background: var(--color-background-primary, #fff); }- .zoom-button { display: grid; width: 32px; height: 32px; place-items: center; border: 0; border-radius: 0; padding: 0; background: transparent; color: var(--color-text-primary, #111827); font-size: 17px; font-weight: 500; cursor: pointer; }+ .draft-summary { display: flex; align-items: baseline; gap: 7px; margin-top: 3px; }+ .header-actions { display: flex; flex: none; align-items: center; gap: 7px; }+ .eyebrow { display: flex; align-items: center; gap: 6px; margin: 0; color: var(--color-text-secondary, #4b5563); font-size: 11px; font-weight: 650; line-height: 1.2; }+ .eyebrow::before { width: 6px; height: 6px; border-radius: 999px; background: #3b82f6; content: ''; }+ h1 { overflow: hidden; margin: 0; font-size: 16px; line-height: 1.25; text-overflow: ellipsis; white-space: nowrap; }+ .meta { flex: none; margin: 0; color: var(--color-text-secondary, #6b7280); font-size: 11px; line-height: 1.25; }+ .zoom-controls { display: flex; align-items: center; overflow: hidden; border: 1px solid var(--color-border-primary, #d1d5db); border-radius: 7px; background: var(--color-background-primary, #fff); }+ .zoom-button { display: grid; width: 28px; height: 28px; place-items: center; border: 0; border-radius: 0; padding: 0; background: transparent; color: var(--color-text-primary, #111827); font-size: 15px; font-weight: 500; cursor: pointer; }.zoom-button:hover:not(:disabled), .zoom-value:hover { background: var(--color-background-secondary, #f3f4f6); }.zoom-button:disabled { cursor: default; opacity: .35; }- .zoom-value { min-width: 46px; height: 32px; border: 0; border-right: 1px solid var(--color-border-primary, #d1d5db); border-left: 1px solid var(--color-border-primary, #d1d5db); border-radius: 0; padding: 0 6px; background: transparent; color: var(--color-text-secondary, #4b5563); font-size: 11px; font-variant-numeric: tabular-nums; cursor: pointer; }- .preview-viewport { width: 100%; margin-top: 18px; overflow: hidden; }- .preview-canvas { position: relative; margin: 0 auto; }- iframe { display: block; width: 1280px; height: 480px; border: 0; background: transparent; transform-origin: top left; }+ .zoom-value { min-width: 43px; height: 28px; border: 0; border-right: 1px solid var(--color-border-primary, #d1d5db); border-left: 1px solid var(--color-border-primary, #d1d5db); border-radius: 0; padding: 0 5px; background: transparent; color: var(--color-text-secondary, #4b5563); font-size: 10px; font-variant-numeric: tabular-nums; cursor: pointer; }+ .preview-viewport { width: 100%; margin-top: 10px; overflow: hidden; }+ .preview-canvas { position: relative; width: 100%; margin: 0; }+ iframe { display: block; width: 100%; height: 480px; border: 0; background: transparent; transform-origin: top left; }ol { padding-left: 22px; margin: 18px 0; }li { margin: 10px 0; }- .open-button { display: inline-flex; flex: none; height: 32px; align-items: center; border: 0; border-radius: 8px; padding: 0 10px; background: #2563eb; color: white; font-size: 12px; font-weight: 650; cursor: pointer; }+ .open-button { display: inline-flex; flex: none; height: 28px; align-items: center; border: 0; border-radius: 7px; padding: 0 9px; background: #2563eb; color: white; font-size: 11px; font-weight: 650; cursor: pointer; }.open-button:disabled { cursor: wait; opacity: .6; }+ .action-status { margin: 7px 0 0; color: #b42318; font-size: 11px; line-height: 1.35; }.empty { color: var(--color-text-secondary, #6b7280); font-style: italic; }@media (max-width: 520px) {- .preview-surface { padding: 14px; }+ .preview-surface { padding: 10px; }.header { align-items: stretch; flex-direction: column; }.header-actions { justify-content: space-between; }- .eyebrow { margin-bottom: 8px; }- h1 { font-size: 17px; }- .open-button { padding: 6px 8px; }+ h1 { font-size: 15px; }}</style><script type="module">@@ -46,44 +46,50 @@const zoomOutButton = document.getElementById('zoom-out');const zoomResetButton = document.getElementById('zoom-reset');const zoomInButton = document.getElementById('zoom-in');- const canvasWidth = 1280;const focusedHeight = 720;- const defaultZoom = 0.8;- const minimumZoom = 0.5;- const zoomStep = 0.1;- let requestedZoom = defaultZoom;+ const zoomLevels = [0.75, 0.85, 1];+ const defaultZoomIndex = 1;+ let zoomIndex = defaultZoomIndex;let naturalHeight = 480;let presentationStyle = 'classic';let resizeScriptPromise;+ let draftHandle = null;+ let rendered = false;+ const initialOpenButtonText = openButton.textContent;+ const loadingFallback = window.setTimeout(() => {+ if (rendered) return;++ title.textContent = 'Preview unavailable';+ meta.textContent = 'Ask ChatGPT to refresh this preview.';+ fields.hidden = true;+ }, 5000);const applyPreviewLayout = () => {const availableWidth = previewViewport.clientWidth;- const fitZoom = availableWidth > 0 ? Math.min(1, availableWidth / canvasWidth) : 1;- const effectiveMinimumZoom = Math.min(minimumZoom, fitZoom);- const zoom = Math.max(effectiveMinimumZoom, Math.min(requestedZoom, fitZoom));+ if (availableWidth <= 0) return;++ const zoom = zoomLevels[zoomIndex];const height = presentationStyle === 'focused' ? focusedHeight : naturalHeight;- preview.style.width = `${canvasWidth}px`;+ preview.style.width = `${availableWidth / zoom}px`;preview.style.height = `${height}px`;preview.style.transform = `scale(${zoom})`;- previewCanvas.style.width = `${canvasWidth * zoom}px`;+ previewCanvas.style.width = `${availableWidth}px`;previewCanvas.style.height = `${height * zoom}px`;zoomResetButton.textContent = `${Math.round(zoom * 100)}%`;- zoomOutButton.disabled = zoom <= effectiveMinimumZoom;- zoomInButton.disabled = zoom >= fitZoom;+ zoomOutButton.disabled = zoomIndex === 0;+ zoomInButton.disabled = zoomIndex === zoomLevels.length - 1;};zoomOutButton.onclick = () => {- const currentZoom = Number.parseInt(zoomResetButton.textContent, 10) / 100;- requestedZoom = Math.max(0.1, currentZoom - zoomStep);+ zoomIndex = Math.max(0, zoomIndex - 1);applyPreviewLayout();};zoomResetButton.onclick = () => {- requestedZoom = defaultZoom;+ zoomIndex = defaultZoomIndex;applyPreviewLayout();};zoomInButton.onclick = () => {- const currentZoom = Number.parseInt(zoomResetButton.textContent, 10) / 100;- requestedZoom = Math.min(1, currentZoom + zoomStep);+ zoomIndex = Math.min(zoomLevels.length - 1, zoomIndex + 1);applyPreviewLayout();};@@ -107,10 +113,29 @@return resizeScriptPromise;};- app.onToolResult((result) => {- const payload = result?.structuredContent ?? result?.structured_content ?? {};+ const toolPayload = (result) => result?.structuredContent+ ?? result?.structured_content+ ?? result+ ?? {};++ const applyToolInput = (input) => {+ const args = input?.arguments ?? input ?? {};+ draftHandle = args.draft_handle ?? draftHandle;+ openButton.disabled = !draftHandle;+ };++ const renderToolResult = (result) => {+ const payload = toolPayload(result);const draft = payload.draft ?? {};const definition = draft.definition ?? {};++ if (!payload.preview_url && !draft.version && !definition.title) {+ return false;+ }++ rendered = true;+ window.clearTimeout(loadingFallback);+ draftHandle = payload.draft_handle ?? draftHandle;presentationStyle = definition.presentation_style ?? 'classic';title.textContent = definition.title ?? 'Untitled form';meta.textContent = `Draft v${draft.version ?? '?'} · ${presentationStyle} layout`;@@ -155,16 +180,51 @@}}- openButton.disabled = !payload.editor_url;- openButton.onclick = () => {- if (window.openai?.openExternal) {- return window.openai.openExternal({ href: payload.editor_url, redirectUrl: false });- }+ openButton.disabled = !draftHandle;++ return true;+ };++ app.onToolInput(applyToolInput);+ app.onToolResult(renderToolResult);- return app.openLink({ url: payload.editor_url });- };+ applyToolInput(window.openai?.toolInput);+ renderToolResult(window.openai?.toolOutput);++ window.addEventListener('openai:set_globals', (event) => {+ const globals = event.detail?.globals ?? {};+ applyToolInput(globals.toolInput ?? window.openai?.toolInput);+ renderToolResult(globals.toolOutput ?? window.openai?.toolOutput);});+ openButton.onclick = async () => {+ if (!draftHandle) return;++ const actionStatus = document.getElementById('action-status');+ openButton.disabled = true;+ openButton.textContent = 'Opening…';+ actionStatus.hidden = true;++ try {+ const result = await app.callServerTool('open_form_draft_in_editor', {+ draft_handle: draftHandle,+ });+ const payload = toolPayload(result);++ if (result?.isError || !payload.editor_url) {+ throw new Error('Editor link unavailable');+ }++ await app.openLink({ url: payload.editor_url });+ } catch (error) {+ actionStatus.textContent = 'Could not open OpnForm. Please try again.';+ actionStatus.hidden = false;+ } finally {+ openButton.textContent = initialOpenButtonText;+ openButton.disabled = !draftHandle;+ }+ };+app.autoResize();});</script>@@ -175,18 +235,21 @@<header class="header"><div class="heading"><p class="eyebrow">Private preview</p>- <h1 id="title">Loading preview…</h1>- <p id="meta" class="meta"></p>+ <div class="draft-summary">+ <h1 id="title">Loading preview…</h1>+ <p id="meta" class="meta"></p>+ </div></div><div class="header-actions"><div class="zoom-controls" role="group" aria-label="Preview zoom"><button id="zoom-out" class="zoom-button" type="button" title="Zoom out" aria-label="Zoom out">−</button>- <button id="zoom-reset" class="zoom-value" type="button" title="Reset zoom">80%</button>+ <button id="zoom-reset" class="zoom-value" type="button" title="Reset zoom">85%</button><button id="zoom-in" class="zoom-button" type="button" title="Zoom in" aria-label="Zoom in">+</button></div><button id="open-editor" class="open-button" type="button" disabled>Open in OpnForm</button></div></header>+ <p id="action-status" class="action-status" role="status" aria-live="polite" hidden></p><div id="preview-viewport" class="preview-viewport" hidden><div id="preview-canvas" class="preview-canvas"><iframediff --git a/api/tests/Feature/Mcp/AgentDraftEditorTest.php b/api/tests/Feature/Mcp/AgentDraftEditorTest.phpindex eb8dccf02..6ecd882bd 100644--- a/api/tests/Feature/Mcp/AgentDraftEditorTest.php+++ b/api/tests/Feature/Mcp/AgentDraftEditorTest.php@@ -2,6 +2,7 @@use App\Http\Controllers\AgentFormDraftController;use App\Mcp\Servers\OpnFormServer;+use App\Mcp\Tools\OpenFormDraftInEditorTool;use App\Mcp\Tools\PreviewFormDraftTool;use App\Models\Forms\AgentFormDraft;use App\Models\OAuthProvider;@@ -26,22 +27,33 @@ beforeEach(function () {config()->set('app.front_url', 'https://opnform.test');});-it('renders an MCP App preview with short-lived preview and reusable editor links', function () {+it('renders a read-only MCP App preview and creates an editor link only on demand', function () {$created = app(AgentFormDraftService::class)->create(editorDraftDefinition());OpnFormServer::tool(PreviewFormDraftTool::class, [- 'draft_token' => $created['token'],+ 'draft_handle' => $created['token'],])->assertOk()->assertSee('preview_url')- ->assertSee('editor_url')+ ->assertSee('draft_handle')+ ->assertDontSee('editor_url')->assertSee('Agent customer intake');+ $this->assertDatabaseCount('agent_form_draft_handoffs', 0);+OpnFormServer::resource(\App\Mcp\Apps\FormDraftPreviewApp::class)->assertOk()->assertSee('Open in OpnForm')- ->assertSee('window.openai?.openExternal')+ ->assertSee("app.callServerTool('open_form_draft_in_editor'")+ ->assertSee('window.openai?.toolOutput')+ ->assertSee("openai:set_globals")->assertSee('<iframe');+ OpnFormServer::tool(OpenFormDraftInEditorTool::class, [+ 'draft_handle' => $created['token'],+ ])->assertOk()+ ->assertSee('editor_url')+ ->assertDontSee('handoff_token');+$draft = $created['draft']->refresh();$handoff = $draft->editorHandoffs()->sole();expect($handoff->token_hash)->toMatch('/^[a-f0-9]{64}$/')@@ -59,7 +71,7 @@ it('publishes standard and ChatGPT-compatible CSP metadata with the full fronten->content()->toResource($previewApp);- expect($previewApp->uri())->toBe('ui://opnform/form-draft-preview-v3')+ expect($previewApp->uri())->toBe('ui://opnform/form-draft-preview-v4')->and($previewApp->resolvedAppMeta()['csp']['resourceDomains'])->toBe(['http://127.0.0.1:33676'])->and($previewApp->resolvedAppMeta()['csp']['frameDomains'])diff --git a/api/tests/Feature/Mcp/AgentPluginPackageTest.php b/api/tests/Feature/Mcp/AgentPluginPackageTest.phpindex eac7d05e0..b132fddde 100644--- a/api/tests/Feature/Mcp/AgentPluginPackageTest.php+++ b/api/tests/Feature/Mcp/AgentPluginPackageTest.php@@ -131,7 +131,7 @@ it('ships a discoverable OpnForm skill with the complete safety workflow', funct->and($skill)->toContain('opnform://schemas/agent-form-definition/v1','validate_form_definition',- 'draft_token',+ 'draft_handle','preview_form_draft','get_form_draft','open_form_draft_in_editor',@@ -168,7 +168,13 @@ it('ships a discoverable OpnForm skill with the complete safety workflow', funct)->and($skill)->toContain('confirm_publish: true', 'confirm_trash: true')->and($skill)->not->toContain('`confirm: true`')+ ->and($skill)->not->toContain('draft_token', 'capability secret')->and($skill)->toContain('Submission access is read-only')+ ->and($skill)->toContain(+ 'do not turn a recoverable enum or field error into a generic “server error”',+ '`border_radius` is `none`, `small`, or `full`',+ 'Never invent aliases such as `medium` or `large`',+ )->and(substr_count($skill, "\n"))->toBeLessThan(500);});@@ -235,12 +241,16 @@ it('renders a flattened and hardened form preview frame', function () {->toContain('/widgets/iframeResize.min.js')->toContain('checkOrigin: [previewUrl.origin]')->toContain('scrolling: false')- ->toContain('const canvasWidth = 1280')->toContain('const focusedHeight = 720')- ->toContain('const defaultZoom = 0.8')- ->toContain('availableWidth / canvasWidth')+ ->toContain('const zoomLevels = [0.75, 0.85, 1]')+ ->toContain('const defaultZoomIndex = 1')+ ->toContain('availableWidth / zoom')->toContain('new ResizeObserver(applyPreviewLayout).observe(previewViewport)')->toContain("sizeHeight: presentationStyle !== 'focused'")+ ->toContain("app.callServerTool('open_form_draft_in_editor'")+ ->toContain('window.openai?.toolOutput')+ ->toContain("openai:set_globals")+ ->toContain('Ask ChatGPT to refresh this preview.')->toContain('aria-label="Preview zoom"')->toContain('sandbox="allow-forms allow-modals allow-popups allow-scripts allow-same-origin"')->toContain('referrerpolicy="no-referrer"')diff --git a/api/tests/Feature/Mcp/AuthenticatedFormToolsTest.php b/api/tests/Feature/Mcp/AuthenticatedFormToolsTest.phpindex 57d1d5378..db39ff9c3 100644--- a/api/tests/Feature/Mcp/AuthenticatedFormToolsTest.php+++ b/api/tests/Feature/Mcp/AuthenticatedFormToolsTest.php@@ -168,7 +168,7 @@ it('hides guest draft capabilities but keeps validation and OAuth tools on self-expect($resourceUris)->toContain('opnform://schemas/agent-form-definition/v1', 'opnform://reference/form-fields/v1')- ->not->toContain('ui://opnform/form-draft-preview-v3');+ ->not->toContain('ui://opnform/form-draft-preview-v4');$this->postJson('/mcp', ['jsonrpc' => '2.0',diff --git a/api/tests/Feature/Mcp/GuestDraftToolsTest.php b/api/tests/Feature/Mcp/GuestDraftToolsTest.phpindex 5ba525b3c..445884978 100644--- a/api/tests/Feature/Mcp/GuestDraftToolsTest.php+++ b/api/tests/Feature/Mcp/GuestDraftToolsTest.php@@ -3,7 +3,9 @@use App\Mcp\Servers\OpnFormServer;use App\Mcp\Tools\CreateFormDraftTool;use App\Mcp\Tools\GetFormDraftTool;+use App\Mcp\Tools\OpenFormDraftInEditorTool;use App\Mcp\Tools\PatchFormDraftTool;+use App\Mcp\Tools\PreviewFormDraftTool;use App\Models\Forms\AgentFormDraft;use App\Service\Forms\AgentFormDraftRateLimiter;use App\Service\Forms\AgentFormDraftService;@@ -24,13 +26,31 @@ beforeEach(function () {config()->set('app.self_hosted', false);});-it('creates a seven-day server-side guest draft and only stores a token hash', function () {+it('publishes a neutral draft handle contract and accurate preview annotations', function () {+ $create = app(CreateFormDraftTool::class)->toArray();+ $preview = app(PreviewFormDraftTool::class)->toArray();+ $open = app(OpenFormDraftInEditorTool::class)->toArray();++ expect($create['outputSchema']['properties'])->toHaveKey('draft_handle')+ ->and($create['outputSchema']['properties'])->not->toHaveKey('draft_token')+ ->and($preview['inputSchema']['properties'])->toHaveKey('draft_handle')+ ->and($preview['outputSchema']['properties'])->not->toHaveKeys([+ 'editor_url',+ 'editor_link_expires_at',+ ])+ ->and($preview['annotations']['readOnlyHint'])->toBeTrue()+ ->and($open['_meta']['ui']['visibility'])->toBe(['model', 'app'])+ ->and($open['outputSchema']['properties'])->not->toHaveKey('handoff_token');+});++it('creates a seven-day server-side guest draft and returns an opaque handle', function () {$before = now();OpnFormServer::tool(CreateFormDraftTool::class, ['definition' => guestDraftDefinition(['visibility' => 'public']),])->assertOk()- ->assertSee('draft_token')+ ->assertSee('draft_handle')+ ->assertDontSee('capability secret')->assertSee('Customer intake')->assertSee('expected_version');@@ -46,11 +66,11 @@ it('creates a seven-day server-side guest draft and only stores a token hash', f$this->assertDatabaseCount('forms', 0);});-it('fetches a draft with its capability token without exposing stored secrets', function () {+it('fetches a draft with its opaque handle without exposing stored hashes', function () {$created = app(AgentFormDraftService::class)->create(guestDraftDefinition());OpnFormServer::tool(GetFormDraftTool::class, [- 'draft_token' => $created['token'],+ 'draft_handle' => $created['token'],])->assertOk()->assertSee('Customer intake')->assertDontSee($created['draft']->token_hash)@@ -62,7 +82,7 @@ it('patches form values and blocks with optimistic versioning', function () {$created = $drafts->create(guestDraftDefinition());$response = OpnFormServer::tool(PatchFormDraftTool::class, [- 'draft_token' => $created['token'],+ 'draft_handle' => $created['token'],'expected_version' => 1,'operations' => [[@@ -103,6 +123,45 @@ it('patches form values and blocks with optimistic versioning', function () {->and($updated->definition['properties'][2]['id'])->toBeString()->not->toBeEmpty();});+it('describes strict style values in the patch schema and field catalog', function () {+ $tool = OpnFormServer::tool(PatchFormDraftTool::class, [+ 'draft_handle' => str_repeat('x', 43),+ 'expected_version' => 1,+ 'operations' => [[+ 'op' => 'set_form_values',+ 'values' => ['border_radius' => 'large'],+ ]],+ ]);++ $tool->assertHasErrors(['Draft not found, expired, or already claimed']);++ $schema = app(PatchFormDraftTool::class)->schema(new \Illuminate\JsonSchema\JsonSchemaTypeFactory());++ $styleProperties = $schema['operations']->toArray()['items']['properties']['values']['properties'];++ expect($styleProperties['presentation_style']['enum'])->toBe(['classic', 'focused'])+ ->and($styleProperties['width']['enum'])->toBe(['centered', 'full'])+ ->and($styleProperties['size']['enum'])->toBe(['sm', 'md', 'lg'])+ ->and($styleProperties['theme']['enum'])->toBe(['default', 'simple', 'notion', 'minimal', 'transparent'])+ ->and($styleProperties['border_radius']['enum'])->toBe(['none', 'small', 'full'])+ ->and(\App\Service\Forms\AgentFormFieldCatalog::reference()['form_style']['border_radius'])+ ->toBe(['none', 'small', 'full']);+});++it('returns actionable validation errors for invalid style values', function () {+ $drafts = app(AgentFormDraftService::class);+ $created = $drafts->create(guestDraftDefinition());++ OpnFormServer::tool(PatchFormDraftTool::class, [+ 'draft_handle' => $created['token'],+ 'expected_version' => 1,+ 'operations' => [[+ 'op' => 'set_form_values',+ 'values' => ['border_radius' => 'large'],+ ]],+ ])->assertHasErrors(['border_radius must be one of: none, small, full.']);+});+it('rejects stale patches without changing the draft', function () {$drafts = app(AgentFormDraftService::class);$created = $drafts->create(guestDraftDefinition());@@ -113,7 +172,7 @@ it('rejects stale patches without changing the draft', function () {]]);OpnFormServer::tool(PatchFormDraftTool::class, [- 'draft_token' => $created['token'],+ 'draft_handle' => $created['token'],'expected_version' => 1,'operations' => [['op' => 'set_form_values',@@ -134,7 +193,7 @@ it('rolls back invalid patch operations and preserves the previous version', fun]));OpnFormServer::tool(PatchFormDraftTool::class, [- 'draft_token' => $created['token'],+ 'draft_handle' => $created['token'],'expected_version' => 1,'operations' => [['op' => 'remove_block',@@ -151,20 +210,20 @@ it('rejects malformed, expired, and claimed draft capabilities with one generic$created = $drafts->create(guestDraftDefinition());OpnFormServer::tool(GetFormDraftTool::class, [- 'draft_token' => str_repeat('x', 43),+ 'draft_handle' => str_repeat('x', 43),])->assertHasErrors(['Draft not found, expired, or already claimed']);$created['draft']->forceFill(['expires_at' => now()->subSecond()])->save();OpnFormServer::tool(GetFormDraftTool::class, [- 'draft_token' => $created['token'],+ 'draft_handle' => $created['token'],])->assertHasErrors(['Draft not found, expired, or already claimed']);$claimed = $drafts->create(guestDraftDefinition());$claimed['draft']->forceFill(['status' => AgentFormDraft::STATUS_CLAIMED])->save();OpnFormServer::tool(GetFormDraftTool::class, [- 'draft_token' => $claimed['token'],+ 'draft_handle' => $claimed['token'],])->assertHasErrors(['Draft not found, expired, or already claimed']);});diff --git a/api/tests/Feature/Mcp/McpFoundationTest.php b/api/tests/Feature/Mcp/McpFoundationTest.phpindex 9f2e6cf57..fdb61d0de 100644--- a/api/tests/Feature/Mcp/McpFoundationTest.php+++ b/api/tests/Feature/Mcp/McpFoundationTest.php@@ -76,6 +76,7 @@ it('advertises explicit safety annotations for every MCP tool', function () {'list_forms','list_submissions','list_workspaces',+ 'preview_form_draft','validate_form_definition',];$writes = [@@ -83,7 +84,6 @@ it('advertises explicit safety annotations for every MCP tool', function () {'create_form_in_account','export_submissions','open_form_draft_in_editor',- 'preview_form_draft',];$destructivePrivateWrites = ['patch_form_draft',diff --git a/api/tests/Feature/Mcp/McpOAuthTest.php b/api/tests/Feature/Mcp/McpOAuthTest.phpindex e806006fd..bb2bb36cf 100644--- a/api/tests/Feature/Mcp/McpOAuthTest.php+++ b/api/tests/Feature/Mcp/McpOAuthTest.php@@ -137,9 +137,9 @@ it('creates and previews a guest form over HTTP without an OAuth challenge', fun->assertJsonPath('result.isError', false)->assertJsonMissingPath('result._meta.mcp/www_authenticate');- $draftToken = $createResponse->json('result.structuredContent.draft_token');+ $draftHandle = $createResponse->json('result.structuredContent.draft_handle');- expect($draftToken)->toBeString()->toHaveLength(43);+ expect($draftHandle)->toBeString()->toHaveLength(43);$this->postJson('/mcp', ['jsonrpc' => '2.0',@@ -148,14 +148,15 @@ it('creates and previews a guest form over HTTP without an OAuth challenge', fun'params' => ['name' => 'preview_form_draft','arguments' => [- 'draft_token' => $draftToken,+ 'draft_handle' => $draftHandle,],],], mcpHeaders())->assertOk()->assertJsonPath('result.isError', false)->assertJsonPath('result.structuredContent.draft.definition.title', 'Contact form')->assertJsonPath('result.structuredContent.preview_url', fn (string $url): bool => str_starts_with($url, 'https://opnform.test/'))- ->assertJsonPath('result.structuredContent.editor_url', fn (string $url): bool => str_starts_with($url, 'https://opnform.test/'))+ ->assertJsonPath('result.structuredContent.draft_handle', $draftHandle)+ ->assertJsonMissingPath('result.structuredContent.editor_url')->assertJsonMissingPath('result._meta.mcp/www_authenticate');});diff --git a/api/tests/Feature/Mcp/McpObservabilityTest.php b/api/tests/Feature/Mcp/McpObservabilityTest.phpindex 9e5b13747..73ce89924 100644--- a/api/tests/Feature/Mcp/McpObservabilityTest.php+++ b/api/tests/Feature/Mcp/McpObservabilityTest.php@@ -16,7 +16,7 @@ it('records metadata-only MCP usage without request arguments', function () {'method' => 'tools/call','params' => ['name' => 'missing_tool',- 'arguments' => ['draft_token' => $secret],+ 'arguments' => ['draft_handle' => $secret],],], ['Accept' => 'application/json, text/event-stream',diff --git a/client/pages/agent-drafts/preview.vue b/client/pages/agent-drafts/preview.vueindex cb8e6ab52..a0abc4753 100644--- a/client/pages/agent-drafts/preview.vue+++ b/client/pages/agent-drafts/preview.vue@@ -40,8 +40,10 @@/><divv-else- class="overflow-hidden border border-neutral-200 bg-white shadow-sm"- :class="isEmbedded && isFocused ? 'h-full' : (isEmbedded ? '' : 'min-h-[650px] rounded-xl')"+ class="overflow-hidden"+ :class="isEmbedded+ ? (isFocused ? 'h-full bg-transparent' : 'bg-transparent')+ : 'min-h-[650px] rounded-xl border border-neutral-200 bg-white shadow-sm'"><OpenCompleteFormref="formPreview"@@ -67,9 +69,6 @@ import { FormMode } from '~/lib/forms/FormModeStrategy.js'definePageMeta({ layout: 'empty' })useOpnSeoMeta({ title: 'Private form draft preview' })-useHead({- script: [{ src: '/widgets/iframeResizer.contentWindow.min.js' }],-})const route = useRoute()const config = useRuntimeConfig()@@ -85,6 +84,13 @@ const isEmbedded = computed(() => route.query.embedded === '1')const isFocused = computed(() => form.value?.presentation_style === 'focused')provide('disableCustomCodeExecution', true)+useHead(() => ({+ script: [{ src: '/widgets/iframeResizer.contentWindow.min.js' }],+ style: isEmbedded.value+ ? [{ children: 'html, body, #__nuxt { background: transparent !important; }' }]+ : [],+}))+const resetForm = () => {if (!formPreview.value?.restart || isResetting.value) returndiff --git a/plugins/opnform/.codex-plugin/plugin.json b/plugins/opnform/.codex-plugin/plugin.jsonindex 439c56879..c70e8dd3a 100644--- a/plugins/opnform/.codex-plugin/plugin.json+++ b/plugins/opnform/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "opnform",- "version": "1.0.0",+ "version": "1.0.1","description": "Build private form drafts without signing in, then connect OpnForm to manage forms and read submissions.","author": {"name": "OpnForm",diff --git a/plugins/opnform/plugin.json b/plugins/opnform/plugin.jsonindex b16a0a705..06c2d2a72 100644--- a/plugins/opnform/plugin.json+++ b/plugins/opnform/plugin.json@@ -1,7 +1,7 @@{"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json","name": "opnform",- "version": "1.0.0",+ "version": "1.0.1","description": "Create, preview, and manage OpnForm forms and read their submissions with an AI agent.","author": {"name": "OpnForm",diff --git a/plugins/opnform/skills/opnform/SKILL.md b/plugins/opnform/skills/opnform/SKILL.mdindex 3af0eabf8..44effd756 100644--- a/plugins/opnform/skills/opnform/SKILL.md+++ b/plugins/opnform/skills/opnform/SKILL.md@@ -25,11 +25,12 @@ This is the default workflow for new-form requests, including when the user does1. Read `opnform://schemas/agent-form-definition/v1` and `opnform://reference/form-fields/v1` before generating a definition. Follow the field reference's `authoring_guidelines`. Re-read the field reference before changing presentation style, fields, layout, or media later in the conversation. Do not inspect the OpnForm source tree or guess product behavior when the MCP resources describe it.2. Perform the respondent-facing quality pass below, then call `validate_form_definition`. Resolve every validation error. Treat `quality_warnings` as non-blocking editorial guidance: correct relevant warnings before creating or saving while preserving intentional user choices.3. Call `create_form_draft` with the validated definition.-4. Keep the returned `draft_token` private. It is a capability secret: never quote it to the user, write it to a file, log it, or send it to another service.-5. Call `preview_form_draft` and present its interactive MCP preview when the host supports it.+4. Keep the returned `draft_handle` in tool context and pass it unchanged to guest draft tools. It is an internal opaque reference, not user-facing form content: do not quote it to the user, write it to a file, log it, or send it to another service.+5. Call `preview_form_draft` and present its interactive MCP preview when the host supports it. This is a read-only step and must not create an editor link.6. Apply requested changes with `patch_form_draft`, passing the latest `expected_version`. Validate the changed definition before persistence when needed.7. If the version conflicts or the current state is uncertain, call `get_form_draft`, reconcile the user's requested changes, validate again, and retry with the new version. Never overwrite blindly.-8. Offer to open the draft in OpnForm. Use the `editor_url` returned by the preview or call `open_form_draft_in_editor`. The handoff URL is reusable until the seven-day guest draft expires; generating another URL does not revoke earlier ones.+8. If a patch returns a validation error, correct the invalid operation and retry once with the same latest version. Report the returned validation problem accurately; do not turn a recoverable enum or field error into a generic “server error”.+9. Offer to open the draft in OpnForm. Call `open_form_draft_in_editor` only after the user chooses the preview's **Open in OpnForm** action or explicitly asks to continue in the editor. The returned handoff URL is reusable until the seven-day guest draft expires; generating another URL does not revoke earlier ones.The browser editor keeps the guest draft available through an HttpOnly session. The user can preview and edit before signing in. Authentication and workspace selection happen only when the user chooses to save the draft into an OpnForm account.@@ -57,6 +58,7 @@ The browser editor keeps the guest draft available through an HttpOnly session.- `classic` is a continuous form. Use widths for columns and `nf-page-break` only when the user wants explicit pagination.- `focused` is a Typeform-like flow: every visible block becomes one step automatically. Use full-width input blocks and concise `nf-text` intro steps. Remove `nf-page-break` and do not add standalone `nf-image`, `nf-divider`, `nf-code`, `nf-video`, or `nf-audio` blocks.+- Use the exact documented style values. In particular: `border_radius` is `none`, `small`, or `full`; `width` is `centered` or `full`; `size` is `sm`, `md`, or `lg`; and `theme` is `default`, `simple`, `notion`, `minimal`, or `transparent`. Never invent aliases such as `medium` or `large`.- To illustrate a focused step, add an `image` object to that input or `nf-text` block. Follow the layouts and media schema in `opnform://reference/form-fields/v1`; do not confuse this with the standalone `nf-image.image_block` shape.- Use only user-provided or durable public HTTPS image URLs. Never persist localhost, private addresses, temporary tunnel domains, expiring signed URLs, or asset paths found by reading the OpnForm repository.- Preserve the existing language, copy, field IDs, and unrelated settings unless the user asks to change them. For a focused conversion, usually set `settings.auto_next`, `settings.navigation_arrows`, and the localized `translations.focused_next_button_text` deliberately.@@ -88,7 +90,7 @@ Submission access requires OAuth. Authenticate only when the user's request need## Safety and recovery-- Treat draft tokens, editor handoffs, OAuth tokens, and export URLs as secrets.+- Keep internal draft handles out of user-facing text and logs. Treat editor handoffs, OAuth tokens, and export URLs as sensitive credentials.- If a preview or editor URL expires, call the appropriate tool for a fresh URL; never reconstruct one.- If authentication is unavailable, continue with guest-safe draft tools when the task permits it.- Never bypass confirmation, workspace permission, validation, revision checks, plan enforcement, or rate limits.