Merge pull request 'Fix/ios unsaved form navigation' (#180) from fix/ios-unsaved-form-navigation into main

Reviewed-on: #180

app/Actions/Tickets/Support/AcceptanceCriteriaChecklistMapper.php

@@ -44,7 +44,7 @@ class AcceptanceCriteriaChecklistMapper
     /**
      * @param  array<int, array{id?: int, checked: bool, indent: int, text: string}>  $items
      */
-    public static function syncTicket(Ticket $ticket, array $items): void
+    public static function syncTicket(Ticket $ticket, array $items, bool $reuseUnidentifiedCriteria = true): void
     {
         $normalized = self::normalize($items);
         $existingCriteria = $ticket->acceptanceCriteria()->get()->keyBy('id');
@@ -73,7 +73,8 @@ class AcceptanceCriteriaChecklistMapper
                 : $existingCriteria->get($criterionId);
 
             while (
-                $criterion === null
+                $reuseUnidentifiedCriteria
+                && $criterion === null
                 && $fallbackIndex < $fallbackCriteria->count()
             ) {
                 /** @var AcceptanceCriterion $candidate */

app/Actions/Tickets/Support/TicketDescriptionFormat.php

@@ -0,0 +1,78 @@
+<?php
+
+namespace App\Actions\Tickets\Support;
+
+use League\CommonMark\Environment\Environment;
+use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
+use League\CommonMark\Extension\CommonMark\Node\Block\HtmlBlock;
+use League\CommonMark\Extension\CommonMark\Node\Inline\HtmlInline;
+use League\CommonMark\Extension\CommonMark\Node\Inline\Image;
+use League\CommonMark\Extension\CommonMark\Node\Inline\Link;
+use League\CommonMark\Extension\GithubFlavoredMarkdownExtension;
+use League\CommonMark\Extension\Table\Table;
+use League\CommonMark\Extension\TaskList\TaskListItemMarker;
+use League\CommonMark\Parser\MarkdownParser;
+use League\Uri\Uri;
+
+class TicketDescriptionFormat
+{
+    /** @return array<string, mixed> */
+    public static function contract(): array
+    {
+        return once(fn (): array => json_decode(file_get_contents(resource_path('js/lib/ticket-description-format.json')), true, flags: JSON_THROW_ON_ERROR));
+    }
+
+    public static function instructions(): string
+    {
+        $contract = self::contract();
+
+        return implode(' ', array_map(fn (string $key): string => $contract[$key], ['format', 'supported', 'unsupported', 'links', 'criteria']))
+            ." Valid description example (Markdown string):\n".$contract['example'];
+    }
+
+    public static function criteriaInstructions(): string
+    {
+        return self::contract()['criteria'];
+    }
+
+    public static function safeLink(string $value): bool
+    {
+        $contract = self::contract();
+        $decoded = rawurldecode($value);
+        if (! mb_check_encoding($decoded, 'UTF-8') || preg_match('~'.$contract['unsafe_link_characters'].'~u', $decoded)
+            || ! preg_match('~'.$contract['link_prefix'].'~i', $value)) {
+            return false;
+        }
+        if (str_starts_with($value, '/') || str_starts_with($value, '#')) {
+            return true;
+        }
+        $url = Uri::tryNew($decoded);
+
+        return $url !== null && ($url->getScheme() === 'mailto' || (filled($url->getHost()) && ($url->getPort() ?? 0) <= 65535));
+    }
+
+    /** @return list<string> */
+    public static function unsupportedContent(string $value): array
+    {
+        $environment = new Environment;
+        $environment->addExtension(new CommonMarkCoreExtension);
+        $environment->addExtension(new GithubFlavoredMarkdownExtension);
+        $document = (new MarkdownParser($environment))->parse($value);
+        $unsupported = [];
+        foreach ($document->iterator() as $node) {
+            $type = match (true) {
+                $node instanceof HtmlBlock, $node instanceof HtmlInline => 'html',
+                $node instanceof Table => 'table',
+                $node instanceof Image => 'image',
+                $node instanceof TaskListItemMarker => 'task',
+                $node instanceof Link && ! self::safeLink($node->getUrl()) => 'unsafe_link',
+                default => null,
+            };
+            if ($type !== null) {
+                $unsupported[] = self::contract()['unsupported_tokens'][$type];
+            }
+        }
+
+        return array_values(array_unique($unsupported));
+    }
+}

app/Actions/Tickets/UpdateProjectTicket.php

@@ -51,6 +51,7 @@ class UpdateProjectTicket
         Ticket $ticket,
         User $actor,
         array $validated,
+        bool $replaceCriteriaWithIds = false,
     ): bool {
         $fieldValueAttributes = Arr::get($validated, 'field_values', []);
         $nextAcceptanceCriteria = AcceptanceCriteriaChecklistMapper::normalize(
@@ -58,7 +59,7 @@ class UpdateProjectTicket
         );
         $ticketAttributes = $this->buildTicketAttributes($ticket, $validated);
 
-        return DB::transaction(function () use ($actor, $fieldValueAttributes, $nextAcceptanceCriteria, $ticket, $ticketAttributes): bool {
+        return DB::transaction(function () use ($actor, $fieldValueAttributes, $nextAcceptanceCriteria, $replaceCriteriaWithIds, $ticket, $ticketAttributes): bool {
             if (! $ticketAttributes['is_blocked']) {
                 $ticketAttributes['blocked_comment'] = null;
             }
@@ -91,7 +92,9 @@ class UpdateProjectTicket
             /** @var Collection<int, TicketFieldValue> $existingFieldValues */
             $existingFieldValues = $ticket->fieldValues
                 ->keyBy('ticket_field_definition_id');
-            $currentAcceptanceCriteria = AcceptanceCriteriaChecklistMapper::fromModels($ticket->acceptanceCriteria);
+            $currentAcceptanceCriteria = $replaceCriteriaWithIds
+                ? AcceptanceCriteriaChecklistMapper::fromModelsWithIds($ticket->acceptanceCriteria)
+                : AcceptanceCriteriaChecklistMapper::fromModels($ticket->acceptanceCriteria);
 
             $changes = [];
             $summaryLabels = [];
@@ -209,7 +212,7 @@ class UpdateProjectTicket
             }
 
             if ($currentAcceptanceCriteria !== $nextAcceptanceCriteria) {
-                AcceptanceCriteriaChecklistMapper::syncTicket($ticket, $nextAcceptanceCriteria);
+                AcceptanceCriteriaChecklistMapper::syncTicket($ticket, $nextAcceptanceCriteria, ! $replaceCriteriaWithIds);
             }
 
             $fieldValueChangeSet = $this->syncProjectTicketFieldValues->handle(

app/Mcp/Servers/KanbanGitServer.php

@@ -2,24 +2,32 @@
 
 namespace App\Mcp\Servers;
 
+use App\Actions\Tickets\Support\TicketDescriptionFormat;
 use App\Mcp\Tools\CreateTicket;
+use App\Mcp\Tools\GetProjectConfiguration;
 use App\Mcp\Tools\GetTicket;
 use App\Mcp\Tools\ListMyAssignedTickets;
+use App\Mcp\Tools\ListProjects;
 use App\Mcp\Tools\ListTicketsByStatus;
 use App\Mcp\Tools\ListTicketTypes;
 use App\Mcp\Tools\MoveTicketStatus;
+use App\Mcp\Tools\SearchTickets;
+use App\Mcp\Tools\UpdateTicket;
 use App\Mcp\Tools\UpdateTicketAssignee;
 use App\Mcp\Tools\UpdateTicketDescription;
 use Laravel\Mcp\Server;
-use Laravel\Mcp\Server\Attributes\Instructions;
 use Laravel\Mcp\Server\Attributes\Name;
 use Laravel\Mcp\Server\Attributes\Version;
 
 #[Name('KanbanGit MCP')]
-#[Version('0.1.0')]
+#[Version('0.2.1')]
-#[Instructions('Use these tools to read, create, and update KanbanGit tickets with the authenticated application key owner permissions. Prefer stable IDs when available, especially project_id, ticket_id, ticket_type_id, and ticket_status_id. Use list_ticket_types to discover the available ticket types in a project. Use create_ticket with parent_ticket_id to create a child ticket.')]
 class KanbanGitServer extends Server
 {
+    protected function boot(): void
+    {
+        $this->instructions = 'Use these tools to read, create, and update KanbanGit tickets with the authenticated application key owner permissions. Prefer stable IDs when available, especially project_id, ticket_id, ticket_type_id, and ticket_status_id. Use list_projects and get_project_configuration to discover visible projects and current workflow metadata. Use get_ticket with ticket_id or ticket_key; use search_tickets for paginated discovery. Use list_ticket_types to discover types and create_ticket with parent_ticket_id to create children of parent-enabled tickets. Use update_ticket for partial updates and move_ticket_status separately for workflow transitions. '.TicketDescriptionFormat::instructions();
+    }
+
     protected array $tools = [
         ListMyAssignedTickets::class,
         ListTicketsByStatus::class,
@@ -29,6 +37,10 @@ class KanbanGitServer extends Server
         MoveTicketStatus::class,
         CreateTicket::class,
         ListTicketTypes::class,
+        ListProjects::class,
+        GetProjectConfiguration::class,
+        SearchTickets::class,
+        UpdateTicket::class,
     ];
 
     protected array $resources = [

app/Mcp/Support/DescribesTicketWriting.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace App\Mcp\Support;
+
+use App\Actions\Tickets\Support\TicketDescriptionFormat;
+
+trait DescribesTicketWriting
+{
+    public function description(): string
+    {
+        return parent::description().' '.TicketDescriptionFormat::instructions();
+    }
+}

app/Mcp/Support/KanbanGitMcp.php

@@ -13,6 +13,7 @@ use App\Models\TicketStatus;
 use App\Models\User;
 use Illuminate\Auth\Access\AuthorizationException;
 use Illuminate\Auth\AuthenticationException;
+use Illuminate\Contracts\Pagination\LengthAwarePaginator;
 use Illuminate\Support\Collection;
 use Illuminate\Validation\ValidationException;
 use Laravel\Mcp\Request;
@@ -78,6 +79,17 @@ class KanbanGitMcp
         return $ticket;
     }
 
+    public function ticketForKey(User $user, string $ticketKey): Ticket
+    {
+        $ticket = Ticket::query()->with('project')->where('ticket_key', $ticketKey)->first();
+        if ($ticket === null || $ticket->ticket_key !== $ticketKey) {
+            throw ValidationException::withMessages(['ticket_key' => 'Ticket was not found.']);
+        }
+        $this->ensureCanRead($user, $ticket->project);
+
+        return $ticket;
+    }
+
     /**
      * @throws AuthorizationException
      */
@@ -201,6 +213,18 @@ class KanbanGitMcp
         ));
     }
 
+    /** @return array{current_page: int, per_page: int, total: int, last_page: int, has_more_pages: bool} */
+    public function paginationPayload(LengthAwarePaginator $paginator): array
+    {
+        return [
+            'current_page' => $paginator->currentPage(),
+            'per_page' => $paginator->perPage(),
+            'total' => $paginator->total(),
+            'last_page' => $paginator->lastPage(),
+            'has_more_pages' => $paginator->hasMorePages(),
+        ];
+    }
+
     /**
      * @return array<string, mixed>
      */

app/Mcp/Support/TicketUpdateInput.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace App\Mcp\Support;
+
+use App\Actions\Tickets\Support\AcceptanceCriteriaChecklistMapper;
+use App\Http\Requests\UpdateProjectTicketRequest;
+use App\Models\Ticket;
+use App\Models\TicketFieldDefinition;
+use App\Models\User;
+use App\Rules\VisualTicketDescription;
+use Illuminate\Routing\Route;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\Validator;
+use Illuminate\Validation\Rule;
+use Illuminate\Validation\ValidationException;
+use Laravel\Mcp\Request;
+
+class TicketUpdateInput
+{
+    public function __construct(private readonly KanbanGitMcp $kanbanGitMcp) {}
+
+    /** @return array<string, mixed> */
+    public function validate(Request $request, Ticket $ticket, User $user): array
+    {
+        $form = new UpdateProjectTicketRequest;
+        $route = new Route('PUT', '/', fn () => null);
+        $route->bind(\Illuminate\Http\Request::create('/', 'PUT'));
+        $route->setParameter('project', $ticket->project);
+        $route->setParameter('ticket', $ticket);
+        $form->setRouteResolver(fn () => $route);
+        $form->setUserResolver(fn () => $user);
+        $rules = $form->rules();
+        foreach ($rules as $key => &$rule) {
+            if (! str_contains($key, '.')) {
+                $rule = ['sometimes', ...$rule];
+            }
+        }
+        unset($rule);
+        $rules['description'][] = new VisualTicketDescription;
+        $rules['acceptance_criteria'] = ['sometimes', 'array', 'list'];
+        $rules['acceptance_criteria.*'] = ['array:id,text,checked,indent'];
+        $rules['acceptance_criteria.*.id'] = ['sometimes', 'integer', 'min:1', 'distinct', Rule::exists('acceptance_criteria', 'id')->where('ticket_id', $ticket->id)];
+        $rules['acceptance_criteria.*.checked'] = ['sometimes', 'boolean'];
+        $rules['acceptance_criteria.*.indent'] = ['sometimes', 'integer', 'min:0', 'max:'.AcceptanceCriteriaChecklistMapper::MAX_INDENT_LEVEL];
+        $rules['field_values'] = ['sometimes', 'array', 'list'];
+        $rules['field_values.*'] = ['array:ticket_field_definition_id,value_number,value_user_id'];
+        $rules['field_values.*.ticket_field_definition_id'][] = 'distinct';
+        $rules['ticket_status_id'] = ['prohibited'];
+        $rules['acceptance_criteria.*.text'][] = function (string $attribute, mixed $value, \Closure $fail): void {
+            if (is_string($value) && trim($value) === '') {
+                $fail('Criterion text must not be blank.');
+            }
+        };
+        $input = $request->validate($rules);
+        $previousIndent = -1;
+        foreach (Arr::get($input, 'acceptance_criteria', []) as $index => $item) {
+            $indent = Arr::get($item, 'indent', 0);
+            if ($indent > $previousIndent + 1) {
+                throw ValidationException::withMessages(["acceptance_criteria.{$index}.indent" => 'Indentation cannot skip a level; the first item must have indent 0.']);
+            }
+            $previousIndent = $indent;
+        }
+        $merged = array_replace($this->kanbanGitMcp->updatePayload($ticket), $input);
+        $merged['acceptance_criteria'] = Arr::exists($input, 'acceptance_criteria')
+            ? AcceptanceCriteriaChecklistMapper::normalize($input['acceptance_criteria'])
+            : AcceptanceCriteriaChecklistMapper::fromModelsWithIds($ticket->acceptanceCriteria()->get());
+
+        $validator = Validator::make($merged, $form->rules());
+        $form->setValidator($validator);
+        $validator->validate();
+        foreach ($form->after() as $callback) {
+            $callback($validator);
+        }
+
+        $people = User::query()->visibleToProject($ticket->project)->pluck('id')->all();
+        foreach (['assignee_user_id', 'author_user_id'] as $field) {
+            if (Arr::exists($input, $field) && $input[$field] !== null && ! in_array((int) $input[$field], $people, true)) {
+                $validator->errors()->add($field, 'The person must be able to view this project.');
+            }
+        }
+        $definitions = $ticket->project->ticketFieldDefinitions()->get()->keyBy('id');
+        foreach (Arr::get($input, 'field_values', []) as $index => $value) {
+            $definition = $definitions->get($value['ticket_field_definition_id']);
+            $incompatible = $definition->field_type === 'user' ? 'value_number' : 'value_user_id';
+            if (Arr::get($value, $incompatible) !== null) {
+                $validator->errors()->add("field_values.{$index}.{$incompatible}", 'The value must match the custom field type.');
+            }
+            if (Arr::get($value, 'value_user_id') !== null && ! in_array((int) $value['value_user_id'], $people, true)) {
+                $validator->errors()->add("field_values.{$index}.value_user_id", 'The person must be able to view this project.');
+            }
+        }
+        if ($validator->errors()->isNotEmpty()) {
+            throw new ValidationException($validator);
+        }
+
+        if (Arr::exists($input, 'field_values')) {
+            $replacement = $definitions->map(fn (TicketFieldDefinition $definition): array => [
+                'ticket_field_definition_id' => $definition->id,
+                'value_number' => null,
+                'value_user_id' => null,
+            ])->all();
+            foreach ($input['field_values'] as $value) {
+                $replacement[$value['ticket_field_definition_id']] = $value;
+            }
+            $merged['field_values'] = array_values($replacement);
+        }
+
+        return $merged;
+    }
+}

app/Mcp/Tools/CreateTicket.php

@@ -5,11 +5,14 @@ namespace App\Mcp\Tools;
 use App\Actions\Permissions\PermissionService;
 use App\Actions\Tickets\CreateProjectTicket;
 use App\Actions\Tickets\Support\AcceptanceCriteriaChecklistMapper;
+use App\Actions\Tickets\Support\TicketDescriptionFormat;
 use App\Enums\Permission;
+use App\Mcp\Support\DescribesTicketWriting;
 use App\Mcp\Support\KanbanGitMcp;
 use App\Models\Project;
 use App\Models\Ticket;
 use App\Models\User;
+use App\Rules\VisualTicketDescription;
 use Illuminate\Contracts\JsonSchema\JsonSchema;
 use Illuminate\JsonSchema\Types\Type;
 use Illuminate\Support\Arr;
@@ -28,6 +31,8 @@ use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
 #[IsDestructive(false)]
 class CreateTicket extends Tool
 {
+    use DescribesTicketWriting;
+
     public function __construct(
         private readonly KanbanGitMcp $kanbanGitMcp,
         private readonly CreateProjectTicket $createProjectTicket,
@@ -44,7 +49,7 @@ class CreateTicket extends Tool
         $project = $this->kanbanGitMcp->projectForWrite($user, (int) Arr::get($projectInput, 'project_id'));
         $validated = $request->validate([
             'title' => ['required', 'string', 'max:255'],
-            'description' => ['nullable', 'string'],
+            'description' => ['nullable', 'string', new VisualTicketDescription],
             'ticket_type_id' => ['required', 'integer', Rule::exists('ticket_types', 'id')->where('project_id', $project->id)],
             'ticket_status_id' => ['required', 'integer', Rule::exists('ticket_statuses', 'id')->where('project_id', $project->id)],
             'ticket_priority_id' => ['required', 'integer', Rule::exists('ticket_priorities', 'id')->where('project_id', $project->id)],
@@ -140,7 +145,7 @@ class CreateTicket extends Tool
         return [
             'project_id' => $schema->integer()->description('Project ID.')->required(),
             'title' => $schema->string()->max(255)->description('Ticket title.')->required(),
-            'description' => $schema->string()->nullable()->description('Ticket description.'),
+            'description' => $schema->string()->nullable()->description('Ticket description. '.TicketDescriptionFormat::instructions()),
             'ticket_type_id' => $schema->integer()->description('Ticket type ID belonging to the project. Explicitly selects the type, including types that allow child tickets.')->required(),
             'ticket_status_id' => $schema->integer()->description('Initial ticket status ID belonging to the project.')->required(),
             'ticket_priority_id' => $schema->integer()->description('Ticket priority ID belonging to the project.')->required(),
@@ -156,7 +161,7 @@ class CreateTicket extends Tool
                     'checked' => $schema->boolean()->default(false),
                     'indent' => $schema->integer()->min(0)->max(AcceptanceCriteriaChecklistMapper::MAX_INDENT_LEVEL)->default(0),
                 ])->withoutAdditionalProperties())
-                ->description('Ordered acceptance checklist. Indent 0 is a root item; larger values nest under preceding items.'),
+                ->description('Ordered acceptance checklist. Indent 0 is a root item; larger values nest under preceding items. '.TicketDescriptionFormat::criteriaInstructions()),
             'field_values' => $schema->array()
                 ->items($schema->object([
                     'ticket_field_definition_id' => $schema->integer()->description('Custom field definition ID belonging to the project. Each definition may appear once.')->required(),

app/Mcp/Tools/GetProjectConfiguration.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace App\Mcp\Tools;
+
+use App\Actions\Permissions\PermissionService;
+use App\Enums\Permission;
+use App\Mcp\Support\KanbanGitMcp;
+use App\Models\TicketStatus;
+use App\Models\User;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Illuminate\JsonSchema\Types\Type;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
+
+#[Name('get_project_configuration')]
+#[Description('Get compact current configuration for a visible project: ordered columns, statuses with IDs/slugs/column assignment and allowed target status IDs, types, priorities, custom field definitions, and permitted people IDs/names. Reads live effective configuration, without template snapshots or full user/project objects. People are paginated (default 25, maximum 100); use people_page for subsequent pages. Author changes require project admin permission, reported in permissions.')]
+#[IsReadOnly]
+class GetProjectConfiguration extends Tool
+{
+    public function __construct(private readonly KanbanGitMcp $kanbanGitMcp, private readonly PermissionService $permissionService) {}
+
+    public function handle(Request $request): Response|ResponseFactory
+    {
+        $input = $request->validate([
+            'project_id' => ['required', 'integer'],
+            'people_page' => ['sometimes', 'integer', 'min:1'],
+            'people_per_page' => ['sometimes', 'integer', 'min:1', 'max:100'],
+        ]);
+        $user = $this->kanbanGitMcp->user($request);
+        $project = $this->kanbanGitMcp->projectForRead($user, $input['project_id']);
+        $people = User::query()->visibleToProject($project)->orderBy('id')->paginate($input['people_per_page'] ?? 25, ['id', 'name'], 'people_page', $input['people_page'] ?? 1);
+
+        $columns = $project->boardColumns()->orderBy('id')->get(['id', 'name', 'position']);
+        $columnPositions = $columns->pluck('position', 'id');
+        $statuses = $project->ticketStatuses()->with('allowedTargetStatuses')->get()->sortBy(
+            fn (TicketStatus $status): array => [$columnPositions->get($status->board_column_id, 0), $status->position, $status->id],
+        )->values();
+
+        return Response::structured([
+            'data' => [
+                'project' => ['id' => $project->id, 'key' => $project->key, 'name' => $project->name],
+                'permissions' => [
+                    'can_write' => $this->permissionService->allows($user, Permission::ProjectWrite, $project),
+                    'can_change_author' => $this->permissionService->allows($user, Permission::ProjectAdmin, $project),
+                ],
+                'board_columns' => $columns->toArray(),
+                'ticket_statuses' => $statuses->map(fn (TicketStatus $status): array => [
+                    'id' => $status->id, 'name' => $status->name, 'slug' => $status->slug,
+                    'position' => $status->position, 'board_column_id' => $status->board_column_id,
+                    'allowed_target_status_ids' => $status->allowedTargetStatuses->pluck('id')->all(),
+                ])->all(),
+                'ticket_types' => $project->ticketTypes()->orderBy('id')->get(['id', 'name', 'position', 'is_parent'])->toArray(),
+                'ticket_priorities' => $project->ticketPriorities()->orderBy('id')->get(['id', 'name', 'position'])->toArray(),
+                'ticket_field_definitions' => $project->ticketFieldDefinitions()->orderBy('id')->get(['id', 'label', 'field_type', 'position'])->toArray(),
+                'people' => $people->getCollection()->map(fn (User $person): array => ['id' => $person->id, 'name' => $person->name])->all(),
+            ],
+            'meta' => ['people' => $this->kanbanGitMcp->paginationPayload($people)],
+        ]);
+    }
+
+    /** @return array<string, Type> */
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'project_id' => $schema->integer()->description('Visible project ID from list_projects.')->required(),
+            'people_page' => $schema->integer()->min(1)->description('People page number, defaults to 1.'),
+            'people_per_page' => $schema->integer()->min(1)->max(100)->description('People page size, defaults to 25; maximum 100.'),
+        ];
+    }
+}

app/Mcp/Tools/GetTicket.php

@@ -14,7 +14,7 @@ use Laravel\Mcp\Server\Tool;
 use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
 
 #[Name('get_ticket')]
-#[Description('Get a visible ticket with project, status, type, priority, assignee, author, field values, and worklog data.')]
+#[Description('Get a visible ticket by exactly one of numeric ticket_id or exact full ticket_key (e.g. KAN-67), with project, status, type, priority, assignee, author, field values, and worklog data.')]
 #[IsReadOnly]
 class GetTicket extends Tool
 {
@@ -25,11 +25,14 @@ class GetTicket extends Tool
     public function handle(Request $request): Response|ResponseFactory
     {
         $validated = $request->validate([
-            'ticket_id' => ['required', 'integer'],
+            'ticket_id' => ['required_without:ticket_key', 'prohibits:ticket_key', 'integer'],
+            'ticket_key' => ['required_without:ticket_id', 'prohibits:ticket_id', 'string', 'regex:/^[A-Z0-9]+-[1-9][0-9]*$/'],
         ]);
 
         $user = $this->kanbanGitMcp->user($request);
-        $ticket = $this->kanbanGitMcp->ticketForRead($user, (int) $validated['ticket_id']);
+        $ticket = isset($validated['ticket_id'])
+            ? $this->kanbanGitMcp->ticketForRead($user, (int) $validated['ticket_id'])
+            : $this->kanbanGitMcp->ticketForKey($user, $validated['ticket_key']);
 
         return Response::structured([
             'data' => $this->kanbanGitMcp->ticketPayload($ticket),
@@ -43,8 +46,8 @@ class GetTicket extends Tool
     {
         return [
             'ticket_id' => $schema->integer()
-                ->description('Ticket ID.')
+                ->description('Ticket ID. Supply exactly one of ticket_id or ticket_key.'),
-                ->required(),
+            'ticket_key' => $schema->string()->description('Exact full ticket key, e.g. KAN-67. Supply exactly one of ticket_id or ticket_key.'),
         ];
     }
 }

app/Mcp/Tools/ListProjects.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace App\Mcp\Tools;
+
+use App\Actions\Permissions\PermissionService;
+use App\Mcp\Support\KanbanGitMcp;
+use App\Models\Project;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Illuminate\JsonSchema\Types\Type;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
+
+#[Name('list_projects')]
+#[Description('List visible projects independently of assigned tickets. Returns only ID, key and name, ordered by ID, with bounded pagination. page starts at 1; per_page defaults to 25 and may not exceed 100.')]
+#[IsReadOnly]
+class ListProjects extends Tool
+{
+    public function __construct(private readonly KanbanGitMcp $kanbanGitMcp, private readonly PermissionService $permissionService) {}
+
+    public function handle(Request $request): Response|ResponseFactory
+    {
+        $input = $request->validate(['page' => ['sometimes', 'integer', 'min:1'], 'per_page' => ['sometimes', 'integer', 'min:1', 'max:100']]);
+        $user = $this->kanbanGitMcp->user($request);
+        $projects = Project::query()->whereIn('id', $this->permissionService->viewableProjectIds($user))
+            ->orderBy('id')->paginate($input['per_page'] ?? 25, ['id', 'key', 'name'], 'page', $input['page'] ?? 1);
+
+        return Response::structured([
+            'data' => $projects->getCollection()->map(fn (Project $project): array => ['id' => $project->id, 'key' => $project->key, 'name' => $project->name])->all(),
+            'meta' => $this->kanbanGitMcp->paginationPayload($projects),
+        ]);
+    }
+
+    /** @return array<string, Type> */
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'page' => $schema->integer()->min(1)->description('Page number, defaults to 1.'),
+            'per_page' => $schema->integer()->min(1)->max(100)->description('Page size, defaults to 25; maximum 100.'),
+        ];
+    }
+}

app/Mcp/Tools/MoveTicketStatus.php

@@ -3,6 +3,7 @@
 namespace App\Mcp\Tools;
 
 use App\Actions\Tickets\MoveProjectTicket;
+use App\Mcp\Support\DescribesTicketWriting;
 use App\Mcp\Support\KanbanGitMcp;
 use Illuminate\Contracts\JsonSchema\JsonSchema;
 use Illuminate\JsonSchema\Types\Type;
@@ -19,6 +20,8 @@ use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
 #[IsDestructive(false)]
 class MoveTicketStatus extends Tool
 {
+    use DescribesTicketWriting;
+
     public function __construct(
         private readonly KanbanGitMcp $kanbanGitMcp,
         private readonly MoveProjectTicket $moveProjectTicket,

app/Mcp/Tools/SearchTickets.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace App\Mcp\Tools;
+
+use App\Actions\Permissions\PermissionService;
+use App\Mcp\Support\KanbanGitMcp;
+use App\Models\Ticket;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\JsonSchema\Types\Type;
+use Illuminate\Support\Arr;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
+
+#[Name('search_tickets')]
+#[Description('Search visible tickets with combined filters: exact full ticket key, literal text in title/description, project, status, type, assignee and parent. Omitted filters do not restrict results; assignee_user_id/parent_ticket_id null selects unassigned/top-level tickets. Returns compact ID, key, title, project ID and status with deterministic ID order and bounded pagination (default 25, maximum 100).')]
+#[IsReadOnly]
+class SearchTickets extends Tool
+{
+    public function __construct(private readonly KanbanGitMcp $kanbanGitMcp, private readonly PermissionService $permissionService) {}
+
+    public function handle(Request $request): Response|ResponseFactory
+    {
+        $input = $request->validate([
+            'ticket_key' => ['sometimes', 'string', 'regex:/^[A-Z0-9]+-[1-9][0-9]*$/'],
+            'query' => ['sometimes', 'string', 'max:255'],
+            'project_id' => ['sometimes', 'integer'],
+            'ticket_status_id' => ['sometimes', 'integer'],
+            'ticket_type_id' => ['sometimes', 'integer'],
+            'assignee_user_id' => ['sometimes', 'nullable', 'integer'],
+            'parent_ticket_id' => ['sometimes', 'nullable', 'integer'],
+            'page' => ['sometimes', 'integer', 'min:1'],
+            'per_page' => ['sometimes', 'integer', 'min:1', 'max:100'],
+        ]);
+        $user = $this->kanbanGitMcp->user($request);
+        $this->kanbanGitMcp->projectForRead($user, $input['project_id'] ?? null);
+        $query = Ticket::query()->whereIn('project_id', $this->permissionService->viewableProjectIds($user));
+        foreach (['ticket_key', 'project_id', 'ticket_status_id', 'ticket_type_id', 'assignee_user_id', 'parent_ticket_id'] as $filter) {
+            if (Arr::exists($input, $filter)) {
+                $query->where($filter, $input[$filter]);
+            }
+        }
+        if (Arr::exists($input, 'query')) {
+            $pattern = '%'.str_replace(['!', '%', '_'], ['!!', '!%', '!_'], $input['query']).'%';
+            $query->where(fn (Builder $q) => $q->whereRaw("title LIKE ? ESCAPE '!'", [$pattern])->orWhereRaw("description LIKE ? ESCAPE '!'", [$pattern]));
+        }
+        $tickets = $query->with('ticketStatus:id,name,slug,board_column_id')->orderBy('id')
+            ->paginate($input['per_page'] ?? 25, ['id', 'ticket_key', 'title', 'project_id', 'ticket_status_id'], 'page', $input['page'] ?? 1);
+
+        return Response::structured([
+            'data' => $tickets->getCollection()->map(fn (Ticket $ticket): array => [
+                'id' => $ticket->id,
+                'ticket_key' => $ticket->ticket_key,
+                'title' => $ticket->title,
+                'project_id' => $ticket->project_id,
+                'ticket_status_id' => $ticket->ticket_status_id,
+                'status' => $ticket->ticketStatus === null ? null : ['id' => $ticket->ticketStatus->id, 'name' => $ticket->ticketStatus->name, 'slug' => $ticket->ticketStatus->slug],
+            ])->all(),
+            'meta' => $this->kanbanGitMcp->paginationPayload($tickets),
+        ]);
+    }
+
+    /** @return array<string, Type> */
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'ticket_key' => $schema->string()->description('Exact full key, e.g. KAN-67.'),
+            'query' => $schema->string()->max(255)->description('Literal substring in title or description.'),
+            'project_id' => $schema->integer()->description('Visible project ID.'),
+            'ticket_status_id' => $schema->integer()->description('Status ID from get_project_configuration.'),
+            'ticket_type_id' => $schema->integer()->description('Type ID from get_project_configuration.'),
+            'assignee_user_id' => $schema->integer()->nullable()->description('Assignee ID; null selects unassigned tickets.'),
+            'parent_ticket_id' => $schema->integer()->nullable()->description('Parent ID; null selects top-level tickets.'),
+            'page' => $schema->integer()->min(1)->description('Page number, defaults to 1.'),
+            'per_page' => $schema->integer()->min(1)->max(100)->description('Page size, defaults to 25; maximum 100.'),
+        ];
+    }
+}

app/Mcp/Tools/UpdateTicket.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace App\Mcp\Tools;
+
+use App\Actions\Tickets\Support\TicketDescriptionFormat;
+use App\Actions\Tickets\UpdateProjectTicket;
+use App\Mcp\Support\DescribesTicketWriting;
+use App\Mcp\Support\KanbanGitMcp;
+use App\Mcp\Support\TicketUpdateInput;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Illuminate\JsonSchema\Types\Type;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
+
+#[Name('update_ticket')]
+#[Description('Partially update a ticket by ID using existing project permissions and ticket rules. Omitted fields stay unchanged. Explicit null clears nullable scalar fields only. acceptance_criteria and field_values replace their entire lists; [] clears a list and null is rejected. Checklist items with an existing ID retain their identity; omit id for a new item. Use move_ticket_status separately for workflow transitions. Author changes require project admin permission; people must be visible to the project.')]
+#[IsDestructive(false)]
+class UpdateTicket extends Tool
+{
+    use DescribesTicketWriting;
+
+    public function __construct(
+        private readonly KanbanGitMcp $kanbanGitMcp,
+        private readonly TicketUpdateInput $ticketUpdateInput,
+        private readonly UpdateProjectTicket $updateProjectTicket,
+    ) {}
+
+    public function handle(Request $request): Response|ResponseFactory
+    {
+        $selector = $request->validate(['ticket_id' => ['required', 'integer']]);
+        $user = $this->kanbanGitMcp->user($request);
+        $ticket = $this->kanbanGitMcp->ticketForWrite($user, (int) $selector['ticket_id']);
+        $validated = $this->ticketUpdateInput->validate($request, $ticket, $user);
+        $updated = $this->updateProjectTicket->handle($ticket, $user, $validated, true);
+
+        return Response::structured([
+            'data' => $this->kanbanGitMcp->ticketPayload($ticket->fresh()),
+            'meta' => ['updated' => $updated],
+        ]);
+    }
+
+    /** @return array<string, Type> */
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'ticket_id' => $schema->integer()->description('Existing ticket ID.')->required(),
+            'title' => $schema->string()->max(255)->description('Nonblank title; omit to preserve.'),
+            'description' => $schema->string()->nullable()->description('Description; null clears it. '.TicketDescriptionFormat::instructions()),
+            'ticket_type_id' => $schema->integer()->description('Type ID from get_project_configuration.'),
+            'ticket_priority_id' => $schema->integer()->description('Priority ID from get_project_configuration.'),
+            'parent_ticket_id' => $schema->integer()->nullable()->description('Parent-enabled ticket in this project; null removes the parent. Cycles are forbidden.'),
+            'assignee_user_id' => $schema->integer()->nullable()->description('Allowed person ID; null unassigns.'),
+            'author_user_id' => $schema->integer()->nullable()->description('Author ID; null clears. Changes require project admin permission.'),
+            'story_points' => $schema->integer()->min(0)->nullable()->description('Nonnegative estimate; null clears.'),
+            'is_blocked' => $schema->boolean()->description('Blocked state; true requires a nonblank blocker comment. Omit to preserve.'),
+            'blocked_comment' => $schema->string()->nullable()->description('Blocker reason; null clears only when the ticket is unblocked.'),
+            'acceptance_criteria' => $schema->array()->items($schema->object([
+                'id' => $schema->integer()->min(1)->description('Existing criterion ID belonging to this ticket. Omit for a new item. IDs must be unique.'),
+                'text' => $schema->string()->description('Nonblank criterion text.')->required(),
+                'checked' => $schema->boolean()->description('Checked state, defaults to false for supplied items.'),
+                'indent' => $schema->integer()->min(0)->max(8)->description('Indent level, defaults to 0; cannot skip a level.'),
+            ])->withoutAdditionalProperties())->description('Ordered replacement checklist. Omitted items are removed. [] clears; omit field to preserve; null is invalid. '.TicketDescriptionFormat::criteriaInstructions()),
+            'field_values' => $schema->array()->items($schema->object([
+                'ticket_field_definition_id' => $schema->integer()->description('Project field ID, supplied once.')->required(),
+                'value_number' => $schema->number()->nullable()->description('Value for a numeric field; null clears.'),
+                'value_user_id' => $schema->integer()->nullable()->description('Allowed person ID for a user field; null clears.'),
+            ])->withoutAdditionalProperties())->description('Replacement custom-field list. Omitted definitions are cleared. [] clears all; omit field to preserve; null is invalid.'),
+        ];
+    }
+}

app/Mcp/Tools/UpdateTicketAssignee.php

@@ -3,6 +3,7 @@
 namespace App\Mcp\Tools;
 
 use App\Actions\Tickets\UpdateProjectTicket;
+use App\Mcp\Support\DescribesTicketWriting;
 use App\Mcp\Support\KanbanGitMcp;
 use Illuminate\Contracts\JsonSchema\JsonSchema;
 use Illuminate\JsonSchema\Types\Type;
@@ -19,6 +20,8 @@ use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
 #[IsDestructive(false)]
 class UpdateTicketAssignee extends Tool
 {
+    use DescribesTicketWriting;
+
     public function __construct(
         private readonly KanbanGitMcp $kanbanGitMcp,
         private readonly UpdateProjectTicket $updateProjectTicket,

app/Mcp/Tools/UpdateTicketDescription.php

@@ -2,10 +2,14 @@
 
 namespace App\Mcp\Tools;
 
+use App\Actions\Tickets\Support\TicketDescriptionFormat;
 use App\Actions\Tickets\UpdateProjectTicket;
+use App\Mcp\Support\DescribesTicketWriting;
 use App\Mcp\Support\KanbanGitMcp;
+use App\Rules\VisualTicketDescription;
 use Illuminate\Contracts\JsonSchema\JsonSchema;
 use Illuminate\JsonSchema\Types\Type;
+use Illuminate\Support\Arr;
 use Laravel\Mcp\Request;
 use Laravel\Mcp\Response;
 use Laravel\Mcp\ResponseFactory;
@@ -19,6 +23,8 @@ use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
 #[IsDestructive(false)]
 class UpdateTicketDescription extends Tool
 {
+    use DescribesTicketWriting;
+
     public function __construct(
         private readonly KanbanGitMcp $kanbanGitMcp,
         private readonly UpdateProjectTicket $updateProjectTicket,
@@ -27,7 +33,7 @@ class UpdateTicketDescription extends Tool
     public function handle(Request $request): Response|ResponseFactory
     {
         $validated = $request->validate([
-            'description' => ['nullable', 'string'],
+            'description' => ['nullable', 'string', new VisualTicketDescription],
             'ticket_id' => ['required', 'integer'],
         ]);
 
@@ -35,7 +41,7 @@ class UpdateTicketDescription extends Tool
         $ticket = $this->kanbanGitMcp->ticketForWrite($user, (int) $validated['ticket_id']);
         $payload = [
             ...$this->kanbanGitMcp->updatePayload($ticket),
-            'description' => $validated['description'] ?? null,
+            ...(Arr::exists($validated, 'description') ? ['description' => Arr::get($validated, 'description')] : []),
         ];
 
         $wasUpdated = $this->updateProjectTicket->handle($ticket, $user, $payload);
@@ -58,7 +64,7 @@ class UpdateTicketDescription extends Tool
         return [
             'description' => $schema->string()
                 ->nullable()
-                ->description('New ticket description. Pass null to clear it.'),
+                ->description('New ticket description. Omit to preserve; pass null to clear it. '.TicketDescriptionFormat::instructions()),
             'ticket_id' => $schema->integer()
                 ->description('Ticket ID.')
                 ->required(),

app/Rules/VisualTicketDescription.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Rules;
+
+use App\Actions\Tickets\Support\TicketDescriptionFormat;
+use Closure;
+use Illuminate\Contracts\Validation\ValidationRule;
+
+class VisualTicketDescription implements ValidationRule
+{
+    public function validate(string $attribute, mixed $value, Closure $fail): void
+    {
+        if (! is_string($value)) {
+            return;
+        }
+        $unsupported = TicketDescriptionFormat::unsupportedContent($value);
+        if ($unsupported !== []) {
+            $fail('The description contains unsupported '.implode(', ', $unsupported).'. Remove these contents or show literal examples inside code. Use ordinary Markdown and safe links; put acceptance criteria only in acceptance_criteria. No ticket fields were changed.');
+        }
+    }
+}

native/package.json

@@ -1,6 +1,6 @@
 {
     "name": "kanbangit-native",
-    "version": "0.2.6",
+    "version": "0.2.8",
     "private": true,
     "type": "module",
     "scripts": {
@@ -25,5 +25,5 @@
     "devDependencies": {
         "@tauri-apps/cli": "2.11.4"
     },
-    "releaseNotes": "Manage local workspace settings in the web app on macOS and iOS, with shared macOS update controls and native recovery for older or unavailable servers."
+    "releaseNotes": "Fix blocked navigation after changing project creation options or other forms on iOS by displaying native confirmations for unsaved changes. Pending confirmations close safely when changing workspaces."
 }

native/src-tauri/Cargo.lock

@@ -1770,7 +1770,7 @@ dependencies = [
 
 [[package]]
 name = "kanbangit-native"
-version = "0.2.6"
+version = "0.2.8"
 dependencies = [
  "semver",
  "serde",

native/src-tauri/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kanbangit-native"
-version = "0.2.6"
+version = "0.2.8"
 description = "KanbanGit native application"
 edition = "2021"
 publish = false

native/src-tauri/gen/apple/Sources/kanbangit-native/WorkspaceViewController.swift

@@ -43,6 +43,7 @@ final class WorkspaceViewController: UIViewController, WKNavigationDelegate, WKU
     private var settingsAvailable = false
     private var toolbarHeight: NSLayoutConstraint!
     private var appearance: UISegmentedControl!
+    private var javaScriptConfirmation: (alert: UIAlertController, completion: (Bool) -> Void)?
 
     init(defaults: UserDefaults = .standard) {
         self.defaults = defaults
@@ -51,6 +52,8 @@ final class WorkspaceViewController: UIViewController, WKNavigationDelegate, WKU
 
     required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
 
+    deinit { javaScriptConfirmation?.completion(false) }
+
     private func text(_ key: String) -> String {
         NSLocalizedString(key, comment: "KanbanGit iOS workspace")
     }
@@ -199,6 +202,7 @@ final class WorkspaceViewController: UIViewController, WKNavigationDelegate, WKU
 
     func open(_ url: URL) {
         if server?.url == url, connection.ready { showWorkspace(); return }
+        completeJavaScriptConfirmation(false)
         let selected = WorkspaceServer.selecting(url, current: server)
         guard let data = try? JSONEncoder().encode(selected) else { status.text = text("storageError"); return }
         defaults.set(data, forKey: serverKey)
@@ -265,6 +269,7 @@ final class WorkspaceViewController: UIViewController, WKNavigationDelegate, WKU
     }
 
     @objc private func showSettings() {
+        completeJavaScriptConfirmation(false)
         loading.stopAnimating()
         view.endEditing(true)
         launcher.isHidden = false
@@ -320,6 +325,39 @@ final class WorkspaceViewController: UIViewController, WKNavigationDelegate, WKU
         }
     }
 
+    func webView(_ webView: WKWebView, runJavaScriptConfirmPanelWithMessage message: String,
+                 initiatedByFrame frame: WKFrameInfo, completionHandler: @escaping (Bool) -> Void) {
+        guard webView === workspace, viewIfLoaded?.window != nil,
+              presentedViewController == nil, javaScriptConfirmation == nil else {
+            completionHandler(false)
+            return
+        }
+        let alert = UIAlertController(title: frame.request.url?.host ?? text("appName"),
+                                      message: message, preferredStyle: .alert)
+        let cancel = UIAlertAction(title: text("cancel"), style: .cancel) { [weak self] _ in
+            self?.completeJavaScriptConfirmation(false)
+        }
+        alert.addAction(cancel)
+        alert.addAction(UIAlertAction(title: text("ok"), style: .default) { [weak self] _ in
+            self?.completeJavaScriptConfirmation(true)
+        })
+        alert.preferredAction = cancel
+        javaScriptConfirmation = (alert, completionHandler)
+        present(alert, animated: true)
+    }
+
+    func completeJavaScriptConfirmation(_ accepted: Bool) {
+        guard let confirmation = javaScriptConfirmation else { return }
+        javaScriptConfirmation = nil
+        if confirmation.alert.presentingViewController == nil {
+            confirmation.completion(accepted)
+        } else {
+            confirmation.alert.dismiss(animated: false) {
+                confirmation.completion(accepted)
+            }
+        }
+    }
+
     func webView(_ webView: WKWebView, decidePolicyFor action: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
         guard webView === workspace, let url = action.request.url else { decisionHandler(.cancel); return }
         guard server?.allows(url) == true else {

native/src-tauri/gen/apple/Sources/kanbangit-native/en.lproj/Localizable.strings

@@ -9,6 +9,7 @@
 "switchWarning" = "Switching servers closes the current workspace and discards unsaved inputs. You will sign in separately on the new server.";
 "confirmSwitch" = "Switch server";
 "cancel" = "Cancel";
+"ok" = "OK";
 "connecting" = "Connecting to your server…";
 "connected" = "Your workspace is open. Use Server settings to change servers.";
 "connectionError" = "The server did not finish loading. Check your connection, server address and HTTPS certificate, then try again. An already open workspace and its inputs are kept.";

native/src-tauri/gen/apple/Tests/WorkspaceTests.swift

@@ -135,6 +135,94 @@ final class WorkspaceTests: XCTestCase {
                       "Changing workspaces must retain native gesture navigation")
     }
 
+    @MainActor
+    func testDirtyFormNavigationPresentsNativeConfirmation() async throws {
+        let animationsEnabled = UIView.areAnimationsEnabled
+        UIView.setAnimationsEnabled(false)
+        defer { UIView.setAnimationsEnabled(animationsEnabled) }
+        let name = "ios-confirmation-\(UUID())"
+        let defaults = try XCTUnwrap(UserDefaults(suiteName: name))
+        defer { defaults.removePersistentDomain(forName: name) }
+        let controller = WorkspaceViewController(defaults: defaults)
+        let window = UIWindow(frame: UIScreen.main.bounds)
+        window.rootViewController = controller
+        window.makeKeyAndVisible()
+        defer { window.isHidden = true; window.rootViewController = nil }
+        let url = URL(string: "https://example.invalid/")!
+        controller.open(url)
+        let webview = try XCTUnwrap(controller.workspace)
+        webview.stopLoading()
+        webview.loadSimulatedRequest(URLRequest(url: url.appendingPathComponent("projects/create")), responseHTML: """
+            <html><body><input id="duplicate" type="radio"><input id="draft" value="Unsaved project">
+            <a id="back" href="#back">Back</a><script>
+            window.visits = 0;
+            document.querySelector('#back').onclick = event => {
+                event.preventDefault();
+                if (!document.querySelector('#duplicate').checked || confirm('Discard unsaved changes?')) window.visits++;
+            };
+            </script></body></html>
+            """)
+        try await waitFor(webview, "document.readyState === 'complete' && typeof window.visits === 'number'")
+        _ = try await webview.evaluateJavaScript("document.querySelector('#back').click(); true")
+        let pristineVisits = try await webview.evaluateJavaScript("window.visits")
+        XCTAssertEqual(pristineVisits as? Int, 1)
+        XCTAssertNil(controller.presentedViewController)
+        _ = try await webview.evaluateJavaScript("document.querySelector('#duplicate').click(); true")
+        var expectedVisits = 1
+        for (index, accepted) in [false, true, false, true].enumerated() {
+            let click = Task { try await webview.evaluateJavaScript("document.querySelector('#back').click(); true") }
+            let alert = try await waitForConfirmation(controller)
+            XCTAssertEqual(alert.title, "example.invalid")
+            XCTAssertEqual(alert.message, "Discard unsaved changes?")
+            XCTAssertEqual(alert.actions.map(\.style), [.cancel, .default])
+            XCTAssertTrue(alert.preferredAction === alert.actions.first, "The default action must preserve the draft")
+            if index == 3 {
+                await withCheckedContinuation { continuation in
+                    alert.dismiss(animated: false) { continuation.resume() }
+                }
+            }
+            controller.completeJavaScriptConfirmation(accepted)
+            controller.completeJavaScriptConfirmation(!accepted)
+            _ = try await click.value
+            if accepted { expectedVisits += 1 }
+            let visits = try await webview.evaluateJavaScript("window.visits")
+            XCTAssertEqual(visits as? Int, expectedVisits, "Only accepted visits may run, exactly once each")
+            let draft = try await webview.evaluateJavaScript("document.querySelector('#draft').value")
+            XCTAssertEqual(draft as? String, "Unsaved project")
+            XCTAssertNil(controller.presentedViewController)
+        }
+
+        let otherAlert = UIAlertController(title: "Already open", message: nil, preferredStyle: .alert)
+        controller.present(otherAlert, animated: false)
+        let blocked = try await webview.evaluateJavaScript("confirm('Another dialog')")
+        XCTAssertEqual(blocked as? Bool, false, "A blocked presentation must release JavaScript")
+        XCTAssertTrue(controller.presentedViewController === otherAlert)
+        await withCheckedContinuation { continuation in
+            otherAlert.dismiss(animated: false) { continuation.resume() }
+        }
+
+        let pendingClick = Task { try await webview.evaluateJavaScript("document.querySelector('#back').click(); true") }
+        _ = try await waitForConfirmation(controller)
+        controller.open(URL(string: "https://other.invalid/")!)
+        _ = try await pendingClick.value
+        XCTAssertNil(controller.presentedViewController, "Replacing a workspace must dismiss its confirmation")
+        let oldVisits = try await webview.evaluateJavaScript("window.visits")
+        XCTAssertEqual(oldVisits as? Int, expectedVisits)
+        let stale = try await webview.evaluateJavaScript("confirm('Previous workspace')")
+        XCTAssertEqual(stale as? Bool, false, "A previous workspace must not present new confirmations")
+        XCTAssertNil(controller.presentedViewController)
+    }
+
+    @MainActor
+    private func waitForConfirmation(_ controller: WorkspaceViewController) async throws -> UIAlertController {
+        for _ in 0..<100 {
+            if let alert = controller.presentedViewController as? UIAlertController, !alert.isBeingPresented { return alert }
+            try await Task.sleep(for: .milliseconds(50))
+        }
+        return try XCTUnwrap(controller.presentedViewController as? UIAlertController,
+                             "Dirty forms must offer a visible confirmation instead of silently cancelling navigation")
+    }
+
     func testSettingsProtocolRejectsUnsupportedActionsAndInvalidPayloads() throws {
         for body in [
             #"{"version":2,"id":1,"action":"getState","payload":{}}"#,

native/src-tauri/gen/apple/kanbangit-native.xcodeproj/project.pbxproj

@@ -33,6 +33,13 @@
 /* End PBXBuildFile section */
 
 /* Begin PBXContainerItemProxy section */
+		1C790E40E71919331C1C4F34 /* PBXContainerItemProxy */ = {
+			isa = PBXContainerItemProxy;
+			containerPortal = AA6AD2A91A9E86D319D86D59 /* Project object */;
+			proxyType = 1;
+			remoteGlobalIDString = 721CF221CEDDC28FF2C5EBD5;
+			remoteInfo = "kanbangit-native_iOS";
+		};
 		8665A25D07C5F1A295164797 /* PBXContainerItemProxy */ = {
 			isa = PBXContainerItemProxy;
 			containerPortal = AA6AD2A91A9E86D319D86D59 /* Project object */;
@@ -48,7 +55,6 @@
 		08DF9B2F499E1EB89EB39BC5 /* WorkspaceTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WorkspaceTests.swift; sourceTree = "<group>"; };
 		0CF713E7BFE3F6B5BAA3550E /* CoreGraphics.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = CoreGraphics.framework; path = System/Library/Frameworks/CoreGraphics.framework; sourceTree = SDKROOT; };
 		1CDE5C303A96423E2E6A194D /* settings.rs */ = {isa = PBXFileReference; path = settings.rs; sourceTree = "<group>"; };
-		23960010246A2A72E9940D3F /* kanbangit-native_iOS.app */ = {isa = PBXFileReference; includeInIndex = 0; lastKnownFileType = wrapper.application; path = "kanbangit-native_iOS.app"; sourceTree = BUILT_PRODUCTS_DIR; };
 		2B96972F58CC158AB3DFF94A /* lib.rs */ = {isa = PBXFileReference; path = lib.rs; sourceTree = "<group>"; };
 		31630170C358EA8657E34854 /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = Assets.xcassets; sourceTree = "<group>"; };
 		47C531812A31207F97A89C5F /* en */ = {isa = PBXFileReference; lastKnownFileType = text.plist.strings; name = en; path = en.lproj/InfoPlist.strings; sourceTree = "<group>"; };
@@ -67,6 +73,7 @@
 		946BA5CC3FD90AD90D101A36 /* kanbangit-native_iOS.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = "kanbangit-native_iOS.entitlements"; sourceTree = "<group>"; };
 		9C56BE6890F0452F69D64795 /* android.rs */ = {isa = PBXFileReference; path = android.rs; sourceTree = "<group>"; };
 		9CAD0AE17A7966154CA29001 /* WorkspaceUITests.xctest */ = {isa = PBXFileReference; includeInIndex = 0; lastKnownFileType = wrapper.cfbundle; path = WorkspaceUITests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
+		9E29B2FA90E1D53F604961F6 /* KanbanGit.app */ = {isa = PBXFileReference; includeInIndex = 0; lastKnownFileType = wrapper.application; path = KanbanGit.app; sourceTree = BUILT_PRODUCTS_DIR; };
 		A372EBDD353022BDB3E78972 /* WorkspaceTests.xctest */ = {isa = PBXFileReference; includeInIndex = 0; lastKnownFileType = wrapper.cfbundle; path = WorkspaceTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
 		AEBAD9ABE758897C50BC1F2E /* locale.rs */ = {isa = PBXFileReference; path = locale.rs; sourceTree = "<group>"; };
 		BD66652CEDB88ADBAD0A87BA /* workspace-settings.js */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.javascript; path = "workspace-settings.js"; sourceTree = "<group>"; };
@@ -189,7 +196,7 @@
 		59D2DE9FD94E6D2D64CB0117 /* Products */ = {
 			isa = PBXGroup;
 			children = (
-				23960010246A2A72E9940D3F /* kanbangit-native_iOS.app */,
+				9E29B2FA90E1D53F604961F6 /* KanbanGit.app */,
 				A372EBDD353022BDB3E78972 /* WorkspaceTests.xctest */,
 				9CAD0AE17A7966154CA29001 /* WorkspaceUITests.xctest */,
 			);
@@ -248,7 +255,7 @@
 			packageProductDependencies = (
 			);
 			productName = "kanbangit-native_iOS";
-			productReference = 23960010246A2A72E9940D3F /* kanbangit-native_iOS.app */;
+			productReference = 9E29B2FA90E1D53F604961F6 /* KanbanGit.app */;
 			productType = "com.apple.product-type.application";
 		};
 		988CFF304CB81C8F3A4D6612 /* WorkspaceUITests */ = {
@@ -279,6 +286,7 @@
 			buildRules = (
 			);
 			dependencies = (
+				DEBBEA8683567208E49E40A5 /* PBXTargetDependency */,
 			);
 			name = WorkspaceTests;
 			packageProductDependencies = (
@@ -418,6 +426,11 @@
 			target = 721CF221CEDDC28FF2C5EBD5 /* kanbangit-native_iOS */;
 			targetProxy = 8665A25D07C5F1A295164797 /* PBXContainerItemProxy */;
 		};
+		DEBBEA8683567208E49E40A5 /* PBXTargetDependency */ = {
+			isa = PBXTargetDependency;
+			target = 721CF221CEDDC28FF2C5EBD5 /* kanbangit-native_iOS */;
+			targetProxy = 1C790E40E71919331C1C4F34 /* PBXContainerItemProxy */;
+		};
 /* End PBXTargetDependency section */
 
 /* Begin PBXVariantGroup section */
@@ -451,7 +464,7 @@
 				CODE_SIGN_ENTITLEMENTS = "kanbangit-native_iOS/kanbangit-native_iOS.entitlements";
 				CODE_SIGN_IDENTITY = "Apple Distribution";
 				CODE_SIGN_STYLE = Manual;
-				CURRENT_PROJECT_VERSION = 6;
+				CURRENT_PROJECT_VERSION = 7;
 				DEVELOPMENT_TEAM = ZZX2KZGTHU;
 				ENABLE_BITCODE = NO;
 				ENABLE_USER_SCRIPT_SANDBOXING = NO;
@@ -467,7 +480,7 @@
 				);
 				"LIBRARY_SEARCH_PATHS[arch=arm64]" = "$(inherited) $(PROJECT_DIR)/Externals/arm64/$(CONFIGURATION) $(SDKROOT)/usr/lib/swift $(DEVELOPER_DIR)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift/$(PLATFORM_NAME) $(DEVELOPER_DIR)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift-5.0/$(PLATFORM_NAME)";
 				"LIBRARY_SEARCH_PATHS[arch=x86_64]" = "$(inherited) $(PROJECT_DIR)/Externals/x86_64/$(CONFIGURATION) $(SDKROOT)/usr/lib/swift $(DEVELOPER_DIR)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift/$(PLATFORM_NAME) $(DEVELOPER_DIR)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift-5.0/$(PLATFORM_NAME)";
-				MARKETING_VERSION = 0.2.6;
+				MARKETING_VERSION = 0.2.8;
 				PRODUCT_BUNDLE_IDENTIFIER = de.kanbangit.ios;
 				PRODUCT_MODULE_NAME = KanbanGitNative;
 				PRODUCT_NAME = KanbanGit;
@@ -628,7 +641,7 @@
 				CODE_SIGN_ENTITLEMENTS = "kanbangit-native_iOS/kanbangit-native_iOS.entitlements";
 				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Manual;
-				CURRENT_PROJECT_VERSION = 6;
+				CURRENT_PROJECT_VERSION = 7;
 				DEVELOPMENT_TEAM = ZZX2KZGTHU;
 				ENABLE_BITCODE = NO;
 				ENABLE_USER_SCRIPT_SANDBOXING = NO;
@@ -644,7 +657,7 @@
 				);
 				"LIBRARY_SEARCH_PATHS[arch=arm64]" = "$(inherited) $(PROJECT_DIR)/Externals/arm64/$(CONFIGURATION) $(SDKROOT)/usr/lib/swift $(DEVELOPER_DIR)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift/$(PLATFORM_NAME) $(DEVELOPER_DIR)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift-5.0/$(PLATFORM_NAME)";
 				"LIBRARY_SEARCH_PATHS[arch=x86_64]" = "$(inherited) $(PROJECT_DIR)/Externals/x86_64/$(CONFIGURATION) $(SDKROOT)/usr/lib/swift $(DEVELOPER_DIR)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift/$(PLATFORM_NAME) $(DEVELOPER_DIR)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift-5.0/$(PLATFORM_NAME)";
-				MARKETING_VERSION = 0.2.6;
+				MARKETING_VERSION = 0.2.8;
 				PRODUCT_BUNDLE_IDENTIFIER = de.kanbangit.ios;
 				PRODUCT_MODULE_NAME = KanbanGitNative;
 				PRODUCT_NAME = KanbanGit;
@@ -691,6 +704,7 @@
 				SDKROOT = iphoneos;
 				SWIFT_VERSION = 5.0;
 				TARGETED_DEVICE_FAMILY = "1,2";
+				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/KanbanGit.app/KanbanGit";
 			};
 			name = debug;
 		};
@@ -710,6 +724,7 @@
 				SDKROOT = iphoneos;
 				SWIFT_VERSION = 5.0;
 				TARGETED_DEVICE_FAMILY = "1,2";
+				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/KanbanGit.app/KanbanGit";
 			};
 			name = release;
 		};

native/src-tauri/gen/apple/project.yml

@@ -18,8 +18,8 @@ settingGroups:
       DEVELOPMENT_TEAM: ZZX2KZGTHU
       ENABLE_USER_SCRIPT_SANDBOXING: false
       PRODUCT_BUNDLE_IDENTIFIER: de.kanbangit.ios
-      MARKETING_VERSION: "0.2.6"
+      MARKETING_VERSION: "0.2.8"
-      CURRENT_PROJECT_VERSION: "6"
+      CURRENT_PROJECT_VERSION: "7"
     configs:
       debug:
         CODE_SIGN_IDENTITY: Apple Development
@@ -40,6 +40,7 @@ targets:
   kanbangit-native_iOS:
     type: application
     platform: iOS
+    productName: KanbanGit
     sources:
       - path: Sources
       - path: ../../../ui/workspace-navigation.js
@@ -115,6 +116,8 @@ targets:
   WorkspaceTests:
     type: bundle.unit-test
     platform: iOS
+    dependencies:
+      - target: kanbangit-native_iOS
     sources:
       - path: ../../../ui/workspace-navigation.js
       - path: ../../../ui/workspace-settings.js
@@ -126,6 +129,7 @@ targets:
       base:
         GENERATE_INFOPLIST_FILE: YES
         PRODUCT_BUNDLE_IDENTIFIER: de.kanbangit.ios.tests
+        TEST_HOST: $(BUILT_PRODUCTS_DIR)/KanbanGit.app/KanbanGit
         DEVELOPMENT_TEAM: ZZX2KZGTHU
         CODE_SIGN_STYLE: Manual
         SWIFT_VERSION: "5.0"

native/src-tauri/src/navigation.m

@@ -1,6 +1,55 @@
+#import <AppKit/AppKit.h>
 #import <WebKit/WebKit.h>
+#import <objc/runtime.h>
+
+@interface KanbanWorkspaceUIDelegate : NSObject <WKUIDelegate>
+@property(nonatomic, strong) id<WKUIDelegate> originalDelegate;
+@end
+
+@implementation KanbanWorkspaceUIDelegate
+- (BOOL)respondsToSelector:(SEL)selector {
+    return [super respondsToSelector:selector] || [self.originalDelegate respondsToSelector:selector];
+}
+
+- (id)forwardingTargetForSelector:(SEL)selector {
+    if ([self.originalDelegate respondsToSelector:selector]) {
+        return self.originalDelegate;
+    }
+    return [super forwardingTargetForSelector:selector];
+}
+
+- (void)webView:(WKWebView *)webView runJavaScriptConfirmPanelWithMessage:(NSString *)message
+        initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)(BOOL))completionHandler {
+    NSWindow *window = webView.window;
+    if (!window || window.attachedSheet) {
+        completionHandler(NO);
+        return;
+    }
+
+    NSAlert *alert = [NSAlert new];
+    alert.alertStyle = NSAlertStyleWarning;
+    alert.messageText = frame.request.URL.host ?: @"KanbanGit";
+    alert.informativeText = message;
+    [alert addButtonWithTitle:@"OK"];
+    [alert addButtonWithTitle:@"Cancel"];
+    [alert beginSheetModalForWindow:window completionHandler:^(NSModalResponse response) {
+        completionHandler(response == NSAlertFirstButtonReturn);
+    }];
+}
+@end
+
+static char workspaceUIDelegateKey;
 
 void install_workspace_navigation(void *pointer) {
     WKWebView *webview = (__bridge WKWebView *)pointer;
     webview.allowsBackForwardNavigationGestures = YES;
+    if ([webview.UIDelegate isKindOfClass:KanbanWorkspaceUIDelegate.class]) {
+        return;
+    }
+
+    KanbanWorkspaceUIDelegate *delegate = [KanbanWorkspaceUIDelegate new];
+    delegate.originalDelegate = webview.UIDelegate;
+    // WKWebView keeps a weak UI delegate, so retain the forwarding adapter with its view.
+    objc_setAssociatedObject(webview, &workspaceUIDelegateKey, delegate, OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+    webview.UIDelegate = delegate;
 }

native/src-tauri/tauri.conf.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://schema.tauri.app/config/2",
     "productName": "KanbanGit",
-    "version": "0.2.6",
+    "version": "0.2.8",
     "identifier": "de.kanbangit.desktop",
     "build": {
         "frontendDist": "../ui"
@@ -25,7 +25,7 @@
         ],
         "macOS": {
             "minimumSystemVersion": "14.0",
-            "bundleVersion": "11",
+            "bundleVersion": "12",
             "dmg": {
                 "windowSize": {
                     "width": 660,

native/src-tauri/tauri.ios.conf.json

@@ -5,7 +5,7 @@
         "iOS": {
             "minimumSystemVersion": "17.0",
             "developmentTeam": "ZZX2KZGTHU",
-            "bundleVersion": "6"
+            "bundleVersion": "7"
         }
     }
 }

native/tests/navigation-macos.m

@@ -17,6 +17,53 @@ static void waitUntil(BOOL (^condition)(void), NSString *message) {
     check(condition(), message);
 }
 
+static id evaluate(WKWebView *webview, NSString *script) {
+    __block BOOL finished = NO;
+    __block id result;
+    [webview evaluateJavaScript:script completionHandler:^(id value, NSError *error) {
+        check(error == nil, error.localizedDescription);
+        result = value;
+        finished = YES;
+    }];
+    waitUntil(^BOOL { return finished; }, @"JavaScript must finish after the confirmation is dismissed");
+    return result;
+}
+
+static NSButton *findButton(NSView *view, NSString *title) {
+    if ([view isKindOfClass:NSButton.class] && [((NSButton *)view).title isEqualToString:title]) {
+        return (NSButton *)view;
+    }
+    for (NSView *child in view.subviews) {
+        NSButton *button = findButton(child, title);
+        if (button) { return button; }
+    }
+    return nil;
+}
+
+static BOOL containsText(NSView *view, NSString *text) {
+    if ([view isKindOfClass:NSTextField.class] && [((NSTextField *)view).stringValue isEqualToString:text]) {
+        return YES;
+    }
+    for (NSView *child in view.subviews) {
+        if (containsText(child, text)) { return YES; }
+    }
+    return NO;
+}
+
+@interface WorkspaceUI : NSObject <WKUIDelegate>
+@property(nonatomic) BOOL closed;
+@property(nonatomic) BOOL uploaded;
+@end
+
+@implementation WorkspaceUI
+- (void)webViewDidClose:(WKWebView *)webView { self.closed = YES; }
+- (void)webView:(WKWebView *)webView runOpenPanelWithParameters:(WKOpenPanelParameters *)parameters
+        initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)(NSArray<NSURL *> *))completionHandler {
+    self.uploaded = YES;
+    completionHandler(nil);
+}
+@end
+
 @interface WorkspacePages : NSObject <WKURLSchemeHandler, WKNavigationDelegate>
 @property(nonatomic) NSUInteger finished;
 @end
@@ -46,9 +93,18 @@ int main(void) {
         [configuration setURLSchemeHandler:pages forURLScheme:@"kanban-test"];
         WKWebView *webview = [[WKWebView alloc] initWithFrame:NSMakeRect(0, 0, 800, 600) configuration:configuration];
         webview.navigationDelegate = pages;
+        WorkspaceUI *originalUI = [WorkspaceUI new];
+        webview.UIDelegate = originalUI;
         check(!webview.allowsBackForwardNavigationGestures, @"WebKit defaults to disabled gestures");
         install_workspace_navigation((__bridge void *)webview);
+        id<WKUIDelegate> installedUI = webview.UIDelegate;
         install_workspace_navigation((__bridge void *)webview);
+        check(webview.UIDelegate == installedUI, @"Installing workspace behavior twice must retain the same delegate");
+        check([installedUI respondsToSelector:@selector(webViewDidClose:)], @"Existing popup callbacks must remain available");
+        [installedUI webViewDidClose:webview];
+        check(originalUI.closed, @"Existing popup callbacks must reach the original delegate");
+        check([installedUI respondsToSelector:@selector(webView:runOpenPanelWithParameters:initiatedByFrame:completionHandler:)],
+            @"Existing file upload callbacks must remain available");
         check(webview.allowsBackForwardNavigationGestures, @"The workspace must enable WebKit's interactive gestures");
         check(webview.configuration.userContentController.userScripts.count == 0, @"Enabling gestures must not inject a history adapter");
         check([webview goBack] == nil && [webview goForward] == nil, @"Empty history must not navigate");
@@ -69,6 +125,41 @@ int main(void) {
         check([webview.URL.path isEqualToString:@"/second"] && webview.canGoBack && !webview.canGoForward,
               @"Forward must restore the second page");
         check(webview.allowsBackForwardNavigationGestures, @"Native gestures must remain enabled across page navigation");
-        puts("PASS: WebKit interactive gesture configuration, full-page back/forward and empty history");
+
+        NSWindow *window = [[NSWindow alloc] initWithContentRect:NSMakeRect(0, 0, 800, 600)
+            styleMask:NSWindowStyleMaskTitled backing:NSBackingStoreBuffered defer:NO];
+        window.releasedWhenClosed = NO;
+        window.title = @"KanbanGit navigation test";
+        window.contentView = webview;
+        [window orderFront:nil];
+        evaluate(webview, @"document.body.innerHTML = `<input id='duplicate' type='radio'><input id='draft' value='Unsaved project'><input id='upload' type='file'><a id='back' href='#back'>Back</a>`; window.visits = 0; document.querySelector('#back').onclick = event => { event.preventDefault(); if (!document.querySelector('#duplicate').checked || confirm('Discard unsaved changes?')) window.visits++; }; true;");
+        evaluate(webview, @"document.querySelector('#upload').click()");
+        waitUntil(^BOOL { return originalUI.uploaded; }, @"File selection must still reach the original UI delegate");
+        evaluate(webview, @"document.querySelector('#back').click()");
+        check([evaluate(webview, @"window.visits") intValue] == 1, @"Pristine forms must navigate without a confirmation");
+        evaluate(webview, @"document.querySelector('#duplicate').click()");
+        for (NSString *choice in @[@"Cancel", @"OK", @"Cancel", @"OK"]) {
+            __block BOOL finished = NO;
+            [webview evaluateJavaScript:@"document.querySelector('#back').click()" completionHandler:^(id result, NSError *error) {
+                check(error == nil, error.localizedDescription);
+                finished = YES;
+            }];
+            waitUntil(^BOOL { return window.attachedSheet != nil; }, @"Dirty form navigation must show a native confirmation");
+            check(!finished, @"The original click must wait for the user's decision");
+            check(containsText(window.attachedSheet.contentView, @"workspace"), @"The confirmation must identify the requesting website");
+            check(containsText(window.attachedSheet.contentView, @"Discard unsaved changes?"), @"The confirmation must show the application's message");
+            NSButton *button = findButton(window.attachedSheet.contentView, choice);
+            check(button != nil, @"The native confirmation must offer OK and Cancel");
+            [button performClick:nil];
+            waitUntil(^BOOL { return finished && window.attachedSheet == nil; }, @"Dismissal must release the original navigation");
+            check([evaluate(webview, @"document.querySelector('#draft').value") isEqualToString:@"Unsaved project"],
+                @"Cancelling a confirmation must preserve the draft");
+        }
+        check([evaluate(webview, @"window.visits") intValue] == 3, @"Only accepted visits must run, exactly once each");
+        window.contentView = nil;
+        check(![evaluate(webview, @"confirm('Detached view')") boolValue], @"A detached view must cancel and release JavaScript immediately");
+        [window orderOut:nil];
+        [window close];
+        puts("PASS: WebKit interactive gesture configuration, full-page back/forward, native confirmations and delegate forwarding");
     }
 }

native/tests/navigation-macos.test.js

@@ -8,7 +8,7 @@ import test from 'node:test';
 import { fileURLToPath } from 'node:url';
 
 test(
-    'WebKit owns interactive navigation and preserves native back/forward history',
+    'WebKit preserves history and confirms dirty form navigation without losing delegate callbacks',
     { skip: process.platform !== 'darwin' },
     () => {
         const directory = mkdtempSync(join(tmpdir(), 'kanbangit-navigation-'));
@@ -48,7 +48,7 @@ test(
             assert.equal(
                 result.status,
                 0,
-                result.stderr || result.error?.message,
+                result.stderr || result.error?.message || result.signal,
             );
             assert.match(result.stdout, /PASS: WebKit/);
         } finally {

package.json

@@ -62,7 +62,7 @@
         "tailwind-merge": "^3.2.0",
         "tailwindcss": "^4.1.1",
         "tw-animate-css": "^1.2.5",
-        "vue": "^3.5.13",
+        "vue": "^3.5.43",
         "vue-input-otp": "^0.3.2"
     },
     "optionalDependencies": {

pnpm-lock.yaml

@@ -204,12 +204,15 @@ settings:
   excludeLinksFromLockfile: false
 
 overrides:
+  '@vue/server-renderer@<3.5.42': ^3.5.42
   axios@>=1.13.0 <1.20.0: ^1.20.0
   axios@>=1.15.0 <1.20.0: ^1.20.0
   axios@>=1.15.1 <1.20.0: ^1.20.0
   axios@>=1.15.2 <1.20.0: ^1.20.0
   axios@>=1.16.1 <1.20.0: ^1.20.0
   axios@>=1.17.0 <1.20.0: ^1.20.0
+  shell-quote@>=1.8.4 <1.11.0: ^1.11.0
+  source-map-js@>=1.0.0 <1.2.2: ^1.2.2
 
 importers:
 
@@ -220,7 +223,7 @@ importers:
         version: 2.3.18(debug@4.4.3(supports-color@8.1.1))(supports-color@8.1.1)
       '@inertiajs/vue3':
         specifier: ^2.3.7
-        version: 2.3.18(debug@4.4.3(supports-color@8.1.1))(supports-color@8.1.1)(vue@3.5.30(typescript@5.9.3))
+        version: 2.3.18(debug@4.4.3(supports-color@8.1.1))(supports-color@8.1.1)(vue@3.5.43(typescript@5.9.3))
       '@tiptap/core':
         specifier: ^3.31.3
         version: 3.31.3(@tiptap/pm@3.31.3)
@@ -235,7 +238,7 @@ importers:
         version: 3.31.3
       '@tiptap/vue-3':
         specifier: ^3.31.3
-        version: 3.31.3(@floating-ui/dom@1.7.6)(@tiptap/core@3.31.3(@tiptap/pm@3.31.3))(@tiptap/pm@3.31.3)(vue@3.5.30(typescript@5.9.3))
+        version: 3.31.3(@floating-ui/dom@1.7.6)(@tiptap/core@3.31.3(@tiptap/pm@3.31.3))(@tiptap/pm@3.31.3)(vue@3.5.43(typescript@5.9.3))
       '@vueuse/core':
         specifier: ^12.8.2
         version: 12.8.2(typescript@5.9.3)
@@ -250,10 +253,10 @@ importers:
         version: 3.0.0(vite@8.2.2(@types/node@22.19.15)(jiti@2.6.1))
       lucide-vue-next:
         specifier: ^0.468.0
-        version: 0.468.0(vue@3.5.30(typescript@5.9.3))
+        version: 0.468.0(vue@3.5.43(typescript@5.9.3))
       reka-ui:
         specifier: ^2.6.1
-        version: 2.9.2(vue@3.5.30(typescript@5.9.3))
+        version: 2.9.2(vue@3.5.43(typescript@5.9.3))
       tailwind-merge:
         specifier: ^3.2.0
         version: 3.5.0
@@ -264,11 +267,11 @@ importers:
         specifier: ^1.2.5
         version: 1.4.0
       vue:
-        specifier: ^3.5.13
+        specifier: ^3.5.43
-        version: 3.5.30(typescript@5.9.3)
+        version: 3.5.43(typescript@5.9.3)
       vue-input-otp:
         specifier: ^0.3.2
-        version: 0.3.2(typescript@5.9.3)(vue@3.5.30(typescript@5.9.3))
+        version: 0.3.2(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
     devDependencies:
       '@eslint/js':
         specifier: ^9.39.4
@@ -293,7 +296,7 @@ importers:
         version: 8.58.1(eslint@9.39.4(jiti@2.6.1)(supports-color@8.1.1))(supports-color@8.1.1)(typescript@5.9.3)
       '@vitejs/plugin-vue':
         specifier: ^6.0.0
-        version: 6.0.5(vite@8.2.2(@types/node@22.19.15)(jiti@2.6.1))(vue@3.5.30(typescript@5.9.3))
+        version: 6.0.5(vite@8.2.2(@types/node@22.19.15)(jiti@2.6.1))(vue@3.5.43(typescript@5.9.3))
       '@vue/eslint-config-typescript':
         specifier: ^14.3.0
         version: 14.7.0(eslint-plugin-vue@9.33.0(eslint@9.39.4(jiti@2.6.1)(supports-color@8.1.1))(supports-color@8.1.1))(eslint@9.39.4(jiti@2.6.1)(supports-color@8.1.1))(supports-color@8.1.1)(typescript@5.9.3)
@@ -370,21 +373,21 @@ importers:
 
 packages:
 
-  '@babel/helper-string-parser@7.27.1':
+  '@babel/helper-string-parser@7.29.7':
-    resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==}
+    resolution: {integrity: sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/helper-validator-identifier@7.28.5':
+  '@babel/helper-validator-identifier@7.29.7':
-    resolution: {integrity: sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==}
+    resolution: {integrity: sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/parser@7.29.2':
+  '@babel/parser@7.29.9':
-    resolution: {integrity: sha512-4GgRzy/+fsBa72/RZVJmGKPmZu9Byn8o4MoLpmNe1m8ZfYnz5emHLQz3U4gLud6Zwl0RZIcgiLD7Uq7ySFuDLA==}
+    resolution: {integrity: sha512-CjXrNHTnvqBVqHgdBysY3vk2T8tpJHb5/RMeHJBTyVa9xgugCB0CJTx/3oO8RV2QRQP391RWpB7D6hLjm8V9uA==}
     engines: {node: '>=6.0.0'}
     hasBin: true
 
-  '@babel/types@7.29.0':
+  '@babel/types@7.29.8':
-    resolution: {integrity: sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==}
+    resolution: {integrity: sha512-Vj1jF3cPfxg7OAfoI7QnVKLoILlm2JF9pnVHrX8qx7AHMiYWT+NDAA7jChlNgRS4WTLc/fD1lXLmPixluj+3Gg==}
     engines: {node: '>=6.9.0'}
 
   '@emnapi/core@1.9.1':
@@ -1109,17 +1112,17 @@ packages:
       typescript:
         optional: true
 
-  '@vue/compiler-core@3.5.30':
+  '@vue/compiler-core@3.5.43':
-    resolution: {integrity: sha512-s3DfdZkcu/qExZ+td75015ljzHc6vE+30cFMGRPROYjqkroYI5NV2X1yAMX9UeyBNWB9MxCfPcsjpLS11nzkkw==}
+    resolution: {integrity: sha512-zdiLhnbe1QQqgDT8xZMpNmyqZ3qlI+/Q/FHQco57Kwl/b05HhCzN6eVGN9QU9rbga4CrS0H5SYY8VGHZCt/1Hg==}
 
-  '@vue/compiler-dom@3.5.30':
+  '@vue/compiler-dom@3.5.43':
-    resolution: {integrity: sha512-eCFYESUEVYHhiMuK4SQTldO3RYxyMR/UQL4KdGD1Yrkfdx4m/HYuZ9jSfPdA+nWJY34VWndiYdW/wZXyiPEB9g==}
+    resolution: {integrity: sha512-PEZoAk3NQmsn/ejMzSOCyTYqwGqczrWm70PuhBKjjv1+TCoQAaO/zOqNwjV+honlNstT5ILxtc+8r8UUfj+iEQ==}
 
-  '@vue/compiler-sfc@3.5.30':
+  '@vue/compiler-sfc@3.5.43':
-    resolution: {integrity: sha512-LqmFPDn89dtU9vI3wHJnwaV6GfTRD87AjWpTWpyrdVOObVtjIuSeZr181z5C4PmVx/V3j2p+0f7edFKGRMpQ5A==}
+    resolution: {integrity: sha512-FCbrG3XNCRl+js3huuKx4IVHBLTvMkJhVepjbxSPu1gn4yWLaYtGNQdjJGZaMytXB6qb76qQDDmDSLy/vkmleQ==}
 
-  '@vue/compiler-ssr@3.5.30':
+  '@vue/compiler-ssr@3.5.43':
-    resolution: {integrity: sha512-NsYK6OMTnx109PSL2IAyf62JP6EUdk4Dmj6AkWcJGBvN0dQoMYtVekAmdqgTtWQgEJo+Okstbf/1p7qZr5H+bA==}
+    resolution: {integrity: sha512-GF62orf7KiJX9RqrHNGrYBudsQGD0OhJ5nDs90O8UiDuS40+YMYomiXu6w6EuvtXuRDc3MSNis3EaaSKAVSWpg==}
 
   '@vue/compiler-vue2@2.7.16':
     resolution: {integrity: sha512-qYC3Psj9S/mfu9uVi5WvNZIzq+xnXMhOwbTFKKDD7b1lhpnn71jXSFdTQ+WsIEk0ONCd7VV2IMm7ONl6tbQ86A==}
@@ -1143,22 +1146,20 @@ packages:
       typescript:
         optional: true
 
-  '@vue/reactivity@3.5.30':
+  '@vue/reactivity@3.5.43':
-    resolution: {integrity: sha512-179YNgKATuwj9gB+66snskRDOitDiuOZqkYia7mHKJaidOMo/WJxHKF8DuGc4V4XbYTJANlfEKb0yxTQotnx4Q==}
+    resolution: {integrity: sha512-G/c9GyOZNI2jVaaS6OX1EF1SSFSv7H0ERqNTl4+DTFMlZmB5eVAB53aLQNam/7NL2NPtaDD7RdVrzf8uJzMuOA==}
 
-  '@vue/runtime-core@3.5.30':
+  '@vue/runtime-core@3.5.43':
-    resolution: {integrity: sha512-e0Z+8PQsUTdwV8TtEsLzUM7SzC7lQwYKePydb7K2ZnmS6jjND+WJXkmmfh/swYzRyfP1EY3fpdesyYoymCzYfg==}
+    resolution: {integrity: sha512-hU6U6VnVhBGQDpvlnnDlIB8ZGJBiOcgk2lh/0InltHiz3D8oSkluvuvY+do1G2H3+udeKFsmaBlgVYP7gXQzEw==}
 
-  '@vue/runtime-dom@3.5.30':
+  '@vue/runtime-dom@3.5.43':
-    resolution: {integrity: sha512-2UIGakjU4WSQ0T4iwDEW0W7vQj6n7AFn7taqZ9Cvm0Q/RA2FFOziLESrDL4GmtI1wV3jXg5nMoJSYO66egDUBw==}
+    resolution: {integrity: sha512-Bb2Jc0YjjJdMt1SJmb9b2L/IWd3I8lIT9x9eS/xvvP9CiVgna0ffua74xKRmt4/uSJ+0r4iN8ex1jrqkhQGWQw==}
 
-  '@vue/server-renderer@3.5.30':
+  '@vue/server-renderer@3.5.43':
-    resolution: {integrity: sha512-v+R34icapydRwbZRD0sXwtHqrQJv38JuMB4JxbOxd8NEpGLny7cncMp53W9UH/zo4j8eDHjQ1dEJXwzFQknjtQ==}
+    resolution: {integrity: sha512-l2Ygjv9NehV94PSBxNWsAHC0j/eIIKbn92mBuWXAPGLnn6HfJ6MH5ubsd+Nk0YoZ5FRuxWI1P2VSoh+dbPQhCQ==}
-    peerDependencies:
-      vue: 3.5.30
 
-  '@vue/shared@3.5.30':
+  '@vue/shared@3.5.43':
-    resolution: {integrity: sha512-YXgQ7JjaO18NeK2K9VTbDHaFy62WrObMa6XERNfNOkAhD1F1oDSf3ZJ7K6GqabZ0BvSDHajp8qfS5Sa2I9n8uQ==}
+    resolution: {integrity: sha512-uksS7YGMR5NZyr4JNq0Rp+QyLns0ueaz20KwzIPW9R0LH1Vnt4E+XUM29PNseEbf1www2gOuhuDi5AKOIXag9Q==}
 
   '@vueuse/core@12.8.2':
     resolution: {integrity: sha512-HbvCmZdzAu3VGi/pWYm5Ut+Kd9mn1ZHnn4L5G8kOQTPs/IwIAmJoBrmYk2ckLArgMXZj0AW3n5CAejLUO+PhdQ==}
@@ -2166,6 +2167,11 @@ packages:
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
     hasBin: true
 
+  nanoid@3.3.20:
+    resolution: {integrity: sha512-uKdg2G3GNCKQn9byYOpxbGqrT2fGO5KRt5J/8b3pok8rT6qxGWF6hxMyJiEYtAf+FVyYuD9hRaDqX5uPFYJ4ZQ==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
   napi-postinstall@0.3.4:
     resolution: {integrity: sha512-PHI5f1O0EP5xJ9gQmFGMS6IZcrVvTjpXjz7Na41gTE7eE2hK11lg04CECCYEEjdc17EV4DO+fkGEtt7TpTaTiQ==}
     engines: {node: ^12.20.0 || ^14.18.0 || >=16.0.0}
@@ -2264,6 +2270,10 @@ packages:
     resolution: {integrity: sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==}
     engines: {node: ^10 || ^12 || >=14}
 
+  postcss@8.5.29:
+    resolution: {integrity: sha512-49cGhUbXj8Qenv0iTMxA1cFBzxXoctpC9Ujd77t1WcbJIr6nF/eI7g/8MgxrYldFRuAXvja7xQRwavoW7kgrxQ==}
+    engines: {node: ^10 || ^12 || >=14}
+
   prelude-ls@1.2.1:
     resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==}
     engines: {node: '>= 0.8.0'}
@@ -2480,8 +2490,8 @@ packages:
     resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
     engines: {node: '>=8'}
 
-  shell-quote@1.9.0:
+  shell-quote@1.12.0:
-    resolution: {integrity: sha512-Iov+JwFv/2HcTpcwNMKd8+IWNb8tboQJNQTkAY/LLVK7gGH9jy+LGkVqPxfekHl+yMmiqXszdGWXgkfml7hjqA==}
+    resolution: {integrity: sha512-PcByqNyT/38F2kDNi006HAMRJaULuBzq/FOsw3qdZvX/GA9W/jamDaRskgHjubHiftXK5sIFxLNkvrXUwcof6Q==}
     engines: {node: '>= 0.4'}
 
   side-channel-list@1.0.1:
@@ -2500,8 +2510,8 @@ packages:
     resolution: {integrity: sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==}
     engines: {node: '>= 0.4'}
 
-  source-map-js@1.2.1:
+  source-map-js@1.2.2:
-    resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
+    resolution: {integrity: sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==}
     engines: {node: '>=0.10.0'}
 
   stable-hash-x@0.2.0:
@@ -2728,8 +2738,8 @@ packages:
     peerDependencies:
       typescript: '>=5.0.0'
 
-  vue@3.5.30:
+  vue@3.5.43:
-    resolution: {integrity: sha512-hTHLc6VNZyzzEH/l7PFGjpcTvUgiaPK5mdLkbjrTeWSRcEfxFrv56g/XckIYlE9ckuobsdwqd5mk2g1sBkMewg==}
+    resolution: {integrity: sha512-o5qZoksdnjIKvW1srZ3ab7pcDNYAerBjRe54D0LBLfRdCYFrSgBHVXokMas35czQc0//lmx4/tuY4ZNQ+Rf2Ng==}
     peerDependencies:
       typescript: '*'
     peerDependenciesMeta:
@@ -2790,18 +2800,18 @@ packages:
 
 snapshots:
 
-  '@babel/helper-string-parser@7.27.1': {}
+  '@babel/helper-string-parser@7.29.7': {}
 
-  '@babel/helper-validator-identifier@7.28.5': {}
+  '@babel/helper-validator-identifier@7.29.7': {}
 
-  '@babel/parser@7.29.2':
+  '@babel/parser@7.29.9':
     dependencies:
-      '@babel/types': 7.29.0
+      '@babel/types': 7.29.8
 
-  '@babel/types@7.29.0':
+  '@babel/types@7.29.8':
     dependencies:
-      '@babel/helper-string-parser': 7.27.1
+      '@babel/helper-string-parser': 7.29.7
-      '@babel/helper-validator-identifier': 7.28.5
+      '@babel/helper-validator-identifier': 7.29.7
 
   '@emnapi/core@1.9.1':
     dependencies:
@@ -2876,11 +2886,11 @@ snapshots:
 
   '@floating-ui/utils@0.2.11': {}
 
-  '@floating-ui/vue@1.1.11(vue@3.5.30(typescript@5.9.3))':
+  '@floating-ui/vue@1.1.11(vue@3.5.43(typescript@5.9.3))':
     dependencies:
       '@floating-ui/dom': 1.7.6
       '@floating-ui/utils': 0.2.11
-      vue-demi: 0.14.10(vue@3.5.30(typescript@5.9.3))
+      vue-demi: 0.14.10(vue@3.5.43(typescript@5.9.3))
     transitivePeerDependencies:
       - '@vue/composition-api'
       - vue
@@ -2912,13 +2922,13 @@ snapshots:
       - debug
       - supports-color
 
-  '@inertiajs/vue3@2.3.18(debug@4.4.3(supports-color@8.1.1))(supports-color@8.1.1)(vue@3.5.30(typescript@5.9.3))':
+  '@inertiajs/vue3@2.3.18(debug@4.4.3(supports-color@8.1.1))(supports-color@8.1.1)(vue@3.5.43(typescript@5.9.3))':
     dependencies:
       '@inertiajs/core': 2.3.18(debug@4.4.3(supports-color@8.1.1))(supports-color@8.1.1)
       '@types/lodash-es': 4.17.12
       laravel-precognition: 1.0.2(debug@4.4.3(supports-color@8.1.1))(supports-color@8.1.1)
       lodash-es: 4.18.1
-      vue: 3.5.30(typescript@5.9.3)
+      vue: 3.5.43(typescript@5.9.3)
     transitivePeerDependencies:
       - debug
       - supports-color
@@ -3053,7 +3063,7 @@ snapshots:
       jiti: 2.6.1
       lightningcss: 1.32.0
       magic-string: 0.30.21
-      source-map-js: 1.2.1
+      source-map-js: 1.2.2
       tailwindcss: 4.2.2
 
   '@tailwindcss/oxide-android-arm64@4.2.2':
@@ -3116,10 +3126,10 @@ snapshots:
 
   '@tanstack/virtual-core@3.13.23': {}
 
-  '@tanstack/vue-virtual@3.13.23(vue@3.5.30(typescript@5.9.3))':
+  '@tanstack/vue-virtual@3.13.23(vue@3.5.43(typescript@5.9.3))':
     dependencies:
       '@tanstack/virtual-core': 3.13.23
-      vue: 3.5.30(typescript@5.9.3)
+      vue: 3.5.43(typescript@5.9.3)
 
   '@tiptap/core@3.31.3(@tiptap/pm@3.31.3)':
     dependencies:
@@ -3283,12 +3293,12 @@ snapshots:
       '@tiptap/extensions': 3.31.3(@tiptap/core@3.31.3(@tiptap/pm@3.31.3))(@tiptap/pm@3.31.3)
       '@tiptap/pm': 3.31.3
 
-  '@tiptap/vue-3@3.31.3(@floating-ui/dom@1.7.6)(@tiptap/core@3.31.3(@tiptap/pm@3.31.3))(@tiptap/pm@3.31.3)(vue@3.5.30(typescript@5.9.3))':
+  '@tiptap/vue-3@3.31.3(@floating-ui/dom@1.7.6)(@tiptap/core@3.31.3(@tiptap/pm@3.31.3))(@tiptap/pm@3.31.3)(vue@3.5.43(typescript@5.9.3))':
     dependencies:
       '@floating-ui/dom': 1.7.6
       '@tiptap/core': 3.31.3(@tiptap/pm@3.31.3)
       '@tiptap/pm': 3.31.3
-      vue: 3.5.30(typescript@5.9.3)
+      vue: 3.5.43(typescript@5.9.3)
     optionalDependencies:
       '@tiptap/extension-bubble-menu': 3.31.3(@tiptap/core@3.31.3(@tiptap/pm@3.31.3))(@tiptap/pm@3.31.3)
       '@tiptap/extension-floating-menu': 3.31.3(@floating-ui/dom@1.7.6)(@tiptap/core@3.31.3(@tiptap/pm@3.31.3))(@tiptap/pm@3.31.3)
@@ -3466,11 +3476,11 @@ snapshots:
   '@unrs/resolver-binding-win32-x64-msvc@1.11.1':
     optional: true
 
-  '@vitejs/plugin-vue@6.0.5(vite@8.2.2(@types/node@22.19.15)(jiti@2.6.1))(vue@3.5.30(typescript@5.9.3))':
+  '@vitejs/plugin-vue@6.0.5(vite@8.2.2(@types/node@22.19.15)(jiti@2.6.1))(vue@3.5.43(typescript@5.9.3))':
     dependencies:
       '@rolldown/pluginutils': 1.0.0-rc.2
       vite: 8.2.2(@types/node@22.19.15)(jiti@2.6.1)
-      vue: 3.5.30(typescript@5.9.3)
+      vue: 3.5.43(typescript@5.9.3)
 
   '@volar/language-core@2.4.15':
     dependencies:
@@ -3486,35 +3496,35 @@ snapshots:
     optionalDependencies:
       typescript: 5.9.3
 
-  '@vue/compiler-core@3.5.30':
+  '@vue/compiler-core@3.5.43':
     dependencies:
-      '@babel/parser': 7.29.2
+      '@babel/parser': 7.29.9
-      '@vue/shared': 3.5.30
+      '@vue/shared': 3.5.43
       entities: 7.0.1
       estree-walker: 2.0.2
-      source-map-js: 1.2.1
+      source-map-js: 1.2.2
 
-  '@vue/compiler-dom@3.5.30':
+  '@vue/compiler-dom@3.5.43':
     dependencies:
-      '@vue/compiler-core': 3.5.30
+      '@vue/compiler-core': 3.5.43
-      '@vue/shared': 3.5.30
+      '@vue/shared': 3.5.43
 
-  '@vue/compiler-sfc@3.5.30':
+  '@vue/compiler-sfc@3.5.43':
     dependencies:
-      '@babel/parser': 7.29.2
+      '@babel/parser': 7.29.9
-      '@vue/compiler-core': 3.5.30
+      '@vue/compiler-core': 3.5.43
-      '@vue/compiler-dom': 3.5.30
+      '@vue/compiler-dom': 3.5.43
-      '@vue/compiler-ssr': 3.5.30
+      '@vue/compiler-ssr': 3.5.43
-      '@vue/shared': 3.5.30
+      '@vue/shared': 3.5.43
       estree-walker: 2.0.2
       magic-string: 0.30.21
-      postcss: 8.5.26
+      postcss: 8.5.29
-      source-map-js: 1.2.1
+      source-map-js: 1.2.2
 
-  '@vue/compiler-ssr@3.5.30':
+  '@vue/compiler-ssr@3.5.43':
     dependencies:
-      '@vue/compiler-dom': 3.5.30
+      '@vue/compiler-dom': 3.5.43
-      '@vue/shared': 3.5.30
+      '@vue/shared': 3.5.43
 
   '@vue/compiler-vue2@2.7.16':
     dependencies:
@@ -3537,9 +3547,9 @@ snapshots:
   '@vue/language-core@2.2.12(typescript@5.9.3)':
     dependencies:
       '@volar/language-core': 2.4.15
-      '@vue/compiler-dom': 3.5.30
+      '@vue/compiler-dom': 3.5.43
       '@vue/compiler-vue2': 2.7.16
-      '@vue/shared': 3.5.30
+      '@vue/shared': 3.5.43
       alien-signals: 1.0.13
       minimatch: 9.0.9
       muggle-string: 0.4.1
@@ -3547,45 +3557,45 @@ snapshots:
     optionalDependencies:
       typescript: 5.9.3
 
-  '@vue/reactivity@3.5.30':
+  '@vue/reactivity@3.5.43':
     dependencies:
-      '@vue/shared': 3.5.30
+      '@vue/shared': 3.5.43
 
-  '@vue/runtime-core@3.5.30':
+  '@vue/runtime-core@3.5.43':
     dependencies:
-      '@vue/reactivity': 3.5.30
+      '@vue/reactivity': 3.5.43
-      '@vue/shared': 3.5.30
+      '@vue/shared': 3.5.43
 
-  '@vue/runtime-dom@3.5.30':
+  '@vue/runtime-dom@3.5.43':
     dependencies:
-      '@vue/reactivity': 3.5.30
+      '@vue/reactivity': 3.5.43
-      '@vue/runtime-core': 3.5.30
+      '@vue/runtime-core': 3.5.43
-      '@vue/shared': 3.5.30
+      '@vue/shared': 3.5.43
       csstype: 3.2.3
 
-  '@vue/server-renderer@3.5.30(vue@3.5.30(typescript@5.9.3))':
+  '@vue/server-renderer@3.5.43':
     dependencies:
-      '@vue/compiler-ssr': 3.5.30
+      '@vue/compiler-ssr': 3.5.43
-      '@vue/shared': 3.5.30
+      '@vue/runtime-dom': 3.5.43
-      vue: 3.5.30(typescript@5.9.3)
+      '@vue/shared': 3.5.43
 
-  '@vue/shared@3.5.30': {}
+  '@vue/shared@3.5.43': {}
 
   '@vueuse/core@12.8.2(typescript@5.9.3)':
     dependencies:
       '@types/web-bluetooth': 0.0.21
       '@vueuse/metadata': 12.8.2
       '@vueuse/shared': 12.8.2(typescript@5.9.3)
-      vue: 3.5.30(typescript@5.9.3)
+      vue: 3.5.43(typescript@5.9.3)
     transitivePeerDependencies:
       - typescript
 
-  '@vueuse/core@14.2.1(vue@3.5.30(typescript@5.9.3))':
+  '@vueuse/core@14.2.1(vue@3.5.43(typescript@5.9.3))':
     dependencies:
       '@types/web-bluetooth': 0.0.21
       '@vueuse/metadata': 14.2.1
-      '@vueuse/shared': 14.2.1(vue@3.5.30(typescript@5.9.3))
+      '@vueuse/shared': 14.2.1(vue@3.5.43(typescript@5.9.3))
-      vue: 3.5.30(typescript@5.9.3)
+      vue: 3.5.43(typescript@5.9.3)
 
   '@vueuse/metadata@12.8.2': {}
 
@@ -3593,13 +3603,13 @@ snapshots:
 
   '@vueuse/shared@12.8.2(typescript@5.9.3)':
     dependencies:
-      vue: 3.5.30(typescript@5.9.3)
+      vue: 3.5.43(typescript@5.9.3)
     transitivePeerDependencies:
       - typescript
 
-  '@vueuse/shared@14.2.1(vue@3.5.30(typescript@5.9.3))':
+  '@vueuse/shared@14.2.1(vue@3.5.43(typescript@5.9.3))':
     dependencies:
-      vue: 3.5.30(typescript@5.9.3)
+      vue: 3.5.43(typescript@5.9.3)
 
   acorn-jsx@5.3.2(acorn@8.16.0):
     dependencies:
@@ -3777,7 +3787,7 @@ snapshots:
     dependencies:
       chalk: 4.1.2
       rxjs: 7.8.2
-      shell-quote: 1.9.0
+      shell-quote: 1.12.0
       supports-color: 8.1.1
       tree-kill: 1.2.2
       yargs: 17.7.2
@@ -4588,9 +4598,9 @@ snapshots:
 
   lodash@4.18.1: {}
 
-  lucide-vue-next@0.468.0(vue@3.5.30(typescript@5.9.3)):
+  lucide-vue-next@0.468.0(vue@3.5.43(typescript@5.9.3)):
     dependencies:
-      vue: 3.5.30(typescript@5.9.3)
+      vue: 3.5.43(typescript@5.9.3)
 
   magic-string@0.30.21:
     dependencies:
@@ -4633,6 +4643,8 @@ snapshots:
 
   nanoid@3.3.18: {}
 
+  nanoid@3.3.20: {}
+
   napi-postinstall@0.3.4: {}
 
   natural-compare@1.4.0: {}
@@ -4730,7 +4742,13 @@ snapshots:
     dependencies:
       nanoid: 3.3.18
       picocolors: 1.1.1
-      source-map-js: 1.2.1
+      source-map-js: 1.2.2
+
+  postcss@8.5.29:
+    dependencies:
+      nanoid: 3.3.20
+      picocolors: 1.1.1
+      source-map-js: 1.2.2
 
   prelude-ls@1.2.1: {}
 
@@ -4849,19 +4867,19 @@ snapshots:
       gopd: 1.2.0
       set-function-name: 2.0.2
 
-  reka-ui@2.9.2(vue@3.5.30(typescript@5.9.3)):
+  reka-ui@2.9.2(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       '@floating-ui/dom': 1.7.6
-      '@floating-ui/vue': 1.1.11(vue@3.5.30(typescript@5.9.3))
+      '@floating-ui/vue': 1.1.11(vue@3.5.43(typescript@5.9.3))
       '@internationalized/date': 3.12.0
       '@internationalized/number': 3.6.5
-      '@tanstack/vue-virtual': 3.13.23(vue@3.5.30(typescript@5.9.3))
+      '@tanstack/vue-virtual': 3.13.23(vue@3.5.43(typescript@5.9.3))
-      '@vueuse/core': 14.2.1(vue@3.5.30(typescript@5.9.3))
+      '@vueuse/core': 14.2.1(vue@3.5.43(typescript@5.9.3))
-      '@vueuse/shared': 14.2.1(vue@3.5.30(typescript@5.9.3))
+      '@vueuse/shared': 14.2.1(vue@3.5.43(typescript@5.9.3))
       aria-hidden: 1.2.6
       defu: 6.1.7
       ohash: 2.0.11
-      vue: 3.5.30(typescript@5.9.3)
+      vue: 3.5.43(typescript@5.9.3)
     transitivePeerDependencies:
       - '@vue/composition-api'
 
@@ -4961,7 +4979,7 @@ snapshots:
 
   shebang-regex@3.0.0: {}
 
-  shell-quote@1.9.0: {}
+  shell-quote@1.12.0: {}
 
   side-channel-list@1.0.1:
     dependencies:
@@ -4991,7 +5009,7 @@ snapshots:
       side-channel-map: 1.0.1
       side-channel-weakmap: 1.0.2
 
-  source-map-js@1.2.1: {}
+  source-map-js@1.2.2: {}
 
   stable-hash-x@0.2.0: {}
 
@@ -5193,9 +5211,9 @@ snapshots:
 
   vscode-uri@3.1.0: {}
 
-  vue-demi@0.14.10(vue@3.5.30(typescript@5.9.3)):
+  vue-demi@0.14.10(vue@3.5.43(typescript@5.9.3)):
     dependencies:
-      vue: 3.5.30(typescript@5.9.3)
+      vue: 3.5.43(typescript@5.9.3)
 
   vue-eslint-parser@10.4.0(eslint@9.39.4(jiti@2.6.1)(supports-color@8.1.1))(supports-color@8.1.1):
     dependencies:
@@ -5222,11 +5240,11 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  vue-input-otp@0.3.2(typescript@5.9.3)(vue@3.5.30(typescript@5.9.3)):
+  vue-input-otp@0.3.2(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       '@vueuse/core': 12.8.2(typescript@5.9.3)
-      reka-ui: 2.9.2(vue@3.5.30(typescript@5.9.3))
+      reka-ui: 2.9.2(vue@3.5.43(typescript@5.9.3))
-      vue: 3.5.30(typescript@5.9.3)
+      vue: 3.5.43(typescript@5.9.3)
     transitivePeerDependencies:
       - '@vue/composition-api'
       - typescript
@@ -5237,13 +5255,13 @@ snapshots:
       '@vue/language-core': 2.2.12(typescript@5.9.3)
       typescript: 5.9.3
 
-  vue@3.5.30(typescript@5.9.3):
+  vue@3.5.43(typescript@5.9.3):
     dependencies:
-      '@vue/compiler-dom': 3.5.30
+      '@vue/compiler-dom': 3.5.43
-      '@vue/compiler-sfc': 3.5.30
+      '@vue/compiler-sfc': 3.5.43
-      '@vue/runtime-dom': 3.5.30
+      '@vue/runtime-dom': 3.5.43
-      '@vue/server-renderer': 3.5.30(vue@3.5.30(typescript@5.9.3))
+      '@vue/server-renderer': 3.5.43
-      '@vue/shared': 3.5.30
+      '@vue/shared': 3.5.43
     optionalDependencies:
       typescript: 5.9.3
 

pnpm-workspace.yaml

@@ -8,9 +8,15 @@ allowBuilds:
   unrs-resolver: true
   vue-demi: true
 overrides:
+  '@vue/server-renderer@<3.5.42': ^3.5.42
   axios@>=1.13.0 <1.20.0: ^1.20.0
   axios@>=1.15.0 <1.20.0: ^1.20.0
   axios@>=1.15.1 <1.20.0: ^1.20.0
   axios@>=1.15.2 <1.20.0: ^1.20.0
   axios@>=1.16.1 <1.20.0: ^1.20.0
   axios@>=1.17.0 <1.20.0: ^1.20.0
+  shell-quote@>=1.8.4 <1.11.0: ^1.11.0
+  source-map-js@>=1.0.0 <1.2.2: ^1.2.2
+audit:
+  ignore:
+    - GHSA-vfj7-8cjw-p6xm

resources/js/lib/ticket-description-format.json

@@ -0,0 +1,17 @@
+{
+    "format": "Markdown stored verbatim and supported by the Tiptap WYSIWYG editor and ticket detail view.",
+    "supported": "Supported: plain text, paragraphs, line breaks, headings, bold, italic, strikethrough, ordinary ordered/unordered lists (including nested lists), blockquotes, inline/fenced/indented code, horizontal rules, and safe links.",
+    "unsupported": "Not visually supported: task checkboxes, tables, HTML, images, or unsafe links. Newly supplied incompatible descriptions reject the entire mutation with a description field error; existing descriptions are preserved when description is omitted.",
+    "criteria": "Put acceptance criteria exclusively in the structured acceptance_criteria field. Do not repeat them in description as task checkboxes or a copied criteria list. No criteria are automatically extracted or moved.",
+    "links": "Safe link destinations: http://, https://, mailto:, a root-relative path starting with a single /, or a #fragment. Protocol-relative URLs, other schemes, whitespace, control characters, and backslashes (including percent-encoded forms) are not allowed.",
+    "example": "## Goal\n\nExplain the **context** and approach.\n\n- Implement the change\n- Verify [the guide](https://example.com/guide)\n\n> Keep the scope clear.\n\nUse `code` when needed.",
+    "unsupported_tokens": {
+        "html": "HTML",
+        "table": "tables",
+        "image": "images",
+        "task": "task checkboxes",
+        "unsafe_link": "unsafe links"
+    },
+    "link_prefix": "^(?:https?://|mailto:|/(?!/)|#)",
+    "unsafe_link_characters": "[\\s\\\\\\x00-\\x1f\\x7f]"
+}

resources/js/lib/ticket-description.ts

@@ -2,30 +2,40 @@ import type { JSONContent } from '@tiptap/core';
 import { Markdown, MarkdownManager } from '@tiptap/markdown';
 import StarterKit from '@tiptap/starter-kit';
 import { h } from 'vue';
+import descriptionFormat from './ticket-description-format.json';
 import type { VNodeChild } from 'vue';
 
 export function safeDescriptionLink(value: unknown): string | null {
     if (
         typeof value !== 'string' ||
-        /[\s\\]/u.test(value) ||
+        new RegExp(descriptionFormat.unsafe_link_characters, 'u').test(value)
-        [...value].some(
-            (character) =>
-                character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127,
-        )
     ) {
         return null;
     }
+    try {
+        if (
+            new RegExp(descriptionFormat.unsafe_link_characters, 'u').test(
+                decodeURIComponent(value),
+            )
+        ) {
+            return null;
+        }
+    } catch {
+        return null;
+    }
     if (/^(https?:\/\/|mailto:)/i.test(value)) {
         try {
-            const url = new URL(value);
+            new URL(value);
-            return ['http:', 'https:', 'mailto:'].includes(url.protocol)
+            return new RegExp(descriptionFormat.link_prefix, 'i').test(value)
                 ? value
                 : null;
         } catch {
             return null;
         }
     }
-    return /^(\/(?!\/)|#)/.test(value) ? value : null;
+    return new RegExp(descriptionFormat.link_prefix, 'i').test(value)
+        ? value
+        : null;
 }
 
 export function descriptionExtensions() {
@@ -55,15 +65,21 @@ const markdown = new MarkdownManager({
 /** Unsupported Markdown stays editable verbatim instead of being silently discarded. */
 export function supportsVisualDescription(value: string): boolean {
     let supported = true;
-    markdown.instance.walkTokens(markdown.instance.lexer(value), (token) => {
+    markdown.instance.walkTokens(
-        if (
+        markdown.instance.lexer(value, { gfm: true, breaks: true }),
-            ['html', 'table', 'image'].includes(token.type) ||
+        (token) => {
-            (token.type === 'list_item' && token.task) ||
+            if (
-            (token.type === 'link' && !safeDescriptionLink(token.href))
+                Object.hasOwn(
-        ) {
+                    descriptionFormat.unsupported_tokens,
-            supported = false;
+                    token.type,
-        }
+                ) ||
-    });
+                (token.type === 'list_item' && token.task) ||
+                (token.type === 'link' && !safeDescriptionLink(token.href))
+            ) {
+                supported = false;
+            }
+        },
+    );
     return supported;
 }
 

tests/Feature/Mcp/TicketDescriptionContractTest.php

@@ -0,0 +1,178 @@
+<?php
+
+namespace Tests\Feature\Mcp;
+
+use App\Actions\ProjectTicketMetadata\InitializeProjectTicketMetadata;
+use App\Actions\Tickets\Support\TicketDescriptionFormat;
+use App\Mcp\Servers\KanbanGitServer;
+use App\Mcp\Tools\CreateTicket;
+use App\Mcp\Tools\GetTicket;
+use App\Mcp\Tools\UpdateTicket;
+use App\Mcp\Tools\UpdateTicketDescription;
+use App\Models\Project;
+use App\Models\Ticket;
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Testing\Fluent\AssertableJson;
+use Inertia\Testing\AssertableInertia as Assert;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Symfony\Component\Process\Process;
+use Tests\TestCase;
+
+class TicketDescriptionContractTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private Project $project;
+
+    private User $user;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->user = User::factory()->create();
+        $this->project = Project::factory()->create(['key' => 'CORE']);
+        app(InitializeProjectTicketMetadata::class)->handle($this->project);
+        $this->syncProjectPermissions($this->project, $this->user, ['view', 'write']);
+    }
+
+    public function test_discovery_exposes_the_shared_contract_for_every_writing_tool_and_field_for_any_key_owner(): void
+    {
+        foreach ([$this->user, User::factory()->create()] as $user) {
+            $this->syncProjectPermissions($this->project, $user, ['view', 'write']);
+            $this->withApplicationKey($user);
+            $this->postJson('/mcp/kanbangit', [
+                'jsonrpc' => '2.0', 'id' => 1, 'method' => 'initialize',
+                'params' => ['protocolVersion' => '2025-06-18', 'capabilities' => [], 'clientInfo' => ['name' => 'Contract test', 'version' => '1.0']],
+            ])->assertOk()->assertJsonPath('result.instructions', fn (string $value): bool => str_contains($value, TicketDescriptionFormat::instructions()));
+            $response = $this->postJson('/mcp/kanbangit', [
+                'jsonrpc' => '2.0', 'id' => 2, 'method' => 'tools/list', 'params' => [],
+            ])->assertOk();
+            $writers = [];
+            foreach ($response->json('result.tools') as $tool) {
+                $fields = $tool['inputSchema']['properties'];
+                if (! ($tool['annotations']['readOnlyHint'] ?? false)) {
+                    $writers[] = $tool['name'];
+                    $this->assertStringContainsString(TicketDescriptionFormat::instructions(), $tool['description'], $tool['name']);
+                }
+                if (isset($fields['description'])) {
+                    $this->assertStringContainsString(TicketDescriptionFormat::instructions(), $fields['description']['description'], $tool['name']);
+                }
+                if (isset($fields['acceptance_criteria'])) {
+                    $this->assertStringContainsString(TicketDescriptionFormat::criteriaInstructions(), $fields['acceptance_criteria']['description'], $tool['name']);
+                }
+            }
+            $this->assertContains('create_ticket', $writers);
+            $this->assertContains('update_ticket', $writers);
+            $this->assertContains('update_ticket_description', $writers);
+        }
+    }
+
+    #[DataProvider('descriptionCases')]
+    public function test_backend_and_editor_share_compatibility_cases(string $value, bool $supported): void
+    {
+        $this->assertSame($supported, TicketDescriptionFormat::unsupportedContent($value) === []);
+    }
+
+    public static function descriptionCases(): array
+    {
+        $cases = json_decode(file_get_contents(__DIR__.'/../../Fixtures/ticket-description-cases.json'), true, flags: JSON_THROW_ON_ERROR);
+
+        return collect($cases)->mapWithKeys(fn (array $case): array => [$case['name'] => [$case['value'], $case['supported']]])->all();
+    }
+
+    #[DataProvider('unsupportedDescriptions')]
+    public function test_incompatible_description_rejects_creation_and_every_update_without_partial_changes(string $description): void
+    {
+        $projectBefore = $this->project->fresh()->getAttributes();
+        KanbanGitServer::actingAs($this->user)->tool(CreateTicket::class, $this->createPayload($description))
+            ->assertHasErrors(['description', 'unsupported', 'acceptance_criteria']);
+        $this->assertDatabaseCount('tickets', 0);
+        $this->assertDatabaseCount('ticket_worklog_entries', 0);
+        $this->assertSame($projectBefore, $this->project->fresh()->getAttributes());
+
+        $ticket = $this->ticket();
+        $before = $ticket->fresh()->getAttributes();
+        foreach ([UpdateTicketDescription::class, UpdateTicket::class] as $tool) {
+            KanbanGitServer::actingAs($this->user)->tool($tool, [
+                'ticket_id' => $ticket->id, 'description' => $description,
+                'title' => 'Must not change', 'story_points' => 99,
+                'acceptance_criteria' => [['text' => 'Must not replace']],
+            ])->assertHasErrors(['description', 'unsupported', 'acceptance_criteria']);
+            $this->assertSame($before, $ticket->fresh()->getAttributes());
+            $this->assertSame('Separate criterion', $ticket->acceptanceCriteria()->sole()->text);
+            $this->assertDatabaseCount('ticket_worklog_entries', 0);
+        }
+    }
+
+    public static function unsupportedDescriptions(): array
+    {
+        return array_map(fn (array $case): array => [$case[0]], array_filter(self::descriptionCases(), fn (array $case): bool => ! $case[1]));
+    }
+
+    public function test_compatible_descriptions_are_stored_verbatim_and_criteria_remain_separate_and_null_clears(): void
+    {
+        $description = TicketDescriptionFormat::contract()['example'];
+        KanbanGitServer::actingAs($this->user)->tool(CreateTicket::class, [
+            ...$this->createPayload($description), 'acceptance_criteria' => [['text' => 'Separate criterion']],
+        ])->assertOk();
+        $ticket = $this->project->tickets()->sole();
+        $this->assertSame($description, $ticket->description);
+        $this->assertSame('Separate criterion', $ticket->acceptanceCriteria()->sole()->text);
+        $this->assertSame([], TicketDescriptionFormat::unsupportedContent($description));
+        $this->withoutVite();
+        $this->actingAs($this->user)->get(route('projects.tickets.show', [$this->project, $ticket]))
+            ->assertInertia(fn (Assert $page) => $page->where('ticket.description', $description)->where('ticket.acceptance_criteria.0.text', 'Separate criterion'));
+        $process = new Process(['node', 'tests/Fixtures/ticket-description.mjs', '--stored-description'], base_path());
+        $process->setInput(json_encode(['description' => $ticket->description, 'criteria' => $ticket->acceptanceCriteria()->get()->toArray()], JSON_THROW_ON_ERROR));
+        $process->setTimeout(60);
+        $process->run();
+        $this->assertTrue($process->isSuccessful(), $process->getOutput().$process->getErrorOutput());
+        foreach ([UpdateTicketDescription::class, UpdateTicket::class] as $tool) {
+            $updated = "> Quote\n\n**Updated**\n\n```markdown\n- [x] literal example\n```";
+            KanbanGitServer::actingAs($this->user)->tool($tool, ['ticket_id' => $ticket->id, 'description' => $updated])->assertOk()
+                ->assertStructuredContent(fn (AssertableJson $json) => $json->where('data.ticket.description', $updated)->etc());
+            $this->assertSame($updated, $ticket->fresh()->description);
+            KanbanGitServer::actingAs($this->user)->tool($tool, ['ticket_id' => $ticket->id, 'description' => null])->assertOk();
+            $this->assertNull($ticket->fresh()->description);
+            $this->assertSame('Separate criterion', $ticket->acceptanceCriteria()->sole()->text);
+        }
+    }
+
+    public function test_updates_without_description_preserve_legacy_source_and_checklist_identity(): void
+    {
+        $ticket = $this->ticket();
+        $legacy = "## Legacy\n\n- [x] Keep verbatim\n\n<table></table>";
+        $ticket->update(['description' => $legacy]);
+        $criterion = $ticket->acceptanceCriteria()->sole();
+        KanbanGitServer::actingAs($this->user)->tool(UpdateTicket::class, ['ticket_id' => $ticket->id, 'title' => 'Updated title'])
+            ->assertOk();
+        $this->assertSame($legacy, $ticket->fresh()->description);
+        $this->assertSame($criterion->id, $ticket->acceptanceCriteria()->sole()->id);
+        KanbanGitServer::actingAs($this->user)->tool(UpdateTicketDescription::class, ['ticket_id' => $ticket->id])->assertOk();
+        $this->assertSame($legacy, $ticket->fresh()->description);
+        KanbanGitServer::actingAs($this->user)->tool(GetTicket::class, ['ticket_id' => $ticket->id])->assertOk()
+            ->assertStructuredContent(fn (AssertableJson $json) => $json->where('data.ticket.description', $legacy)->etc());
+    }
+
+    private function createPayload(?string $description): array
+    {
+        return [
+            'project_id' => $this->project->id, 'title' => 'Formatted ticket', 'description' => $description,
+            'ticket_type_id' => $this->project->ticketTypes()->where('is_parent', false)->firstOrFail()->id,
+            'ticket_status_id' => $this->project->ticketStatuses()->firstOrFail()->id,
+            'ticket_priority_id' => $this->project->ticketPriorities()->firstOrFail()->id,
+        ];
+    }
+
+    private function ticket(): Ticket
+    {
+        $ticket = Ticket::factory()->create([
+            ...collect($this->createPayload('Original description'))->except('project_id')->all(),
+            'project_id' => $this->project->id, 'ticket_key' => 'CORE-1', 'sequence_number' => 1,
+        ]);
+        $ticket->acceptanceCriteria()->create(['text' => 'Separate criterion', 'checked' => false, 'indent' => 0, 'position' => 1]);
+
+        return $ticket;
+    }
+}

tests/Feature/Mcp/TicketDiscoveryTest.php

@@ -0,0 +1,225 @@
+<?php
+
+namespace Tests\Feature\Mcp;
+
+use App\Actions\ProjectTicketMetadata\InitializeProjectTicketMetadata;
+use App\Mcp\Servers\KanbanGitServer;
+use App\Mcp\Tools\GetProjectConfiguration;
+use App\Mcp\Tools\GetTicket;
+use App\Mcp\Tools\ListProjects;
+use App\Mcp\Tools\SearchTickets;
+use App\Models\BoardColumn;
+use App\Models\Project;
+use App\Models\Team;
+use App\Models\Ticket;
+use App\Models\TicketFieldDefinition;
+use App\Models\TicketStatus;
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Testing\Fluent\AssertableJson;
+use Illuminate\Testing\TestResponse;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Tests\TestCase;
+
+class TicketDiscoveryTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private User $user;
+
+    private Project $project;
+
+    private Project $hidden;
+
+    private Ticket $ticket;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->user = User::factory()->create();
+        $this->project = Project::factory()->create(['key' => 'CORE', 'name' => 'Visible']);
+        $this->hidden = Project::factory()->create(['key' => 'HIDE']);
+        app(InitializeProjectTicketMetadata::class)->handle($this->project);
+        app(InitializeProjectTicketMetadata::class)->handle($this->hidden);
+        $this->syncProjectPermissions($this->project, $this->user, ['view']);
+        $this->ticket = $this->newTicket($this->project, 1, ['title' => 'Special needle', 'description' => 'First description', 'assignee_user_id' => $this->user->id]);
+        $this->newTicket($this->project, 2, ['title' => 'Other title', 'description' => 'Needle in description', 'parent_ticket_id' => $this->ticket->id]);
+        $this->newTicket($this->hidden, 1, ['title' => 'Hidden needle']);
+    }
+
+    public function test_exact_key_and_existing_id_lookup_work_and_hidden_tickets_are_denied(): void
+    {
+        foreach ([['ticket_id' => $this->ticket->id], ['ticket_key' => 'CORE-1']] as $input) {
+            KanbanGitServer::actingAs($this->user)->tool(GetTicket::class, $input)->assertOk()
+                ->assertStructuredContent(fn (AssertableJson $json) => $json->where('data.ticket.id', $this->ticket->id)->etc());
+        }
+        KanbanGitServer::actingAs($this->user)->tool(GetTicket::class, ['ticket_key' => 'HIDE-1'])->assertHasErrors(['cannot view']);
+        KanbanGitServer::actingAs($this->user)->tool(GetTicket::class, ['ticket_key' => 'CORE-99'])->assertHasErrors(['not found']);
+    }
+
+    #[DataProvider('invalidSelectors')]
+    public function test_key_lookup_requires_exactly_one_valid_selector(array $input): void
+    {
+        KanbanGitServer::actingAs($this->user)->tool(GetTicket::class, $input)->assertHasErrors();
+    }
+
+    public static function invalidSelectors(): array
+    {
+        return [
+            [[]], [['ticket_key' => 'CORE']], [['ticket_key' => 'core-1']], [['ticket_key' => 'CORE-0']],
+            [['ticket_key' => 'CORE-1', 'ticket_id' => 1]], [['ticket_key' => null]],
+        ];
+    }
+
+    public function test_search_combines_filters_and_paginates_only_visible_tickets_with_compact_payloads(): void
+    {
+        KanbanGitServer::actingAs($this->user)->tool(SearchTickets::class, ['query' => 'needle', 'per_page' => 1])
+            ->assertOk()->assertStructuredContent(fn (AssertableJson $json) => $json
+            ->where('data.0.id', $this->ticket->id)->count('data', 1)
+            ->where('data.0.status.id', $this->ticket->ticket_status_id)
+            ->missing('data.0.description')->missing('data.0.project')
+            ->where('meta.total', 2)->where('meta.last_page', 2)->where('meta.has_more_pages', true)->etc());
+        KanbanGitServer::actingAs($this->user)->tool(SearchTickets::class, ['query' => 'needle', 'page' => 2, 'per_page' => 1])
+            ->assertOk()->assertStructuredContent(fn (AssertableJson $json) => $json
+            ->where('data.0.ticket_key', 'CORE-2')->where('meta.current_page', 2)->where('meta.has_more_pages', false)->etc());
+        KanbanGitServer::actingAs($this->user)->tool(SearchTickets::class, [
+            'project_id' => $this->project->id, 'ticket_key' => 'CORE-1', 'ticket_status_id' => $this->ticket->ticket_status_id,
+            'ticket_type_id' => $this->ticket->ticket_type_id, 'assignee_user_id' => $this->user->id, 'parent_ticket_id' => null,
+        ])->assertOk()->assertStructuredContent(fn (AssertableJson $json) => $json->count('data', 1)->where('data.0.id', $this->ticket->id)->etc());
+        KanbanGitServer::actingAs($this->user)->tool(SearchTickets::class, ['parent_ticket_id' => $this->ticket->id, 'assignee_user_id' => null])
+            ->assertOk()->assertStructuredContent(fn (AssertableJson $json) => $json->count('data', 1)->where('data.0.ticket_key', 'CORE-2')->etc());
+        KanbanGitServer::actingAs($this->user)->tool(SearchTickets::class, ['ticket_type_id' => $this->hidden->ticketTypes()->firstOrFail()->id])
+            ->assertOk()->assertStructuredContent(fn (AssertableJson $json) => $json->count('data', 0)->etc());
+        KanbanGitServer::actingAs($this->user)->tool(SearchTickets::class, ['project_id' => $this->hidden->id])->assertHasErrors(['cannot view']);
+        KanbanGitServer::actingAs($this->user)->tool(SearchTickets::class, ['page' => 10])->assertOk()
+            ->assertStructuredContent(fn (AssertableJson $json) => $json->count('data', 0)->where('meta.total', 2)->etc());
+    }
+
+    public function test_search_returns_tickets_without_a_status(): void
+    {
+        $this->ticket->update(['ticket_status_id' => null]);
+        KanbanGitServer::actingAs($this->user)->tool(SearchTickets::class, ['ticket_key' => 'CORE-1'])->assertOk()
+            ->assertStructuredContent(fn (AssertableJson $json) => $json->where('data.0.id', $this->ticket->id)
+                ->where('data.0.ticket_status_id', null)->where('data.0.status', null)->etc());
+    }
+
+    public function test_literal_search_does_not_expand_sql_wildcards(): void
+    {
+        $this->ticket->update(['title' => 'A 50%_! literal']);
+        KanbanGitServer::actingAs($this->user)->tool(SearchTickets::class, ['query' => '%_!'])
+            ->assertOk()->assertStructuredContent(fn (AssertableJson $json) => $json->count('data', 1)->where('data.0.id', $this->ticket->id)->etc());
+    }
+
+    public function test_project_list_is_compact_paginated_and_independent_of_assignments_with_team_and_global_access(): void
+    {
+        $this->ticket->update(['assignee_user_id' => null]);
+        KanbanGitServer::actingAs($this->user)->tool(ListProjects::class)->assertOk()
+            ->assertStructuredContent(fn (AssertableJson $json) => $json->count('data', 1)->where('data.0.key', 'CORE')->missing('data.0.template_state')->where('meta.total', 1)->etc());
+        $team = Team::factory()->create();
+        $team->users()->attach($this->user);
+        $this->syncProjectPermissions($this->hidden, $team, ['view']);
+        KanbanGitServer::actingAs($this->user)->tool(ListProjects::class, ['per_page' => 1, 'page' => 2])->assertOk()
+            ->assertStructuredContent(fn (AssertableJson $json) => $json->where('data.0.id', $this->hidden->id)->where('meta.total', 2)->etc());
+        $global = User::factory()->create();
+        $this->syncGlobalPermissions($global, ['admin']);
+        KanbanGitServer::actingAs($global)->tool(SearchTickets::class)->assertOk()
+            ->assertStructuredContent(fn (AssertableJson $json) => $json->where('meta.total', 3)->etc());
+        KanbanGitServer::actingAs(User::factory()->create())->tool(ListProjects::class)->assertOk()
+            ->assertStructuredContent(fn (AssertableJson $json) => $json->count('data', 0)->where('meta.total', 0)->etc());
+    }
+
+    public function test_configuration_returns_current_workflow_and_allowed_people_without_full_resources(): void
+    {
+        $first = $this->project->ticketStatuses()->firstOrFail();
+        $column = BoardColumn::factory()->for($this->project)->create(['position' => 1]);
+        $second = TicketStatus::factory()->for($this->project)->for($column)->create(['position' => 1]);
+        TicketFieldDefinition::factory()->for($this->project)->create(['field_type' => 'user', 'position' => 1]);
+        $first->allowedTargetStatuses()->sync([$second->id]);
+        $first->update(['name' => 'Fresh workflow']);
+        $otherViewer = User::factory()->create();
+        $this->syncProjectPermissions($this->project, $otherViewer, ['view']);
+        User::factory()->create();
+        KanbanGitServer::actingAs($this->user)->tool(GetProjectConfiguration::class, ['project_id' => $this->project->id, 'people_per_page' => 1])
+            ->assertOk()->assertStructuredContent(fn (AssertableJson $json) => $json
+            ->where('data.project.id', $this->project->id)->missing('data.project.template_state')
+            ->where('data.permissions.can_write', false)->where('data.permissions.can_change_author', false)
+            ->where('data.ticket_statuses.0.id', $first->id)->where('data.ticket_statuses.0.slug', 'fresh-workflow')
+            ->where('data.ticket_statuses.0.allowed_target_status_ids', [$second->id])
+            ->where('data.ticket_statuses.0.board_column_id', $first->board_column_id)
+            ->has('data.ticket_field_definitions.0.field_type')->has('data.ticket_types.0.is_parent')->has('data.ticket_priorities.0.id')->has('data.board_columns.0.position')
+            ->count('data.people', 1)->missing('data.people.0.email')->missing('data.people.0.avatar')
+            ->where('meta.people.total', 2)->etc());
+        KanbanGitServer::actingAs($this->user)->tool(GetProjectConfiguration::class, ['project_id' => $this->project->id, 'people_page' => 2, 'people_per_page' => 1])
+            ->assertOk()->assertStructuredContent(fn (AssertableJson $json) => $json->where('data.people.0.id', $otherViewer->id)->etc());
+        KanbanGitServer::actingAs($this->user)->tool(GetProjectConfiguration::class, ['project_id' => $this->hidden->id])->assertHasErrors(['cannot view']);
+    }
+
+    public function test_numeric_project_keys_and_configured_column_order_are_supported(): void
+    {
+        $this->project->update(['key' => '42']);
+        $this->ticket->update(['ticket_key' => '42-1']);
+        KanbanGitServer::actingAs($this->user)->tool(GetTicket::class, ['ticket_key' => '42-1'])->assertOk();
+        KanbanGitServer::actingAs($this->user)->tool(SearchTickets::class, ['ticket_key' => '42-1'])->assertOk()
+            ->assertStructuredContent(fn (AssertableJson $json) => $json->where('data.0.id', $this->ticket->id)->etc());
+        $later = BoardColumn::factory()->for($this->project)->create(['position' => 2]);
+        $earlier = BoardColumn::factory()->for($this->project)->create(['position' => 1]);
+        $laterStatus = TicketStatus::factory()->for($this->project)->for($later)->create(['position' => 1]);
+        $earlierStatus = TicketStatus::factory()->for($this->project)->for($earlier)->create(['position' => 1]);
+        KanbanGitServer::actingAs($this->user)->tool(GetProjectConfiguration::class, ['project_id' => $this->project->id])->assertOk()
+            ->assertStructuredContent(fn (AssertableJson $json) => $json
+                ->where('data.board_columns.0.id', $earlier->id)
+                ->where('data.ticket_statuses.1.id', $earlierStatus->id)
+                ->where('data.ticket_statuses.2.id', $laterStatus->id)->etc());
+    }
+
+    public function test_pagination_limits_and_missing_projects_are_validated(): void
+    {
+        foreach ([ListProjects::class, SearchTickets::class] as $tool) {
+            KanbanGitServer::actingAs($this->user)->tool($tool, ['per_page' => 101])->assertHasErrors();
+            KanbanGitServer::actingAs($this->user)->tool($tool, ['page' => 0])->assertHasErrors();
+        }
+        KanbanGitServer::actingAs($this->user)->tool(GetProjectConfiguration::class, ['project_id' => 999])->assertHasErrors(['not found']);
+        KanbanGitServer::actingAs($this->user)->tool(GetProjectConfiguration::class, ['project_id' => $this->project->id, 'people_per_page' => 101])->assertHasErrors();
+    }
+
+    public function test_application_key_discovers_new_schemas_and_completes_refinement_without_browser_login(): void
+    {
+        $this->syncProjectPermissions($this->project, $this->user, ['write']);
+        $this->withApplicationKey($this->user);
+        $response = $this->postJson('/mcp/kanbangit', ['jsonrpc' => '2.0', 'id' => 1, 'method' => 'tools/list', 'params' => []])->assertOk();
+        $tools = collect($response->json('result.tools'))->keyBy('name');
+        foreach (['list_projects', 'search_tickets', 'get_project_configuration'] as $name) {
+            $this->assertTrue($tools[$name]['annotations']['readOnlyHint']);
+        }
+        $this->assertSame(['ticket_id'], $tools['update_ticket']['inputSchema']['required']);
+        $this->assertArrayHasKey('ticket_key', $tools['get_ticket']['inputSchema']['properties']);
+        $this->assertFalse($tools['update_ticket']['annotations']['destructiveHint']);
+        $this->rpc('update_ticket', ['ticket_id' => $this->ticket->id, 'title' => 'Refined via MCP', 'description' => 'Refinement', 'acceptance_criteria' => [['text' => 'Real criterion']]]);
+        $ticket = $this->rpc('get_ticket', ['ticket_key' => 'CORE-1'])->json('result.structuredContent.data.ticket');
+        $this->assertSame('Refined via MCP', $ticket['title']);
+        $this->assertSame('Real criterion', $ticket['acceptance_criteria'][0]['text']);
+        $this->rpc('update_ticket', ['ticket_id' => $this->ticket->id, 'acceptance_criteria' => [['id' => $ticket['acceptance_criteria'][0]['id'], 'text' => 'Criterion checked', 'checked' => true]]]);
+        $target = TicketStatus::factory()->for($this->project)->create(['position' => 2]);
+        $this->ticket->ticketStatus->allowedTargetStatuses()->sync([$target->id]);
+        $this->rpc('move_ticket_status', ['ticket_id' => $this->ticket->id, 'ticket_status_id' => $target->id]);
+        $this->assertSame($target->id, $this->ticket->fresh()->ticket_status_id);
+    }
+
+    private function rpc(string $name, array $arguments): TestResponse
+    {
+        return $this->postJson('/mcp/kanbangit', [
+            'jsonrpc' => '2.0', 'id' => 2, 'method' => 'tools/call', 'params' => ['name' => $name, 'arguments' => $arguments],
+        ])->assertOk()->assertJsonPath('result.isError', false);
+    }
+
+    private function newTicket(Project $project, int $sequence, array $attributes = []): Ticket
+    {
+        return Ticket::factory()->create([
+            'project_id' => $project->id, 'ticket_key' => "{$project->key}-{$sequence}", 'sequence_number' => $sequence,
+            'ticket_status_id' => $project->ticketStatuses()->firstOrFail()->id,
+            'ticket_type_id' => $project->ticketTypes()->where('is_parent', $sequence === 1)->firstOrFail()->id,
+            'ticket_priority_id' => $project->ticketPriorities()->firstOrFail()->id,
+            ...$attributes,
+        ]);
+    }
+}

tests/Feature/Mcp/UpdateTicketTest.php

@@ -0,0 +1,235 @@
+<?php
+
+namespace Tests\Feature\Mcp;
+
+use App\Actions\ProjectTicketMetadata\InitializeProjectTicketMetadata;
+use App\Actions\Tickets\Support\AcceptanceCriteriaChecklistMapper;
+use App\Actions\Tickets\SyncProjectTicketFieldValues;
+use App\Mcp\Servers\KanbanGitServer;
+use App\Mcp\Tools\GetTicket;
+use App\Mcp\Tools\UpdateTicket;
+use App\Models\Project;
+use App\Models\Ticket;
+use App\Models\TicketFieldDefinition;
+use App\Models\TicketPriority;
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Testing\Fluent\AssertableJson;
+use Laravel\Mcp\Server\Testing\TestResponse;
+use PHPUnit\Framework\Attributes\DataProvider;
+use RuntimeException;
+use Tests\TestCase;
+
+class UpdateTicketTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private User $user;
+
+    private Project $project;
+
+    private Ticket $ticket;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->user = User::factory()->create();
+        $this->project = Project::factory()->create(['key' => 'CORE']);
+        app(InitializeProjectTicketMetadata::class)->handle($this->project);
+        $this->syncProjectPermissions($this->project, $this->user, ['admin']);
+        $this->ticket = $this->newTicket(['description' => 'Original', 'story_points' => 5, 'author_user_id' => $this->user->id]);
+        AcceptanceCriteriaChecklistMapper::syncTicket($this->ticket, [
+            ['text' => 'First', 'checked' => false, 'indent' => 0],
+            ['text' => 'Second', 'checked' => true, 'indent' => 0],
+        ]);
+    }
+
+    public function test_partial_update_and_no_op_preserve_checklist_ids_and_unrelated_fields(): void
+    {
+        $before = AcceptanceCriteriaChecklistMapper::fromModelsWithIds($this->ticket->acceptanceCriteria()->get());
+        $this->updateTicket(['title' => 'Refined'])->assertOk()->assertStructuredContent(fn (AssertableJson $json) => $json
+            ->where('data.ticket.description', 'Original')->where('data.ticket.story_points', 5)
+            ->where('data.ticket.acceptance_criteria', $before)->where('meta.updated', true)->etc());
+        $this->updateTicket(['title' => 'Refined'])->assertOk()->assertStructuredContent(fn (AssertableJson $json) => $json->where('meta.updated', false)->etc());
+        $this->assertSame(1, $this->ticket->worklogEntries()->count());
+        $this->assertSame('Refined', $this->ticket->fresh()->title);
+    }
+
+    public function test_checklist_replacement_adds_reorders_indents_checks_and_removes_by_identity(): void
+    {
+        $before = AcceptanceCriteriaChecklistMapper::fromModelsWithIds($this->ticket->acceptanceCriteria()->get());
+        $replacement = [
+            ['text' => 'New root', 'checked' => false, 'indent' => 0],
+            ['id' => $before[1]['id'], 'text' => 'Second edited', 'checked' => false, 'indent' => 1],
+            ['id' => $before[0]['id'], 'text' => 'First', 'checked' => true, 'indent' => 0],
+        ];
+        $this->updateTicket(['acceptance_criteria' => $replacement])->assertOk();
+        $after = AcceptanceCriteriaChecklistMapper::fromModelsWithIds($this->ticket->acceptanceCriteria()->get());
+        $this->assertNotContains($after[0]['id'], array_column($before, 'id'));
+        $this->assertSame($replacement[1], ['id' => $after[1]['id'], 'text' => $after[1]['text'], 'checked' => $after[1]['checked'], 'indent' => $after[1]['indent']]);
+        $this->assertSame($before[0]['id'], $after[2]['id']);
+        $this->updateTicket(['acceptance_criteria' => $after])->assertOk()->assertStructuredContent(fn (AssertableJson $json) => $json->where('meta.updated', false)->etc());
+        $this->updateTicket(['acceptance_criteria' => [$after[2]]])->assertOk();
+        KanbanGitServer::actingAs($this->user)->tool(GetTicket::class, ['ticket_key' => 'CORE-1'])
+            ->assertOk()->assertStructuredContent(fn (AssertableJson $json) => $json->count('data.ticket.acceptance_criteria', 1)->where('data.ticket.acceptance_criteria.0.id', $before[0]['id'])->etc());
+        $this->updateTicket(['acceptance_criteria' => []])->assertOk();
+        $this->assertSame(0, $this->ticket->acceptanceCriteria()->count());
+    }
+
+    public function test_scalar_null_and_custom_field_replacement_have_explicit_clear_semantics(): void
+    {
+        $number = TicketFieldDefinition::factory()->for($this->project)->create(['field_type' => 'number']);
+        $person = TicketFieldDefinition::factory()->for($this->project)->create(['field_type' => 'user', 'position' => 2]);
+        $this->updateTicket(['field_values' => [
+            ['ticket_field_definition_id' => $number->id, 'value_number' => 0],
+            ['ticket_field_definition_id' => $person->id, 'value_user_id' => $this->user->id],
+        ]])->assertOk();
+        $this->updateTicket(['description' => null, 'story_points' => null, 'assignee_user_id' => null, 'author_user_id' => null])->assertOk();
+        $this->assertSame(2, $this->ticket->fieldValues()->count());
+        $this->assertNull($this->ticket->fresh()->description);
+        $this->assertNull($this->ticket->fresh()->story_points);
+        $this->updateTicket(['field_values' => [['ticket_field_definition_id' => $number->id, 'value_number' => 3]]])->assertOk();
+        $this->assertSame(1, $this->ticket->fieldValues()->count());
+        $this->updateTicket(['field_values' => []])->assertOk();
+        $this->assertSame(0, $this->ticket->fieldValues()->count());
+    }
+
+    #[DataProvider('invalidInputs')]
+    public function test_invalid_payload_does_not_partially_change_ticket(array $input): void
+    {
+        $before = $this->ticket->fresh()->getAttributes();
+        $this->updateTicket(['title' => 'Must not change', ...$input])->assertHasErrors();
+        $this->assertSame($before, $this->ticket->fresh()->getAttributes());
+        $this->assertSame(0, $this->ticket->worklogEntries()->count());
+        $this->assertSame(2, $this->ticket->acceptanceCriteria()->count());
+    }
+
+    public static function invalidInputs(): array
+    {
+        return [
+            'null title' => [['title' => null]],
+            'null type' => [['ticket_type_id' => null]],
+            'null priority' => [['ticket_priority_id' => null]],
+            'null blocked state' => [['is_blocked' => null]],
+            'invalid criterion text' => [['acceptance_criteria' => [['text' => []]]]],
+            'null criteria' => [['acceptance_criteria' => null]],
+            'null fields' => [['field_values' => null]],
+            'invalid criterion' => [['acceptance_criteria' => [['id' => 99999, 'text' => 'Foreign']]]],
+            'blank criterion' => [['acceptance_criteria' => [['text' => '   ']]]],
+            'skipped indent' => [['acceptance_criteria' => [['text' => 'Child', 'indent' => 1]]]],
+            'negative points' => [['story_points' => -1]],
+            'missing blocker' => [['is_blocked' => true]],
+            'status not editable' => [['ticket_status_id' => 999]],
+        ];
+    }
+
+    public function test_foreign_and_duplicate_criterion_ids_are_rejected_atomically(): void
+    {
+        $other = $this->newTicket(['ticket_key' => 'CORE-2', 'sequence_number' => 2]);
+        AcceptanceCriteriaChecklistMapper::syncTicket($other, [['text' => 'Other', 'checked' => false, 'indent' => 0]]);
+        $foreign = $other->acceptanceCriteria()->firstOrFail()->id;
+        $this->updateTicket(['title' => 'Rejected', 'acceptance_criteria' => [['id' => $foreign, 'text' => 'Steal']]])->assertHasErrors();
+        $id = $this->ticket->acceptanceCriteria()->firstOrFail()->id;
+        $this->updateTicket(['acceptance_criteria' => [['id' => $id, 'text' => 'One'], ['id' => $id, 'text' => 'Two']]])->assertHasErrors();
+        $this->assertSame('Original', $this->ticket->fresh()->description);
+        $this->assertSame('Other', $other->acceptanceCriteria()->firstOrFail()->text);
+    }
+
+    public function test_project_read_and_write_permissions_and_author_rules_are_enforced(): void
+    {
+        $this->syncProjectPermissions($this->project, $this->user, ['view']);
+        $this->updateTicket(['title' => 'Denied'])->assertHasErrors(['cannot update tickets']);
+        $this->syncProjectPermissions($this->project, $this->user, ['write']);
+        $this->updateTicket(['title' => 'Allowed'])->assertOk();
+        $this->updateTicket(['author_user_id' => null])->assertHasErrors(['Only project admins']);
+        $this->syncProjectPermissions($this->project, $this->user, []);
+        $this->updateTicket(['title' => 'Denied'])->assertHasErrors(['cannot update tickets']);
+        $this->assertSame('Allowed', $this->ticket->fresh()->title);
+    }
+
+    public function test_invalid_people_foreign_metadata_custom_types_and_parent_relations_are_rejected(): void
+    {
+        $hiddenUser = User::factory()->create();
+        $this->updateTicket(['assignee_user_id' => $hiddenUser->id])->assertHasErrors(['person']);
+        $this->updateTicket(['author_user_id' => $hiddenUser->id])->assertHasErrors(['person']);
+        $otherProject = Project::factory()->create();
+        app(InitializeProjectTicketMetadata::class)->handle($otherProject);
+        $this->updateTicket(['ticket_type_id' => $otherProject->ticketTypes()->firstOrFail()->id])->assertHasErrors();
+        $this->updateTicket(['ticket_priority_id' => $otherProject->ticketPriorities()->firstOrFail()->id])->assertHasErrors();
+        $foreignTicket = Ticket::factory()->for($otherProject)->create();
+        $this->updateTicket(['parent_ticket_id' => $foreignTicket->id])->assertHasErrors();
+        $field = TicketFieldDefinition::factory()->for($this->project)->create(['field_type' => 'user']);
+        $this->updateTicket(['field_values' => [['ticket_field_definition_id' => $field->id, 'value_user_id' => $hiddenUser->id]]])->assertHasErrors(['person']);
+        $this->updateTicket(['field_values' => [['ticket_field_definition_id' => $field->id, 'value_number' => 2]]])->assertHasErrors(['field type']);
+        $this->updateTicket(['parent_ticket_id' => $this->ticket->id])->assertHasErrors(['own parent']);
+        $task = $this->newTicket(['ticket_key' => 'CORE-2', 'sequence_number' => 2]);
+        $this->updateTicket(['parent_ticket_id' => $task->id])->assertHasErrors(['parent-enabled']);
+        $parentType = $this->project->ticketTypes()->where('is_parent', true)->firstOrFail();
+        $this->updateTicket(['ticket_type_id' => $parentType->id])->assertOk();
+        $task->update(['parent_ticket_id' => $this->ticket->id, 'ticket_type_id' => $parentType->id]);
+        $this->updateTicket(['parent_ticket_id' => $task->id])->assertHasErrors(['descendants']);
+        $this->updateTicket(['ticket_type_id' => $this->project->ticketTypes()->where('is_parent', false)->firstOrFail()->id])->assertHasErrors(['child tickets']);
+    }
+
+    public function test_all_editable_scalar_fields_accept_valid_project_values(): void
+    {
+        $person = User::factory()->create();
+        $this->syncProjectPermissions($this->project, $person, ['view']);
+        $parentType = $this->project->ticketTypes()->where('is_parent', true)->firstOrFail();
+        $parent = $this->newTicket(['ticket_key' => 'CORE-2', 'sequence_number' => 2, 'ticket_type_id' => $parentType->id]);
+        $priority = TicketPriority::factory()->for($this->project)->create(['position' => 2]);
+        $input = [
+            'title' => 'All scalar fields', 'description' => 'Updated description',
+            'ticket_type_id' => $parentType->id, 'ticket_priority_id' => $priority->id,
+            'assignee_user_id' => $person->id, 'author_user_id' => $person->id,
+            'parent_ticket_id' => $parent->id, 'story_points' => 0,
+            'is_blocked' => true, 'blocked_comment' => 'Dependency',
+        ];
+        $this->updateTicket($input)->assertOk();
+        foreach ($input as $field => $value) {
+            $this->assertSame($value, $this->ticket->fresh()->getAttribute($field));
+        }
+        $this->assertSame(1, $this->ticket->worklogEntries()->count());
+        $this->updateTicket(['parent_ticket_id' => null])->assertOk();
+        $this->assertNull($this->ticket->fresh()->parent_ticket_id);
+    }
+
+    public function test_blocker_validation_uses_preserved_state(): void
+    {
+        $this->updateTicket(['is_blocked' => true, 'blocked_comment' => 'Waiting'])->assertOk();
+        $this->updateTicket(['title' => 'Still blocked'])->assertOk();
+        $this->updateTicket(['blocked_comment' => null])->assertHasErrors(['blocker comment']);
+        $this->updateTicket(['is_blocked' => false])->assertOk();
+        $this->assertNull($this->ticket->fresh()->blocked_comment);
+    }
+
+    public function test_action_failure_rolls_back_scalars_checklist_and_worklog(): void
+    {
+        $this->mock(SyncProjectTicketFieldValues::class)->shouldReceive('handle')->once()->andThrow(new RuntimeException('Sync failed'));
+        try {
+            $this->updateTicket(['title' => 'Rollback', 'acceptance_criteria' => []]);
+            $this->fail('Expected action failure.');
+        } catch (RuntimeException $exception) {
+            $this->assertSame('Sync failed', $exception->getMessage());
+        }
+        $this->assertNotSame('Rollback', $this->ticket->fresh()->title);
+        $this->assertSame(2, $this->ticket->acceptanceCriteria()->count());
+        $this->assertSame(0, $this->ticket->worklogEntries()->count());
+    }
+
+    private function updateTicket(array $input): TestResponse
+    {
+        return KanbanGitServer::actingAs($this->user)->tool(UpdateTicket::class, ['ticket_id' => $this->ticket->id, ...$input]);
+    }
+
+    private function newTicket(array $attributes = []): Ticket
+    {
+        return Ticket::factory()->create([
+            'project_id' => $this->project->id, 'ticket_key' => 'CORE-1', 'sequence_number' => 1,
+            'ticket_status_id' => $this->project->ticketStatuses()->firstOrFail()->id,
+            'ticket_type_id' => $this->project->ticketTypes()->where('is_parent', false)->firstOrFail()->id,
+            'ticket_priority_id' => $this->project->ticketPriorities()->firstOrFail()->id,
+            ...$attributes,
+        ]);
+    }
+}

tests/Fixtures/ticket-description-browser.mjs

@@ -3,6 +3,7 @@ import TicketDescriptionEditor from '../../resources/js/components/tickets/Ticke
 import TicketDescription from '../../resources/js/components/tickets/TicketDescription.vue';
 import { createLocalization } from '../../resources/js/lib/localization';
 import '../../resources/css/app.css';
+import descriptionFormat from '../../resources/js/lib/ticket-description-format.json';
 
 const original = 'First line\nSecond line\n\n**Existing bold**';
 const state = reactive({
@@ -199,6 +200,33 @@ try {
     state.value =
         '# Plan\n\nUse **bold** and *italic* formatting, lists and [links](https://example.test).\n\n- Create ticket\n- Save description\n\n> Keep existing descriptions readable.';
     await tick();
+    state.value = descriptionFormat.example;
+    await tick();
+    assert(
+        document.querySelector('#description h2')?.textContent === 'Goal',
+        'MCP example opens formatted in WYSIWYG',
+    );
+    assert(
+        document.querySelector('#description strong')?.textContent ===
+            'context',
+        'MCP emphasis is formatted',
+    );
+    assert(
+        document.querySelectorAll('#description li').length === 2,
+        'MCP ordinary lists render',
+    );
+    assert(
+        !document.querySelector('textarea#description'),
+        'MCP example avoids source fallback',
+    );
+    state.value = '## Legacy\n\n- [ ] Criterion';
+    await tick();
+    assert(
+        document.querySelector('textarea#description')?.value === state.value,
+        'Legacy task checkboxes retain original source',
+    );
+    state.value = descriptionFormat.example;
+    await tick();
     state.result =
         'Browser checks passed: formatting, undo/redo, source round-trip, links, errors, disabled state, reset, clearing and legacy content.';
 } catch (error) {

tests/Fixtures/ticket-description-cases.json

@@ -0,0 +1,167 @@
+[
+    {
+        "name": "plain text",
+        "value": "München 🚀 & details\nSecond line",
+        "supported": true
+    },
+    {
+        "name": "formatting",
+        "value": "# Title\n\n**Bold** and *italic* and ~~strike~~\n\n- One\n  - Nested\n\n3. Third\n4. Fourth\n\n> Quote\n\n`inline`\n\n```js\n<tag>\n```\n\n[Link](https://example.test/path)\n\n---",
+        "supported": true
+    },
+    {
+        "name": "setext heading",
+        "value": "Title\n===\n\nText",
+        "supported": true
+    },
+    {
+        "name": "safe links",
+        "value": "[http](http://example.test) [mail](mailto:test@example.test) [root](/projects/1) [fragment](#part)",
+        "supported": true
+    },
+    {
+        "name": "reference link",
+        "value": "[Guide][ref]\n\n[ref]: https://example.test",
+        "supported": true
+    },
+    {
+        "name": "autolinks",
+        "value": "<https://example.test> and https://example.test and test@example.test",
+        "supported": true
+    },
+    {
+        "name": "literal code",
+        "value": "```markdown\n- [x] Done\n<table></table>\n![image](bad)\n[a](javascript:bad)\n```\n\n`- [ ] task`\n\n    <script>example</script>",
+        "supported": true
+    },
+    {
+        "name": "escaped text",
+        "value": "\\<tag> and \\![image](https://example.test)\n\n- \\[x] ordinary list",
+        "supported": true
+    },
+    {
+        "name": "entities",
+        "value": "&lt;img src=x onerror=alert(1)&gt;",
+        "supported": true
+    },
+    {
+        "name": "empty",
+        "value": "",
+        "supported": true
+    },
+    {
+        "name": "task",
+        "value": "## Plan\n\n- [ ] Criteria",
+        "supported": false
+    },
+    {
+        "name": "checked",
+        "value": "- [x] Done",
+        "supported": false
+    },
+    {
+        "name": "nested task",
+        "value": "> 1. [X] Done",
+        "supported": false
+    },
+    {
+        "name": "table",
+        "value": "| A | B |\n| - | - |\n| a | b |",
+        "supported": false
+    },
+    {
+        "name": "html",
+        "value": "<script>alert(1)</script>",
+        "supported": false
+    },
+    {
+        "name": "inline html",
+        "value": "Text <b>bold</b>",
+        "supported": false
+    },
+    {
+        "name": "html comment",
+        "value": "<!-- comment -->",
+        "supported": false
+    },
+    {
+        "name": "image",
+        "value": "![Image](https://example.test/image.png)",
+        "supported": false
+    },
+    {
+        "name": "reference image",
+        "value": "![alt][img]\n\n[img]: https://example.test/image.png",
+        "supported": false
+    },
+    {
+        "name": "javascript",
+        "value": "[unsafe](javascript:alert%281%29)",
+        "supported": false
+    },
+    {
+        "name": "data",
+        "value": "[unsafe](data:text/html,test)",
+        "supported": false
+    },
+    {
+        "name": "protocol relative",
+        "value": "[unsafe](//evil.test)",
+        "supported": false
+    },
+    {
+        "name": "relative",
+        "value": "[unsafe](other/page)",
+        "supported": false
+    },
+    {
+        "name": "unsafe reference",
+        "value": "[unsafe][ref]\n\n[ref]: javascript:alert(1)",
+        "supported": false
+    },
+    {
+        "name": "malformed https",
+        "value": "[unsafe](https://)",
+        "supported": false
+    },
+    {
+        "name": "backslash",
+        "value": "[unsafe](https://example.test/a\\\\b)",
+        "supported": false
+    },
+    {
+        "name": "invalid ipv6",
+        "value": "[unsafe](https://[invalid]/)",
+        "supported": false
+    },
+    {
+        "name": "encoded backslash",
+        "value": "[unsafe](https://example.test/%5cpath)",
+        "supported": false
+    },
+    {
+        "name": "encoded whitespace",
+        "value": "[unsafe](https://example.test/a%20b)",
+        "supported": false
+    },
+    {
+        "name": "invalid encoding",
+        "value": "[unsafe](https://example.test/%ff)",
+        "supported": false
+    },
+    {
+        "name": "too large port",
+        "value": "[unsafe](https://example.test:99999)",
+        "supported": false
+    },
+    {
+        "name": "ipv6",
+        "value": "[safe](https://[::1]/path)",
+        "supported": true
+    },
+    {
+        "name": "international domain",
+        "value": "[safe](https://münchen.example/🚀)",
+        "supported": true
+    }
+]

tests/Fixtures/ticket-description.mjs

@@ -1,4 +1,5 @@
 import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import vue from '@vitejs/plugin-vue';
@@ -11,7 +12,24 @@ const serve = process.argv.includes('--serve');
 const server = await createServer({
     configFile: false,
     plugins: [vue(), ...(serve ? [tailwind()] : [])],
+    optimizeDeps: {
+        include: [
+            '@tiptap/core',
+            '@tiptap/pm/state',
+            '@tiptap/vue-3',
+            '@tiptap/markdown',
+            '@tiptap/starter-kit',
+        ],
+    },
     resolve: {
+        dedupe: [
+            'vue',
+            '@tiptap/core',
+            '@tiptap/pm',
+            'prosemirror-state',
+            'prosemirror-model',
+            'prosemirror-view',
+        ],
         alias: {
             '@': fileURLToPath(new URL('../../resources/js', import.meta.url)),
         },
@@ -56,6 +74,58 @@ if (serve) {
             renderToString(
                 createSSRApp({ render: () => h(Description, { description }) }),
             );
+        const cases = JSON.parse(
+            readFileSync(
+                new URL('./ticket-description-cases.json', import.meta.url),
+                'utf8',
+            ),
+        );
+        const contract = JSON.parse(
+            readFileSync(
+                new URL(
+                    '../../resources/js/lib/ticket-description-format.json',
+                    import.meta.url,
+                ),
+                'utf8',
+            ),
+        );
+        cases.push({
+            name: 'MCP contract example',
+            value: contract.example,
+            supported: true,
+        });
+        for (const item of cases) {
+            assert.equal(
+                supportsVisualDescription(item.value),
+                item.supported,
+                item.name,
+            );
+            if (item.supported) {
+                assert.ok(parseDescription(item.value));
+                await render(item.value);
+            }
+        }
+        if (process.argv.includes('--stored-description')) {
+            const saved = JSON.parse(readFileSync(0, 'utf8'));
+            assert.equal(supportsVisualDescription(saved.description), true);
+            const html = await render(saved.description);
+            assert.match(html, /<h2>Goal<\/h2>/);
+            assert.match(html, /<strong>context<\/strong>/);
+            assert.equal(
+                parseDescription(saved.description).content[0].type,
+                'heading',
+            );
+            for (const criterion of saved.criteria) {
+                assert.ok(
+                    !html.includes(criterion.text),
+                    'Criteria stay in the separate checklist',
+                );
+            }
+        }
+        const exampleHtml = await render(contract.example);
+        assert.match(exampleHtml, /<h2>Goal<\/h2>/);
+        assert.match(exampleHtml, /<strong>context<\/strong>/);
+        assert.doesNotMatch(exampleHtml, /acceptance_criteria|task checkboxes/);
         const markdown =
             '# Title\n\n**Bold** and *italic* and ~~strike~~\n\n- One\n  - Nested\n\n3. Third\n4. Fourth\n\n> Quote\n\n`inline`\n\n```js\n<tag>\n```\n\n[Link](https://example.test/path)\n\n---';
         assert.equal(supportsVisualDescription(markdown), true);