semantics

frontend/src/components/Navbar.svelte

@@ -1,12 +1,15 @@
 <!-- [DEF:Navbar:Component] -->
 <!--
-@UX_STATE: Loading -> Default
-
 @COMPLEXITY: 3
 @SEMANTICS: navbar, navigation, header, layout
-@PURPOSE:   Main navigation bar for the application.
-@LAYER:     UI
-@RELATION:  USES -> auth
+@PURPOSE: Main navigation bar for the application.
+@LAYER: UI
+@RELATION: BINDS_TO -> [authStore]
+@RELATION: BINDS_TO -> [i18n]
+@RELATION: DEPENDS_ON -> [LanguageSwitcher]
+
+@UX_STATE: Idle -> Navigation links and settings menus are visible.
+@UX_STATE: Authenticated -> User identity and logout action are rendered.
 -->
 <script>
     import { page } from '$app/state';

frontend/src/components/Toast.svelte

@@ -1,13 +1,13 @@
 <!-- [DEF:Toast:Component] -->
 <!--
-@COMPLEXITY: 1
+@COMPLEXITY: 2
 @SEMANTICS: toast, notification, feedback, ui
 @PURPOSE: Displays transient notifications (toasts) in the bottom-right corner.
 @LAYER: UI
-@RELATION: DEPENDS_ON -> frontend/src/lib/toasts.js
+@RELATION: BINDS_TO -> toasts
 
-@PROPS: None
-@EVENTS: None
+@UX_STATE: Empty -> Toast viewport stays mounted without visible notifications.
+@UX_STATE: Visible -> Active toast items render with type-specific emphasis.
 -->
 <script>
     // [SECTION: IMPORTS]

frontend/src/components/__tests__/task_log_viewer.test.js

@@ -3,7 +3,7 @@
 // @SEMANTICS: tests, task-log, viewer, mount, components
 // @PURPOSE: Unit tests for TaskLogViewer component by mounting it and observing the DOM.
 // @LAYER: UI (Tests)
-// @RELATION: VERIFIES -> TaskLogViewer
+// @RELATION: DEPENDS_ON -> [TaskLogViewer]
 // @INVARIANT: Duplicate logs are never appended. Polling only active for in-progress tasks.
 // @TEST_CONTRACT: TaskLogViewerPropsAndLogStream -> RenderedLogTimeline
 // @TEST_SCENARIO: historical_and_realtime_merge -> Historical logs render and realtime logs append without duplication.
@@ -139,7 +139,7 @@ describe('TaskLogViewer Component', () => {
         expect(() => screen.getByText(/Duplicate log entry/)).not.toThrow();
     });
 
-    // @TEST_FIXTURE valid_viewer
+    // @TEST_FIXTURE: valid_viewer -> INLINE_JSON
     it('fetches and displays historical logs in modal mode under valid_viewer fixture', async () => {
         getTaskLogsMock.mockResolvedValue([
             { timestamp: '2024-01-01T00:00:00', level: 'INFO', message: 'Modal log entry' }
@@ -155,7 +155,7 @@ describe('TaskLogViewer Component', () => {
         expect(getTaskLogs).toHaveBeenCalledWith('task-123');
     });
 
-    // @TEST_EDGE no_task_id
+    // @TEST_EDGE: no_task_id -> Null taskId does not trigger fetch.
     it('does not fetch logs if taskId is null', () => {
         render(TaskLogViewer, { inline: true, taskId: null });
         expect(getTaskLogs).not.toHaveBeenCalled();
@@ -167,4 +167,4 @@ describe('TaskLogViewer Component', () => {
         expect(component).toBeDefined();
     });
 });
-// [/DEF:frontend.src.components.__tests__.task_log_viewer:Module]
+// [/DEF:TaskLogViewerTest:Module]

frontend/src/components/git/__tests__/git_manager.unfinished_merge.integration.test.js

@@ -3,7 +3,7 @@
 // @SEMANTICS: git-manager, unfinished-merge, dialog, integration-test
 // @PURPOSE: Protect unresolved-merge dialog contract in GitManager pull flow.
 // @LAYER: UI Tests
-// @RELATION: VERIFIES -> frontend/src/components/git/GitManager.svelte
+// @RELATION: DEPENDS_ON -> [GitManager]
 
 import { describe, it, expect } from 'vitest';
 import fs from 'node:fs';
@@ -40,4 +40,4 @@ describe('GitManager unfinished merge dialog contract', () => {
     expect(source).toContain('$t.git?.unfinished_merge?.copy_commands');
   });
 });
-// [/DEF:frontend.src.components.git.__tests__.git_manager_unfinished_merge_integration:Module]
+// [/DEF:GitManagerUnfinishedMergeIntegrationTest:Module]

frontend/src/components/llm/__tests__/provider_config.integration.test.js

@@ -3,7 +3,7 @@
 // @SEMANTICS: llm, provider-config, integration-test, edit-flow, delete-flow
 // @PURPOSE: Protect edit and delete interaction contracts in LLM provider settings UI.
 // @LAYER: UI Tests
-// @RELATION: VERIFIES -> ProviderConfig
+// @RELATION: DEPENDS_ON -> [ProviderConfig]
 // @INVARIANT: Edit action keeps explicit click handler and opens normalized edit form.
 
 import { describe, it, expect } from 'vitest';
@@ -16,7 +16,7 @@ const COMPONENT_PATH = path.resolve(
 );
 
 // [DEF:provider_config_edit_contract_tests:Function]
-// @RELATION: USES -> App
+// @RELATION: BINDS_TO -> [ProviderConfigIntegrationTest]
 // @COMPLEXITY: 3
 // @PURPOSE: Validate edit and delete handler wiring plus normalized edit form state mapping.
 // @PRE: ProviderConfig component source exists in expected path.
@@ -58,4 +58,4 @@ describe('ProviderConfig edit interaction contract', () => {
   });
 });
 // [/DEF:provider_config_edit_contract_tests:Function]
-// [/DEF:frontend.src.components.llm.__tests__.provider_config_integration:Module]
+// [/DEF:ProviderConfigIntegrationTest:Module]