@shepai/cli 1.59.0 → 1.61.0

package/dist/src/presentation/web/components/features/skills/skill-list.stories.js

@@ -0,0 +1,124 @@
+import { fn } from '@storybook/test';
+import { SkillList } from './skill-list.js';
+const meta = {
+    title: 'Features/SkillList',
+    component: SkillList,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+    },
+    args: {
+        onSkillSelect: fn(),
+    },
+};
+export default meta;
+/* ---------------------------------------------------------------------------
+ * Data fixtures
+ * ------------------------------------------------------------------------- */
+const workflowSkills = [
+    {
+        name: 'shep-kit:implement',
+        displayName: 'implement',
+        description: 'Validate specs and autonomously execute implementation tasks.',
+        category: 'Workflow',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+    {
+        name: 'shep-kit:plan',
+        displayName: 'plan',
+        description: 'Create implementation plan and task breakdown.',
+        category: 'Workflow',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+    {
+        name: 'shep-kit:research',
+        displayName: 'research',
+        description: 'Analyze technical approach, evaluate libraries, document decisions.',
+        category: 'Workflow',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+];
+const codeGenSkills = [
+    {
+        name: 'shep:ui-component',
+        displayName: 'ui-component',
+        description: 'Use when creating, modifying, or reviewing web UI components.',
+        context: 'fork',
+        allowedTools: 'Read, Write, Bash, Edit, Glob',
+        category: 'Code Generation',
+        source: 'project',
+        body: '',
+        resources: [{ name: 'references', fileCount: 7 }],
+    },
+];
+const analysisSkills = [
+    {
+        name: 'architecture-reviewer',
+        displayName: 'architecture-reviewer',
+        description: 'Use when making architectural decisions or reviewing PRs.',
+        context: 'fork',
+        category: 'Analysis',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+    {
+        name: 'cross-validate-artifacts',
+        displayName: 'cross-validate-artifacts',
+        description: 'Cross-validate documentation and artifacts for consistency.',
+        category: 'Analysis',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+];
+const referenceSkills = [
+    {
+        name: 'shadcn-ui',
+        displayName: 'shadcn-ui',
+        description: 'Complete shadcn/ui component library patterns.',
+        category: 'Reference',
+        source: 'project',
+        body: '',
+        resources: [{ name: 'references', fileCount: 3 }],
+    },
+    {
+        name: 'vercel-react-best-practices',
+        displayName: 'vercel-react-best-practices',
+        description: 'React and Next.js performance optimization guidelines.',
+        category: 'Reference',
+        source: 'global',
+        body: '',
+        resources: [{ name: 'references', fileCount: 4 }],
+    },
+];
+const allSkills = [
+    ...workflowSkills,
+    ...codeGenSkills,
+    ...analysisSkills,
+    ...referenceSkills,
+];
+/* ---------------------------------------------------------------------------
+ * Stories
+ * ------------------------------------------------------------------------- */
+export const Default = {
+    args: {
+        skills: allSkills,
+    },
+};
+export const SingleCategory = {
+    args: {
+        skills: workflowSkills,
+    },
+};
+export const Empty = {
+    args: {
+        skills: [],
+    },
+};

package/dist/src/presentation/web/components/features/skills/skills-page-client.d.ts

@@ -0,0 +1,6 @@
+import type { SkillData } from '../../../lib/skills.js';
+export interface SkillsPageClientProps {
+    skills: SkillData[];
+}
+export declare function SkillsPageClient({ skills }: SkillsPageClientProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=skills-page-client.d.ts.map

package/dist/src/presentation/web/components/features/skills/skills-page-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-page-client.d.ts","sourceRoot":"","sources":["../../../../../../../src/presentation/web/components/features/skills/skills-page-client.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE7D,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAeD,wBAAgB,gBAAgB,CAAC,EAAE,MAAM,EAAE,EAAE,qBAAqB,2CAiFjE"}

package/dist/src/presentation/web/components/features/skills/skills-page-client.js

@@ -0,0 +1,52 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useMemo } from 'react';
+import { Search, Puzzle } from 'lucide-react';
+import { Input } from '../../ui/input.js';
+import { Button } from '../../ui/button.js';
+import { PageHeader } from '../../common/page-header/index.js';
+import { EmptyState } from '../../common/empty-state/index.js';
+import { SkillList } from './skill-list.js';
+import { CategoryFilter } from './category-filter.js';
+import { SkillDetailDrawer } from './skill-detail-drawer.js';
+function computeCategoryCounts(skills) {
+    const counts = {
+        Workflow: 0,
+        'Code Generation': 0,
+        Analysis: 0,
+        Reference: 0,
+    };
+    for (const skill of skills) {
+        counts[skill.category]++;
+    }
+    return counts;
+}
+export function SkillsPageClient({ skills }) {
+    const [searchQuery, setSearchQuery] = useState('');
+    const [activeCategory, setActiveCategory] = useState(null);
+    const [selectedSkill, setSelectedSkill] = useState(null);
+    const categoryCounts = useMemo(() => computeCategoryCounts(skills), [skills]);
+    const filteredSkills = useMemo(() => {
+        const query = searchQuery.toLowerCase();
+        return skills.filter((skill) => {
+            if (activeCategory && skill.category !== activeCategory)
+                return false;
+            if (query) {
+                const matchesName = skill.name.toLowerCase().includes(query);
+                const matchesDescription = skill.description.toLowerCase().includes(query);
+                if (!matchesName && !matchesDescription)
+                    return false;
+            }
+            return true;
+        });
+    }, [skills, searchQuery, activeCategory]);
+    const clearFilters = () => {
+        setSearchQuery('');
+        setActiveCategory(null);
+    };
+    // No skills installed at all
+    if (skills.length === 0) {
+        return (_jsxs("div", { className: "flex flex-col gap-6 p-6", children: [_jsx(PageHeader, { title: "Skills", description: "Claude Code skills installed in this project" }), _jsx(EmptyState, { icon: _jsx(Puzzle, { className: "size-10" }), title: "No skills found", description: "No Claude Code skills are installed. Add skills to .claude/skills/ to get started." })] }));
+    }
+    return (_jsxs("div", { className: "flex flex-col gap-6 p-6", children: [_jsx(PageHeader, { title: "Skills", description: "Claude Code skills installed in this project" }), _jsxs("div", { className: "relative", children: [_jsx(Search, { className: "text-muted-foreground absolute top-1/2 left-3 size-4 -translate-y-1/2" }), _jsx(Input, { placeholder: "Search skills...", value: searchQuery, onChange: (e) => setSearchQuery(e.target.value), className: "pl-9" })] }), _jsx(CategoryFilter, { activeCategory: activeCategory, onCategoryChange: setActiveCategory, counts: categoryCounts }), filteredSkills.length > 0 ? (_jsx(SkillList, { skills: filteredSkills, onSkillSelect: setSelectedSkill })) : (_jsx(EmptyState, { icon: _jsx(Search, { className: "size-10" }), title: "No matching skills", description: "No skills match your current search and filter criteria.", action: _jsx(Button, { variant: "outline", onClick: clearFilters, children: "Clear filters" }) })), _jsx(SkillDetailDrawer, { skill: selectedSkill, onClose: () => setSelectedSkill(null) })] }));
+}

package/dist/src/presentation/web/components/features/skills/skills-page-client.stories.d.ts

@@ -0,0 +1,16 @@
+import type { StoryObj } from '@storybook/react';
+import { SkillsPageClient } from './skills-page-client.js';
+declare const meta: {
+    title: string;
+    component: typeof SkillsPageClient;
+    tags: string[];
+    parameters: {
+        layout: string;
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Default: Story;
+export declare const Empty: Story;
+export declare const ManySkills: Story;
+//# sourceMappingURL=skills-page-client.stories.d.ts.map

package/dist/src/presentation/web/components/features/skills/skills-page-client.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-page-client.stories.d.ts","sourceRoot":"","sources":["../../../../../../../src/presentation/web/components/features/skills/skills-page-client.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGxD,QAAA,MAAM,IAAI;;;;;;;CAO+B,CAAC;AAE1C,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAwKnC,eAAO,MAAM,OAAO,EAAE,KAIrB,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAInB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,KAIxB,CAAC"}

package/dist/src/presentation/web/components/features/skills/skills-page-client.stories.js

@@ -0,0 +1,186 @@
+import { SkillsPageClient } from './skills-page-client.js';
+const meta = {
+    title: 'Features/SkillsPageClient',
+    component: SkillsPageClient,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'fullscreen',
+    },
+};
+export default meta;
+/* ---------------------------------------------------------------------------
+ * Data fixtures
+ * ------------------------------------------------------------------------- */
+const sampleSkills = [
+    {
+        name: 'shep-kit:implement',
+        displayName: 'implement',
+        description: 'Validate specs and autonomously execute implementation tasks with status tracking.',
+        category: 'Workflow',
+        source: 'project',
+        body: '## Usage\n\nRun /shep-kit:implement after planning is complete.',
+        resources: [],
+    },
+    {
+        name: 'shep-kit:plan',
+        displayName: 'plan',
+        description: 'Create implementation plan and task breakdown.',
+        category: 'Workflow',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+    {
+        name: 'shep-kit:research',
+        displayName: 'research',
+        description: 'Analyze technical approach, evaluate libraries, document decisions.',
+        category: 'Workflow',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+    {
+        name: 'shep:ui-component',
+        displayName: 'ui-component',
+        description: 'Use when creating, modifying, or reviewing web UI components.',
+        context: 'fork',
+        allowedTools: 'Read, Write, Bash, Edit, Glob',
+        category: 'Code Generation',
+        source: 'project',
+        body: '',
+        resources: [
+            { name: 'references', fileCount: 7 },
+            { name: 'templates', fileCount: 3 },
+        ],
+    },
+    {
+        name: 'architecture-reviewer',
+        displayName: 'architecture-reviewer',
+        description: 'Use when making architectural decisions, planning features, or reviewing PRs.',
+        context: 'fork',
+        category: 'Analysis',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+    {
+        name: 'cross-validate-artifacts',
+        displayName: 'cross-validate-artifacts',
+        description: 'Cross-validate documentation and artifacts for consistency.',
+        category: 'Analysis',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+    {
+        name: 'shadcn-ui',
+        displayName: 'shadcn-ui',
+        description: 'Complete shadcn/ui component library patterns and implementation.',
+        category: 'Reference',
+        source: 'project',
+        body: '',
+        resources: [{ name: 'references', fileCount: 3 }],
+    },
+    {
+        name: 'vercel-react-best-practices',
+        displayName: 'vercel-react-best-practices',
+        description: 'React and Next.js performance optimization guidelines from Vercel Engineering.',
+        category: 'Reference',
+        source: 'global',
+        body: '',
+        resources: [{ name: 'references', fileCount: 4 }],
+    },
+];
+const manySkills = [
+    ...sampleSkills,
+    {
+        name: 'shep-kit:commit-pr',
+        displayName: 'commit-pr',
+        description: 'Use when ready to commit, push, and create a PR with CI verification.',
+        category: 'Workflow',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+    {
+        name: 'shep-kit:new-feature',
+        displayName: 'new-feature',
+        description: 'Use when starting any new feature, functionality, or enhancement.',
+        category: 'Workflow',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+    {
+        name: 'shep-kit:new-feature-fast',
+        displayName: 'new-feature-fast',
+        description: 'Fast-track feature creation that collapses new-feature, research, and planning.',
+        category: 'Workflow',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+    {
+        name: 'shep-kit:merged',
+        displayName: 'merged',
+        description: 'Use after a PR has been merged to clean up branches.',
+        category: 'Workflow',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+    {
+        name: 'mermaid-diagrams',
+        displayName: 'mermaid-diagrams',
+        description: 'Comprehensive guide for creating software diagrams using Mermaid syntax.',
+        category: 'Reference',
+        source: 'project',
+        body: '',
+        resources: [{ name: 'references', fileCount: 2 }],
+    },
+    {
+        name: 'react-flow',
+        displayName: 'react-flow',
+        description: 'React Flow for workflow visualization with custom nodes and edges.',
+        category: 'Reference',
+        source: 'project',
+        body: '',
+        resources: [],
+    },
+    {
+        name: 'tsp-model',
+        displayName: 'tsp-model',
+        description: 'Use when creating, modifying, or documenting TypeSpec domain models.',
+        category: 'Reference',
+        source: 'project',
+        body: '',
+        resources: [{ name: 'references', fileCount: 5 }],
+    },
+    {
+        name: 'find-skills',
+        displayName: 'find-skills',
+        description: 'Helps users discover and install agent skills.',
+        category: 'Reference',
+        source: 'global',
+        body: '',
+        resources: [],
+    },
+];
+/* ---------------------------------------------------------------------------
+ * Stories
+ * ------------------------------------------------------------------------- */
+export const Default = {
+    args: {
+        skills: sampleSkills,
+    },
+};
+export const Empty = {
+    args: {
+        skills: [],
+    },
+};
+export const ManySkills = {
+    args: {
+        skills: manySkills,
+    },
+};

package/dist/src/presentation/web/components/layouts/app-sidebar/app-sidebar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-sidebar.d.ts","sourceRoot":"","sources":["../../../../../../../src/presentation/web/components/layouts/app-sidebar/app-sidebar.tsx"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAG/E,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;IACnC,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;CAClC;AAED,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,mBAAmB,GACpB,EAAE,eAAe,2CA+FjB"}
+{"version":3,"file":"app-sidebar.d.ts","sourceRoot":"","sources":["../../../../../../../src/presentation/web/components/layouts/app-sidebar/app-sidebar.tsx"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAI/E,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;IACnC,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;CAClC;AAED,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,mBAAmB,GACpB,EAAE,eAAe,2CAuGjB"}

package/dist/src/presentation/web/components/layouts/app-sidebar/app-sidebar.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { usePathname } from 'next/navigation';
-import { Home, Wrench, Plus } from 'lucide-react';
+import { Home, Wrench, Puzzle, Plus } from 'lucide-react';
 import { Sidebar, SidebarHeader, SidebarContent, SidebarFooter, SidebarMenu, SidebarMenuItem, SidebarMenuButton, SidebarRail, useSidebar, } from '../../ui/sidebar.js';
 import { ScrollArea } from '../../ui/scroll-area.js';
 import { SidebarNavItem } from '../../common/sidebar-nav-item/index.js';
@@ -12,6 +12,7 @@ import { FeatureStatusGroup } from '../../common/feature-status-group/index.js';
 import { SidebarSectionHeader } from '../../common/sidebar-section-header/index.js';
 import { featureStatusConfig, featureStatusOrder } from '../../common/feature-status-config.js';
 import { useDeferredMount } from '../../../hooks/use-deferred-mount.js';
+import { featureFlags } from '../../../lib/feature-flags.js';
 export function AppSidebar({ features, onNewFeature, onFeatureClick, onFeaturesFolderClick, onFeaturesMenuClick, }) {
     const pathname = usePathname();
     const { state } = useSidebar();
@@ -26,7 +27,7 @@ export function AppSidebar({ features, onNewFeature, onFeatureClick, onFeaturesF
                                             'flex min-w-0 flex-1 items-center gap-2 overflow-hidden px-2',
                                             'transition-opacity duration-200 ease-out',
                                             expandedVisible ? 'opacity-100' : 'opacity-0',
-                                        ].join(' '), "aria-hidden": !expandedVisible, children: [_jsx(ShepLogo, { className: "shrink-0", size: 20 }), _jsx("span", { className: "truncate text-sm font-semibold tracking-tight", children: "Shep" })] })) : null, _jsx(SidebarCollapseToggle, { className: "shrink-0 transition-all duration-200" })] }) }), _jsx(SidebarNavItem, { icon: Home, label: "Control Center", href: "/", active: pathname === '/' }), _jsx(SidebarNavItem, { icon: Wrench, label: "Tools", href: "/tools", active: pathname === '/tools' })] }) }), _jsx(SidebarContent, { children: showExpanded ? (_jsxs("div", { className: [
+                                        ].join(' '), "aria-hidden": !expandedVisible, children: [_jsx(ShepLogo, { className: "shrink-0", size: 20 }), _jsx("span", { className: "truncate text-sm font-semibold tracking-tight", children: "Shep" })] })) : null, _jsx(SidebarCollapseToggle, { className: "shrink-0 transition-all duration-200" })] }) }), _jsx(SidebarNavItem, { icon: Home, label: "Control Center", href: "/", active: pathname === '/' }), _jsx(SidebarNavItem, { icon: Wrench, label: "Tools", href: "/tools", active: pathname === '/tools' }), featureFlags.skills ? (_jsx(SidebarNavItem, { icon: Puzzle, label: "Skills", href: "/skills", active: pathname === '/skills' })) : null] }) }), _jsx(SidebarContent, { children: showExpanded ? (_jsxs("div", { className: [
                         'min-w-0 overflow-hidden transition-opacity duration-200 ease-out',
                         '[&_[data-sidebar=group-label]]:!mt-0 [&_[data-sidebar=group-label]]:!opacity-100 [&_[data-sidebar=group-label]]:!transition-none',
                         expandedVisible ? 'opacity-100' : 'opacity-0',

package/dist/src/presentation/web/hooks/use-notifications.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-notifications.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/web/hooks/use-notifications.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,sBAAsB;IACrC,wBAAwB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,sBAAsB,EAAE,sBAAsB,CAAC;CAChD;AA4CD,wBAAgB,gBAAgB,IAAI,sBAAsB,CAgEzD"}
+{"version":3,"file":"use-notifications.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/web/hooks/use-notifications.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,sBAAsB;IACrC,wBAAwB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,sBAAsB,EAAE,sBAAsB,CAAC;CAChD;AA4CD,wBAAgB,gBAAgB,IAAI,sBAAsB,CAgEzD"}

package/dist/src/presentation/web/hooks/use-notifications.js

@@ -3,7 +3,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { toast } from 'sonner';
 import { NotificationEventType, NotificationSeverity } from '../../../../packages/core/src/domain/generated/output.js';
 import { useAgentEventsContext } from './agent-events-provider.js';
-import { useSound } from './use-sound.js';
+import { useSoundAction } from './use-sound-action.js';
 const SEVERITY_TO_TOAST = {
     [NotificationSeverity.Success]: 'success',
     [NotificationSeverity.Error]: 'error',
@@ -34,23 +34,23 @@ function dispatchBrowserNotification(event) {
         icon: '/favicon-light.svg',
     });
 }
-const SEVERITY_TO_SOUND = {
-    [NotificationSeverity.Success]: 'celebration',
-    [NotificationSeverity.Error]: 'caution',
-    [NotificationSeverity.Warning]: 'notification',
-    [NotificationSeverity.Info]: 'button',
+const SEVERITY_TO_ACTION = {
+    [NotificationSeverity.Success]: 'notification-success',
+    [NotificationSeverity.Error]: 'notification-error',
+    [NotificationSeverity.Warning]: 'notification-warning',
+    [NotificationSeverity.Info]: 'notification-info',
 };
 export function useNotifications() {
     const { events } = useAgentEventsContext();
-    const successSound = useSound('celebration', { volume: 0.5 });
-    const errorSound = useSound('caution', { volume: 0.5 });
-    const warningSound = useSound('notification', { volume: 0.5 });
-    const infoSound = useSound('button', { volume: 0.5 });
-    const soundsByName = useMemo(() => ({
-        celebration: successSound,
-        caution: errorSound,
-        notification: warningSound,
-        button: infoSound,
+    const successSound = useSoundAction('notification-success');
+    const errorSound = useSoundAction('notification-error');
+    const warningSound = useSoundAction('notification-warning');
+    const infoSound = useSoundAction('notification-info');
+    const soundsByAction = useMemo(() => ({
+        'notification-success': successSound,
+        'notification-error': errorSound,
+        'notification-warning': warningSound,
+        'notification-info': infoSound,
     }), [successSound, errorSound, warningSound, infoSound]);
     const [browserPermissionState, setBrowserPermissionState] = useState(() => {
         if (typeof globalThis.Notification === 'undefined')
@@ -75,10 +75,10 @@ export function useNotifications() {
             }
             dispatchToast(event);
             dispatchBrowserNotification(event);
-            const soundName = SEVERITY_TO_SOUND[event.severity];
-            soundsByName[soundName]?.play();
+            const actionName = SEVERITY_TO_ACTION[event.severity];
+            soundsByAction[actionName]?.play();
         }
-    }, [events, soundsByName]);
+    }, [events, soundsByAction]);
     const requestBrowserPermission = useCallback(async () => {
         if (typeof globalThis.Notification === 'undefined')
             return;

package/dist/src/presentation/web/hooks/use-sound-action.d.ts

@@ -0,0 +1,100 @@
+import type { UseSoundResult } from './use-sound.js';
+/** Maps semantic UI actions to their sound name and volume. */
+export declare const SOUND_ACTION_MAP: {
+    readonly navigate: {
+        readonly sound: "tap_01";
+        readonly volume: 0.2;
+    };
+    readonly 'menu-item': {
+        readonly sound: "tap_01";
+        readonly volume: 0.2;
+    };
+    readonly select: {
+        readonly sound: "select";
+        readonly volume: 0.3;
+    };
+    readonly 'toggle-on': {
+        readonly sound: "toggle_on";
+        readonly volume: 0.3;
+    };
+    readonly 'toggle-off': {
+        readonly sound: "toggle_off";
+        readonly volume: 0.3;
+    };
+    readonly click: {
+        readonly sound: "tap_01";
+        readonly volume: 0.3;
+    };
+    readonly cancel: {
+        readonly sound: "transition_down";
+        readonly volume: 0.3;
+    };
+    readonly expand: {
+        readonly sound: "swipe";
+        readonly volume: 0.3;
+    };
+    readonly collapse: {
+        readonly sound: "swipe";
+        readonly volume: 0.3;
+    };
+    readonly 'menu-open': {
+        readonly sound: "select";
+        readonly volume: 0.3;
+    };
+    readonly copy: {
+        readonly sound: "select";
+        readonly volume: 0.3;
+    };
+    readonly 'drawer-open': {
+        readonly sound: "transition_up";
+        readonly volume: 0.4;
+    };
+    readonly 'drawer-close': {
+        readonly sound: "transition_down";
+        readonly volume: 0.4;
+    };
+    readonly submit: {
+        readonly sound: "button";
+        readonly volume: 0.4;
+    };
+    readonly approve: {
+        readonly sound: "celebration";
+        readonly volume: 0.5;
+    };
+    readonly reject: {
+        readonly sound: "caution";
+        readonly volume: 0.5;
+    };
+    readonly create: {
+        readonly sound: "transition_up";
+        readonly volume: 0.5;
+    };
+    readonly delete: {
+        readonly sound: "transition_down";
+        readonly volume: 0.5;
+    };
+    readonly 'notification-success': {
+        readonly sound: "celebration";
+        readonly volume: 0.5;
+    };
+    readonly 'notification-error': {
+        readonly sound: "caution";
+        readonly volume: 0.5;
+    };
+    readonly 'notification-warning': {
+        readonly sound: "notification";
+        readonly volume: 0.5;
+    };
+    readonly 'notification-info': {
+        readonly sound: "button";
+        readonly volume: 0.5;
+    };
+};
+/** Union of all semantic action names available in the sound system. */
+export type SoundAction = keyof typeof SOUND_ACTION_MAP;
+/**
+ * Returns `{ play, stop, isPlaying }` for the given semantic action.
+ * Sound name and volume are resolved from `SOUND_ACTION_MAP`.
+ */
+export declare function useSoundAction(action: SoundAction): UseSoundResult;
+//# sourceMappingURL=use-sound-action.d.ts.map

package/dist/src/presentation/web/hooks/use-sound-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-sound-action.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/web/hooks/use-sound-action.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAMlD,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8B4C,CAAC;AAE1E,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAExD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,CAGlE"}

package/dist/src/presentation/web/hooks/use-sound-action.js

@@ -0,0 +1,42 @@
+'use client';
+import { useSound } from './use-sound.js';
+/* ------------------------------------------------------------------ */
+/*  Sound Action Map — single source of truth for action → sound      */
+/* ------------------------------------------------------------------ */
+/** Maps semantic UI actions to their sound name and volume. */
+export const SOUND_ACTION_MAP = {
+    // Navigation (volume 0.2) — subtle taps for frequent interactions
+    navigate: { sound: 'tap_01', volume: 0.2 },
+    'menu-item': { sound: 'tap_01', volume: 0.2 },
+    // Toggles & selections (volume 0.3) — moderate feedback
+    select: { sound: 'select', volume: 0.3 },
+    'toggle-on': { sound: 'toggle_on', volume: 0.3 },
+    'toggle-off': { sound: 'toggle_off', volume: 0.3 },
+    click: { sound: 'tap_01', volume: 0.3 },
+    cancel: { sound: 'transition_down', volume: 0.3 },
+    expand: { sound: 'swipe', volume: 0.3 },
+    collapse: { sound: 'swipe', volume: 0.3 },
+    'menu-open': { sound: 'select', volume: 0.3 },
+    copy: { sound: 'select', volume: 0.3 },
+    // Drawers & transitions (volume 0.4) — noticeable transitions
+    'drawer-open': { sound: 'transition_up', volume: 0.4 },
+    'drawer-close': { sound: 'transition_down', volume: 0.4 },
+    submit: { sound: 'button', volume: 0.4 },
+    // Significant actions (volume 0.5) — prominent feedback
+    approve: { sound: 'celebration', volume: 0.5 },
+    reject: { sound: 'caution', volume: 0.5 },
+    create: { sound: 'transition_up', volume: 0.5 },
+    delete: { sound: 'transition_down', volume: 0.5 },
+    'notification-success': { sound: 'celebration', volume: 0.5 },
+    'notification-error': { sound: 'caution', volume: 0.5 },
+    'notification-warning': { sound: 'notification', volume: 0.5 },
+    'notification-info': { sound: 'button', volume: 0.5 },
+};
+/**
+ * Returns `{ play, stop, isPlaying }` for the given semantic action.
+ * Sound name and volume are resolved from `SOUND_ACTION_MAP`.
+ */
+export function useSoundAction(action) {
+    const { sound, volume } = SOUND_ACTION_MAP[action];
+    return useSound(sound, { volume });
+}

package/dist/src/presentation/web/hooks/use-sound-action.stories.d.ts

@@ -0,0 +1,6 @@
+import type { Meta, StoryObj } from '@storybook/react';
+declare const meta: Meta;
+export default meta;
+type Story = StoryObj;
+export declare const Catalog: Story;
+//# sourceMappingURL=use-sound-action.stories.d.ts.map

package/dist/src/presentation/web/hooks/use-sound-action.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-sound-action.stories.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/web/hooks/use-sound-action.stories.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AA8FvD,QAAA,MAAM,IAAI,EAAE,IAIX,CAAC;AAEF,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC;AAEtB,eAAO,MAAM,OAAO,EAAE,KAErB,CAAC"}